Custom Code
AppNavi provides for the use of custom code in various places. Custom code statements are implemented in JavaScript. For example, custom code can be executed when an application is launched to make changes to the HTML of a page. Furthermore, it is possible to intervene in the step sequence of a route. If AppNavi has been integrated into a page using the an-loader, the custom code API is executable via the browser console as well as via the custom code hooks in the AppNavi Portal. If AppNavi was integrated into a page via the Chrome Extension, access is only possible via the code hooks in the AppNavi Portal and not via console.
Note: Custom Code is only available if you have enabled Expert Mode in your tenant.
The API methods are made available through the following object: window.appnaviApi
Utils
The Utils class provides certain helper functions:
- findElementsByText(text, rootElement): This function traverses the HTML and returns elements with a given InnerText. If no _rootElement _parameter was specified, the entire document is searched. For example, if you want to search for all elements with the innerText "Gmail" to hide the first element, this can be realized as follows:
window.appnaviApi.utils.findElementsByText('Gmail')[0].style.display = 'none';
ANQuery
AppNavi integrates its own distribution of jQuery. Through the anQuery implementation, certain functions of jQuery are usable and simplify the handling of DOM objects.
The following example shows how to hide an element in custom code using anQuery.
window.appnaviApi.anQuery('#gb > div > div:nth-child(1) > div > div:nth-child(1) > a').hide();
Application
The application api provides some methods to control the AppNavi avatar behavior.
start :method
This method starts Appnavi in a specified selector. The delay parameter can be set in order to start Appnavi with a delay of milliseconds.
Method Signature
start(configuration)
Arguments
Configuration object contains following property,
Property | Type | Description | Required |
---|---|---|---|
selector | string | The target iFrame in which appnavi is to be started. | yes |
delay | number | The delay in ms until appnavi is started. | no |
Code Sample
var configuration = {selector:'iFrame selector', delay: 100}
window.appnaviApi.application.start(configuration);
console.log('Appnavi started in the selector: ' + configuration.selector);
setGuestUserId :method
This method specifies a unique identifier for a user, which is used, for example, to determine returning users (e.g. in route progress tracking or training feature). For example, the e-mail address can be used as a unique identifier. The User ID cannot be overwritten when Enterprise Authentication is active.
Method Signature
setGuestUserId(configuration)
Arguments
Configuration object contains following property,
Property | Type | Description | Required |
---|---|---|---|
userId | string | The unique id for a specific user. | yes |
Code Sample
var configuration = {userId:'85727577'}
window.appnaviApi.application.setGuestUserId(configuration);
console.log("userId : ", configuration.userId);
setPreferredLanguage :method
This method allows you to set both the preferred content display language and the preferred UI language. This preference overrides the browser's language settings for content and UI of AppNavi.
Method Signature
setPreferredLanguage(configuration)
Arguments
Configuration object contains following property,
Property | Type | Description | Required |
---|---|---|---|
contentLanguage | string | The code of the preferred content language to show (e.g. 'de' or 'en-us'). | no |
uiLanguage | string | The code of the preferred UI language to show (e.g. 'de' or 'en-us'). | no |
Code Sample
var configuration = {contentLanguage:'de', uiLanguage:'de'}
window.appnaviApi.application.setPreferredLanguage(configuration);
console.log("contentLanguage : ",configuration.contentLanguage);
console.log("uiLanguage : ",configuration.uiLanguage);
hideAvatar :method
This method can be used to hide the avatar.
The hideAvatar API only affects the visibility of the avatar, hiding it from view without impacting any other functionality. All other functions associated with the avatar, including those implemented via custom code, will continue to run as usual.
Method Signature
hideAvatar()
Code Sample
window.setTimeout(function () {
window.appnaviApi.application.hideAvatar();
console.log("avatar has been hidden");
})
showAvatar :method
This method can be used to show the avatar.
Method Signature
showAvatar()
Code Sample
window.appnaviApi.application.showAvatar();
console.log("avatar displayed");
getCurrentApplicationId :method
This method returns the id of the current application as a string.
Method Signature
getCurrentApplicationId()
Code Sample
var applicationId = window.appnaviApi.application.getCurrentApplicationId();
console.log('Application id: '+ applicationId );
getCurrentApplication :method
This method returns the current application object.
Method Signature
getCurrentApplication()
Code Sample
var application = window.appnaviApi.application.getCurrentApplication();
console.log("application: ", application)
getCurrentSubscriptionId :method
This method returns the id of the current subscription.
Method Signature
getCurrentSubscriptionId()
Code Sample
var subscriptionId = window.appnaviApi.application.getCurrentSubscriptionId();
console.log('Subscription id: '+ subscriptionId );
getApplicationContainer :method
This method returns the current DOM parent object in which the AppNavi avatar is embedded. In the normal case, this is the DOM element with the global-an-container id.
Method Signature
getApplicationContainer()
Code Sample
var appContainer = window.appnaviApi.application.getApplicationContainer();
console.log('Application Container : '+ appContainer);
setTargetAudienceConditions :method
This method defines the target audiences. Target audiences refer to the filtering of content by means of labels. This method can also be used to filter the classic labels.
Method Signature
setTargetAudienceConditions(configuration)
Arguments
Configuration object contains following property,
Property | Type | Description | Required |
---|---|---|---|
labels | array | The array contain labels as string. | no |
Code Sample
var configuration = {labels:['Administrator', 'Admin']}
window.appnaviApi.application.setTargetAudienceConditions(configuration);
console.log('Labels: '+ configuration.labels );
avatarLoad :event
This event is executed when the AppNavi avatar is fully loaded and displayed in the interface.
Arguments
Parameter | Type | Description |
---|---|---|
appId | string | The application id of the application that was loaded. |
Code Sample
appnavi.event.register("an-avatarLoad", function(event){
var eventDetails = event.detail;
var detailObject = eventDetails.detail;
console.log("avatar loaded on application Id " +detailObject.appId);
});
Announcement
getAvailableNews :method
This method returns a list of all available news for this application. This method is executed asynchronously.
Method Signature
getAvailableNews(configuration)
Arguments
Configuration object contains following property,
Property | Type | Description | Required |
---|---|---|---|
filterByTargetAudience | boolean | Specifies whether the currently set custom labels are to be taken into account in the filtering. If no value is given, no filtering takes place. | no |
Code Sample
var configuration = {filterByTargetAudience:true};
window.appnaviApi.news.getAvailableNews(configuration).then(function(resp){
console.log("Available news are",resp);
})
showAnnouncement :method
This method displays a news article as an announcement. The currently published version is displayed. If a news item is already marked as read in the version, it is not displayed unless the Force parameter is explicitly set to true.
We can display both single and multiple announcements by passing their IDs in an array.
Method Signature
showAnnouncement(configuration)
Arguments
Configuration object contain following properties,
Parameter | Type | Description | Required |
---|---|---|---|
newsId | Array | The id of the news element to be displayed as an announcement. | yes |
force | bool | This parameter specifies whether a news item should be displayed even though it has already been marked as read. The default value is false. | no |
Code Sample
var configuration = {newsId:["e7c515f9","f776a70c","c26b05fd"],force: true}
window.appnaviApi.news.showAnnouncement(configuration);
console.log("Announcement has been shown having id " + configuration.newsId);
showInfo :method
This method displays an announcement-type info as a tooltip. The currently published version will be displayed.
Method Signature
showInfo(configuration)
Arguments
Configuration object contain following properties,
Parameter | Type | Description | Required |
---|---|---|---|
infoId | string | The id of the info element to be displayed. | yes |
filterByTargetAudience | bool | Specifies whether the currently set custom labels are to be taken into account in the filtering. If no value is given, no filtering takes place. | no |
Code Sample
var configuration = {infoId:"cc9993ac", filterByTargetAudience: true}
window.appnaviApi.news.showInfo(configuration);
console.log("Info has been shown having id " + configuration.infoId);
newsShow :event
This event is triggered when a news item is displayed. This only applies to the display in the news area and not to announcements.
Arguments
Parameter | Type | Description |
---|---|---|
newsId | string | The id of the news that was displayed. |
Code Sample
appnavi.event.register("an-newsShow", function(event){
var eventDetails = event.detail;
var detail = eventDetails.detail;
console.log("news displayed having id", detail.newsId);
});
newsRead :event
This event is triggered when a news item is marked as read. This applies to the display in the news area as well as in the announcement window.
Arguments
Parameter | Type | Description |
---|---|---|
newsId | string | The id of the news which was read. |
Code Sample
appnavi.event.register("an-newsRead", function(event){
var eventDetails = event.detail;
var detail = eventDetails.detail;
console.log("news read having id", detail.newsId);
});
announcementShow :event
This event is triggered when the Announcement window is displayed.
Arguments
Parameter | Type | Description |
---|---|---|
newsIds | array of type string | The ids of the news that were displayed in the announcement window. |
Code Sample
appnavi.event.register("an-announcementShow", function(event){
var eventDetails = event.detail;
var detail = eventDetails.detail;
console.log("The ids of the news that were displayed are", detail.newsIds);
});
Hotspots
The hotspot API contains all methods that are relevant for the control of the AppNavi hotspot feature.
getAvailableHotspotCollections :method
This method returns a list of all available hotspot collections for this application. This method is executed asynchronously.
Method Signature
getAvailableHotspotCollections(configuration)
Arguments
Configuration object contains following property,
Property | Type | Description | Required |
---|---|---|---|
filterByTargetAudience | boolean | Specifies whether the currently set custom labels are to be taken into account in the filtering. If no value is given, no filtering takes place. | no |
Code Sample
var configuration = {filterByTargetAudience:true};
window.appnaviApi.hotspot.getAvailableHotspotCollections(configuration).then(function(resp){
console.log("Available hotpspots are",resp);
})
getPageHotspots :method
This method returns a list of hotspots that are displayed on the current page and are visible to the current user, taking into account the target audience.
Method Signature
getPageHotspots()
Code Sample
window.appnaviApi.hotspot.getPageHotspots().then(function(resp){
console.log("Page hotspots are ", resp);
})
hidePageHotspots :method
This method hides the hotspots on the current page.
Method Signature
hidePageHotspots()
Code Sample
window.appnaviApi.hotspot.hidePageHotspots();
console.log('Page hostspot has been hidden' );
showPageHotspots :method
This method displays hotspots which are available on current page that may be hidden with the hideHotspots method. Only elements that fall within the target group range of the current user are displayed.
Method Signature
showPageHotspots()
Code Sample
window.appnaviApi.hotspot.showPageHotspots();
console.log('Page hostspot has been shown' );
hideHotspotItem :method
This method hides a specific hotspot item displayed on the current page.
Method Signature
hideHotspotItem(configuration)
Arguments
Configuration object contains following property,
Property | Type | Description | Required |
---|---|---|---|
hotspotId | string | The id of the hotspot element to be hidden. | yes |
Code Sample
var configuration = {hotspotId:'cdedcd72'};
window.setTimeout(function () {
window.appnaviApi.hotspot.hideHotspotItem(configuration);
console.log('Page hostspot id :'+ configuration.hotspotId +' has been hidden' );
})
showHotspotItem :method
This method shows a specific hotspot item displayed on the current page.
Method Signature
showHotspotItem(configuration)
Arguments
Configuration object contains following property,
Property | Type | Description | Required |
---|---|---|---|
hotspotId | string | The id of the hotspot element to be shown. | yes |
Code Sample
var configuration = {hotspotId:'cdedcd72'};
window.appnaviApi.hotspot.showHotspotItem(configuration);
console.log("Hotspot item has been shown having id " + configuration.hotspotId);
startHotspotAction :method
This method starts the action (e.g. display a hint, start a route, etc.) associated with the specified hotspot.
Method Signature
startHotspotAction(configuration)
Arguments
Configuration object contains following property,
Property | Type | Description | Required |
---|---|---|---|
hotspotId | string | The id of the hotspot whose action is to be started. | yes |
Code Sample
var configuration = {hotspotId:'bafdcd72'}
window.appnaviApi.hotspot.startHotspotAction(configuration);
console.log("Hotspot action started for hotspot id: "+ configuration.hotspotId);
stopHotspotAction :method
This method stops the action (e.g. stop display a hint, stop a route, etc.) associated with the specified hotspot.
Method Signature
stopHotspotAction(configuration)
Arguments
Configuration object contains following property,
Property | Type | Description | Required |
---|---|---|---|
hotspotId | string | The id of the hotspot whose action is to be stoped. | yes |
Code Sample
var configuration = {hotspotId:'bafdcd72'}
window.appnaviApi.hotspot.stopHotspotAction(configuration);
console.log("Hotspot action stopped for hotspot id: "+ configuration.hotspotId);
startRenderHotspots :method
This method starts the rerendering of the hotspots on the current page. If the method is called while another hotspot search is running, it is stopped and the search starts again.
Method Signature
startRenderHotspots()
Code Sample
window.appnaviApi.hotspot.startRenderHotspots();
console.log("Hotspot rendering started");
stopRenderHotspots :method
If a hotspot search is in progress, this method will cancel it. Hotspots that could not be found by the search at this time are not displayed.
Method Signature
stopRenderHotspots()
Code Sample
window.appnaviApi.hotspot.stopRenderHotspots();
console.log("Hotspot rendering stopped");
hotspotActionStart :event
This event is triggered when a user starts the action of a hotspot (e.g. starting a route via a hotspot).
Arguments
Parameter | Type | Description |
---|---|---|
hotspotId | string | The id of the hotspot whose action was started. |
Code Sample
appnavi.event.register("an-hotspotActionStart", function(event){
var eventDetails = event.detail;
var detail = eventDetails.detail;
console.log("The id of the hotspot that was started is ", detail.hotspotId);
});
hotspotActionStop :event
This event is triggered when the action of a hotspot is stopped (e.g. route started via a hotspot is stopped). This event is only triggered if the action was actually started in advance via a hotspot.
Arguments
Parameter | Type | Description |
---|---|---|
hotspotId | string | The id of the hotspot whose action was stopped. |
Code Sample
appnavi.event.register("an-hotspotActionStop", function(event){
var eventDetails = event.detail;
var detail = eventDetails.detail;
console.log("The id of the hotspot that was stopped is ", detail.hotspotId);
});
hotspotFound :event
This event is triggered when the hotspot has been found successfully by the search.
Arguments
Parameter | Type | Description |
---|---|---|
hotspotId | string | The id of the hotspot which is found. |
Code Sample
appnavi.event.register("an-hotspotFound", function(event){
var eventDetails = event.detail;
console.log("The id of the hotspot that was found is ", eventDetails.hotspotId);
});
hotspotNotFound :event
This event is triggered right after the search is timed out and no element is returned by the search
Arguments
Parameter | Type | Description |
---|---|---|
hotspotId | string | The id of the hotspot which was not found. |
Code Sample
appnavi.event.register("an-hotspotNotFound", function(event){
var eventDetails = event.detail;
console.log("The id of the hotspot that was not found is ", eventDetails.hotspotId);
});
hotspotHover :event
This event is triggered whenever we hover over the hotspot.
Arguments
Parameter | Type | Description |
---|---|---|
hotspotId | string | The id of the hotspot that was hovered. |
Code Sample
appnavi.event.register("an-hotspotHover", function(event){
var eventDetails = event.detail;
console.log("The id of the hotspot that was hovered is ", eventDetails.hotspotId);
});
Automation
The automation API contains all methods that can control the automation flow within a route.
insertValue :method
This method can be used to insert a dynamic text into an input field. This method is only executed if the route was started in automation mode. This method overwrites the automation configuration set in the user interface. This API method is only executed in step of type insert text. The configuration is passed as a configuration object.
Method Signature
insertValue(configuration)
Arguments
Configuration object contain following properties,
Property | Type | Description | Required |
---|---|---|---|
value | string | The value to be inserted. | yes |
fillingSpeed | string | The speed at which the field is to be filled in (slow/normal/fast). | yes |
Code Sample
var configuration = {value:"javascript", fillingSpeed:"fast"};
window.appnaviApi.automation.insertValue(configuration);
console.log('automation value ' + configuration.value + ' is inserted with the fillingSpeed '+ configuration.fillingSpeed);
skipAutomation :method
This method skips the automation of the current step and can be used in the onBeforeRender event hook. The method only affects the route when the route is in automation mode and is ignored in standard play mode.
Method Signature
skipAutomation()
Code Sample
window.appnaviApi.automation.skipAutomation();
console.log("automation skipped");
Analytics
setUserRole :method
This method allows you to define a user role, which is then available as an evaluation in Analytics. The user role is only saved if the Custom Analytics feature is active at the application level and role recording is allowed.
Method Signature
setUserRole(configuration);
Arguments
Configuration object contains following property,
Property | Type | Description | Required |
---|---|---|---|
userRole | string | The role of a user to be evaluated in analytics. | yes |
Code Sample
var configuration = {userRole:"Administrator"}
window.appnaviApi.analytics.setUserRole(configuration);
console.log("user role set as ", configuration.userRole)
ubmConfiguration:method
This method allows you to configure the user behavior monitoring (UBM) settings within your application. It accepts a single object parameter which specifies whether to enable or disable the capturing of user events.
Method Signature
ubmConfiguration(configuration);
Arguments
Configuration object contains following property,
Property | Type | Description | Required |
---|---|---|---|
captureEvents | boolean | Specifies whether the capturing of UBM events should be enabled for application or not. | no |
Code Sample
var configuration = {captureEvents:true}
window.appnaviApi.analytics.ubmConfiguration(configuration);
console.log("capture events set as ", configuration.captureEvents)
UBM Push Event API
This method allows user to sent customize events of UBM.
In some instances, certain elements may not be recorded during mining due to their customized nature. To address this issue, users can utilize the Push API within UBM.
ubmEvent is an array and can be sent multiple events at a time.
For more details check following link : push-event-API
[ubmEvent]
Configuration object contains following property,
Property | Type | Description | Required |
---|---|---|---|
EventType | String | Specifies RIGHT_CLICK, LEFT_CLICK, PAGE_LOAD. | yes |
areaLabel | String | customized text added by user. | No |
elementLabel | String | customized text added by user. | No |
tagType | String | Defines the category or type of tags that can be used. | yes |
Code Sample
let ubmEvent = {
eventType: "RIGHT_CLICK",
areaLabel: "This is area",
elementLabel: "This is element label",
tagType: window.appnaviApi.tagType.button
}
window.appnaviApi.analytics.pushEvent({type: "ubm", events: [ubmEvent]
});
setCustomFieldValue:method
This method allows you to configure the additional information to user behavior mining (UBM) events within your application. It accepts a single object parameter which specifies the additional information. This additional information then can be used for various purposes like data export based on the provided information
Method Signature
setCustomFieldValue(configuration);
Arguments
Configuration object contains following properties. One thing to note about all the properties is that their length should not exceed 32 characters. If they exceed, the text would be truncated to 32 characters.
Parameter | Type | Description | Required |
---|---|---|---|
customField_1 | string | Specifies the additional information to the UBM event. | no |
customField_2 | string | Specifies the additional information to the UBM event. | no |
customField_3 | string | Specifies the additional information to the UBM event. | no |
Code Sample
var configuration = {customField_1:"Engineer", customField_2: "19c19162-c760-47be-a6b9-cae88e562f2d" }
window.appnaviApi.analytics.setCustomFieldValue(configuration);
console.log("UBM Custom fields set as ", configuration)
Custom Push Event API
This method allows users to send customized events specific to their application's needs. Before utilizing this API, users must first create the necessary setup in the portal
For more details, refer to the following link: Custom Push Event API
Configuration Object contains following Properties,
Property | Type | Description | Required |
---|---|---|---|
EventType | String | Specifies the type of event. Custom events require a prefix "CUSTOM:". | Yes |
pageUrl | String | The URL of the page where the event occurs. | Optional |
pageTitle | String | The title of the page where the event occurs. | Optional |
customField_1 | String | User-defined custom field for additional data. | Optional |
customField_2 | String | User-defined custom field for additional data. | Optional |
customField_3 | String | User-defined custom field for additional data. | Optional |
Code Sample
let ubmEvent = {
eventType: "CUSTOM:BUTTON_CLICK",
pageUrl: "https://example.com/dashboard",
pageTitle: "Dashboard",
customField_1: "User clicked on the submit button",
customField_2: "Button color: Blue",
customField_3: "Time spent on page: 5 minutes"
}
window.appnaviApi.analytics.pushEvent({type: "ubm", events: [ubmEvent]});
## Route
The Route API contains all methods that are relevant for the control and the route data flow. The functions of this API must also work in automation mode.
startRoute :method
This method starts a route. If another route is already active, the active route is stopped and the new route is executed instead. This method can start a route within the current application or a route in another application that is in the same tenant. If no step id is provided, the route starts with the first active step. Deactivated steps cannot be played.
Method Signature
startRoute(configuration)
Arguments
Configuration object contain following properties,
Parameter | Type | Description | Required |
---|---|---|---|
applicationId | string | The application id in which the target route is located. | no |
routeId | string | Id of the route to be started. | yes |
stepId | string | Id of the step with which the route is to be started. If no step id is specified, the route starts with the first step. | no |
startMode | string | The start mode indicates whether the route is started in learning mode or in automation mode. Possible configuration parameters are 'learning' - this is the default or 'automation'. | no |
Code Sample
var configuration = {applicationId:"acvdcd72",routeId:"cdedcd72",stepId:"6785ab00",startMode:"automation"}
window.appnaviApi.route.startRoute(configuration);
console.log('Route started with these details: ', JSON.stringify(configuration));
getActiveRouteId :method
This method returns the Id of the currently started route as a string. The method returns null if no route is started.
Method Signature
getActiveRouteId()
Code Sample
var activeRouteId = window.appnaviApi.route.getActiveRouteId();
console.log('Active route id: '+ activeRouteId );
getCurrentStepId :method
This method returns the current step id of the currently executed route as a string. If no route is being executed or if no active Step id exists, the method returns null.
Method Signature
getCurrentStepId()
Code Sample
var stepId = window.appnaviApi.route.getCurrentStepId();
console.log('Current step id: '+ stepId );
getStartMode :method
This method returns mode in which the route is executed (learning / automation). This method returns null in case no route is started.
Method Signature
getStartMode()
Code Sample
var mode = window.appnaviApi.route.getStartMode();
console.log('Start mode: '+ mode );
stopRoute :method
This method stops the execution of current route.
Method Signature
stopRoute()
Code Sample
window.appnaviApi.route.stopRoute();
console.log("route stopped");
playStep :method
The playstep method can start any step of the current route. If no active route exists, the instruction of this method is ignored. Deactivated steps can also be played by putting deactivated step id in the configuration.
Method Signature
playStep(configuration);
Arguments
Configuration object contains following property,
Properties | Type | Description | Required |
---|---|---|---|
stepId | string | The step id of active route to be played. If no step id is specified, the first step will be played. | no |
Code Sample
var configuration = {stepId:"6785ab00"}
window.appnaviApi.route.playStep(configuration);
console.log("step played having id", configuration.stepId);
getCurrentElement :method
This method returns the currently found HTML element to which a step refers. This method can only be used in the onAfterRender method of a route step.
Method Signature
getCurrentElement()
Code Sample
var element = window.appnaviApi.route.getCurrentElement();
if (element) {
element.style.backgroundColor = "gray";
console.log("element: " + element);
}
getAvailableRoutes :method
This method returns a list of all available routes for the current application. This method is executed asynchronously.
Method Signature
getAvailableRoutes(configuration)
Arguments
Configuration object contains following property,
Property | Type | Description | Required |
---|---|---|---|
filterByTargetAudience | boolean | Specifies whether the currently set custom labels are to be taken into account in the filtering. If no value is given, no filtering takes place. | yes |
Code Sample
var configuration = {filterByTargetAudience:true};
window.appnaviApi.route.getAvailableRoutes(configuration).then(function(resp){
console.log("Available routes are",resp);
})
getTooltipContainer :method
This method returns the current tooltip container dom object and allows it to be modified. This method can only be executed in the onAfterRender event hook.
Method Signature
getTooltipContainer()
Code Sample
var tooltip = window.appnaviApi.route.getTooltipContainer();
tooltip.style.backgroundColor = "green";
console.log("tooltip: " tooltip);
routeStart :event
This event is triggered when a route is started within the application. This event can be registered at application level.
Arguments
Parameter | Type | Description |
---|---|---|
routeId | string | The id of the route that was started. |
Code Sample
appnavi.event.register("an-routeStart", function(event){
var eventDetails = event.detail;
var detail = eventDetails.detail;
console.log("route started having id", detail.routeId);
});
routeStop :event
This event is triggered when a route is stopped within the application. This event can be registered at application level.
Arguments
Parameter | Type | Description |
---|---|---|
routeId | string | The id of the route that was started. |
Code Sample
appnavi.event.register("an-routeStop", function(event){
var eventDetails = event.detail;
var detail = eventDetails.detail;
console.log("route stopped having id", detail.routeId);
});
playStep :event
This event is triggered when a user navigates to the next or previous step by clicking the button or navigation is executed by code using the playStep API.
Arguments
Parameter | Type | Description |
---|---|---|
routeId | string | The id of the route that was started. |
stepId | string | The id of the current step from which it was navigated. |
direction | string | The direction in which you navigated (forth / back). |
Code Sample
appnavi.event.register("an-playStep", function(event){
var eventDetails = event.detail;
var detail = eventDetails.detail;
console.log("step played with following details,");
console.log({ routeId: detail.routeId }, { stepId: detail.stepId}, { direction:
detail.direction })
});
Custom Code V2
AppNavi allows you to provide custom code that is executed when the step is played. AppNavi maintains two kind of Step custom codes, V1 and V2. The user can choose which one to use in the Route screen by using the "Use Custom Code V2" switch.
V1
You can provide custom code for two events in two separate rich code editors, BeforeRender and AfterRender, separately.
BeforeRender code is executed before the step is rendered, and it is executed even before the step's search is started. In this section, you can skip the step using the window.appnaviApi.route.playStep API.
AfterRender code is executed after the step is completely rendered and shown to the user.
V2
V2 is more powerful and flexible because it supports more events and provides a clean way to get notified of the Step events. The following events are supported by V2.
Event Name | Description |
---|---|
onBeforeSearch | Executed before the search is started. |
onElementFound | Executed after the element is found. |
onElementNotFound | Executed after the search is timed out and no element is returned by the search. |
onBeforeRender | Executed right before the tooltip is rendered and shown to the user. |
onElementLost | Executed when the element's tracking is lost. |
onBeforeSearch :event
This event is executed before the step's search is started. In this event, you can skip the step using the window.appnaviApi.route.playStep API.
Arguments
Parameter | Type | Description |
---|---|---|
route | object | Complete route object that is currently being played. |
step | object | Complete step object that is currently being played. |
Code Sample
appnavi.event.register("an-onBeforeSearch", function(event){
var detail = event.detail;
console.log("step is going to be played with the following details,");
console.log({ route: detail.route }, { step: detail.step});
});
onElementFound :event
This event is executed after search has returned element successfully.
Arguments
Parameter | Type | Description |
---|---|---|
route | object | Complete route object that is currently being played. |
step | object | Complete step object that is currently being played. |
element | HTMLElement | Dom element that was originaly captured by the step. |
Code Sample
appnavi.event.register("an-onElementFound", function(event){
var detail = event.detail;
console.log("step is going to be played with the following details,");
console.log({ route: detail.route }, { step: detail.step}, { element: detail.element});
});
Example to skip step based on found element's atrributes or text.
appnavi.event.register("an-onElementFound", function(event){
var detail = event.detail;
if (detail.element.getAttribute('data-id') != "Welcome!" ) {
var configuration = {stepId:"2009b561"}
window.appnaviApi.route.playStep(configuration);
}
});
onElementNotFound :event
This event is executed after the search is timed out and no element is returned by the search.
Arguments
Parameter | Type | Description |
---|---|---|
route | object | Complete route object that is currently being played. |
step | object | Complete step object that is currently being played. |
Code Sample
appnavi.event.register("an-onElementNotFound", function(event){
var detail = event.detail;
console.log("Step was triggered with the following details,");
console.log({ route: detail.route }, { step: detail.step});
});
Example to skip step if element is not found.
appnavi.event.register("an-onElementNotFound", function(event){
var configuration = {stepId:"5a3d4642"}
window.appnaviApi.route.playStep(configuration);
});
onBeforeRender :event
This event is executed right before the tooltip is rendered and shown to the user.
Arguments
Parameter | Type | Description |
---|---|---|
route | object | Complete route object that is currently being played. |
step | object | Complete step object that is currently being played. |
ELEMENT | HTMLElement | Dom element that was originaly captured by the step. |
tooltip | object { header, body, button, container } | Custom object containing different elements of the tooltip, allowing you to customize it. |
Code Sample
console.log('Hello World!');
appnavi.event.register('an-onBeforeRender', function (event) {
var detail = event.detail;
var tooltip = detail.tooltip;
var header = tooltip.header;
var body = tooltip.body;
var nextButton = tooltip.nextButton;
var backButton = tooltip.backButton;
var container = tooltip.container;
var tooltipType = tooltip.tooltipType;
console.log(header.get());
console.log(body.get());
console.log(container);//The html element containing the whole tooltip.
console.log(tooltipType);//There are 4 types, Content, Searching, Takes Longer, Not Found
header.set('Custom header text');
body.set('<span><b>Custom body text</b></span>');//you can provide any html.
//Override next button visibility.
nextButton.show();
//nextButton.hide();
//Override back button visibility.
backButton.hide();
//backButton.show();
});
Example to skip step if element satisfies some condition.
appnavi.event.register("an-onBeforeRender", function(event){
if( event.detail.element.value === 'Google Search') {
var configuration = {stepId:"SINK"}
window.appnaviApi.route.playStep(configuration);
}
});
onElementLost :event
This event is executed when the element is removed from the dom and AppNavi loses tracking of it.
Arguments
Parameter | Type | Description |
---|---|---|
route | object | Complete route object that is currently being played. |
step | object | Complete step object that is currently being played. |
Code Sample
appnavi.event.register("an-onElementLost", function(event){
var detail = event.detail;
console.log("Step was triggered with the following details,");
console.log({ route: detail.route }, { step: detail.step});
});
Example to cancel search for the element that was lost and move route to next step.
appnavi.event.register("an-onElementLost", function(event){
event.detail.stopSearch();
console.log("new search is cancelled");
});
Updated 26 days ago