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,

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,

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,

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,

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

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,

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,

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,

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

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

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

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,

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,

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,

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,

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,

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

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

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

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

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

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,

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,

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,

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,

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.

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,

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,

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,

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,

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

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

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

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.

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

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

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

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

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

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");
});