Custom Code

Overview

AppNavi supports custom code in several locations. Custom code is written in JavaScript and can be used to extend application and route behavior.

For example, custom code can run when an application launches and modify the page HTML. It can also control the step sequence of a route.

If AppNavi is integrated into a page using the an-loader, the Custom Code API can be executed through the browser console and through the custom code hooks in the AppNavi Portal.

If AppNavi is integrated through the Chrome Extension, custom code can only be executed through the code hooks in the AppNavi Portal. Browser console access is not available for Chrome Extension integrations.

Note: Custom Code is available only when Expert Mode is enabled for your tenant.

The API methods are available through the following object:

window.appnaviApi

Where Custom Code Can Run

Custom code can run through AppNavi Portal hooks and, depending on the integration method, through the browser console.

Safe Coding Guidelines

Warning: Custom code can change live page behavior and directly affect customers. Test changes in a non-production environment, use a limited audience where possible, and maintain a rollback path before publishing.

Follow these guidelines when developing and testing custom code:

• Validate selectors and returned elements before reading their properties or modifying the DOM.
• Avoid exposing access tokens, user claims, personal data, or other secrets in console output.
• Keep custom code scoped to the intended application, route, and step. Remove event listeners and timers that are no longer required.
• Handle asynchronous API calls using promise rejection handling or try...catch blocks.
• Confirm that a failure in custom code does not prevent the host application from being used or block navigation and data entry.

Common Recipes

• Hide or show the avatar:
  Use application.hideAvatar() and application.showAvatar().

• Set the user context:
  Use application.setGuestUserId(), setTargetAudienceConditions(), setDepartment(), or setOrganizationalUnit() as applicable.

• Control guidance:
  Use route.startRoute(), route.stopRoute(), and route.playStep() to start, stop, or move through a route.

• Respond to step lifecycle events:
  In Custom Code V2, register handlers for onBeforeSearch, onElementFound, onElementNotFound, onBeforeRender, and onElementLost.

• Dispatch analytics events:
  Use the User Behavior Monitoring (UBM) and Custom Push Event APIs described in the API Reference.

Related Documentation

• AppNavi Guide API — Internal documentation link placeholder
• End User Authentication — Internal documentation link placeholder
• Error Handling and Custom Event Dispatching — Internal documentation link placeholder

API Reference

window.appnaviApi

The methods and events documented below are available through unless a specific section states otherwise.