Announcement

The Announcement API allows you to retrieve available news, display news as announcements or tooltips, and listen for events when users view or read news.

getAvailableNews :method

This method asynchronously returns a list of all news items available for the application.

Method Signature

getAvailableNews(configuration)

Arguments

The configuration object supports the 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 one or more news items as announcements.

The currently published version of each news item is displayed. If a news item has already been marked as read, it is not displayed again unless force is set to true.

You can display a single news item or multiple news items by providing their IDs in an array.

Method Signature

showAnnouncement(configuration)

Arguments

The configuration object supports the 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 info-type news item as a tooltip.

The currently published version of the selected info item is displayed.

Method Signature

showInfo(configuration)

Arguments

The configuration object supports the 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 in the News area.

This event is not triggered when the news item is displayed as an announcement.

Arguments

Code Sample

appnavi.event.register("an-newsShow", function(event){ 
    var eventDetails = event.detail;
    var detail = eventDetails.detail;
    console.log("News displayed with ID", detail.newsId); 
});

newsRead :event

This event is triggered when a user marks a news item as read.

It applies to news items displayed both in the News area and in an Announcement window.

Arguments

Code Sample

appnavi.event.register("an-newsRead", function(event){ 
    var eventDetails = event.detail;
    var detail = eventDetails.detail;
    console.log("News read with ID", detail.newsId); 
});

announcementShow :event

This event is triggered when an Announcement window is displayed.

The event contains the IDs of all news items displayed in the Announcement window.

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 items displayed are", detail.newsIds); 
});

Quick Reference

getDepartment() :method

This method returns the department available for the current application.

The department is determined using the following priority:

1. IDP Configuration: If an IDP is configured and a department is defined, the department from the IDP takes the highest priority.
2. Custom Code: If no department is configured in the IDP, the department defined through custom code in the application is used.
3. Registry: If no department is defined through the IDP or custom code, the department configured in the registry is used.

Method Signature

getDepartment()

Code Sample

var configuration = {department: 'marketing'};

window.appnaviApi.application.setDepartment(configuration);

console.log("Department: ", configuration.department);

getOrganizationalUnit() :method

This method returns the organizational unit available for the current application.

The organizational unit is determined using the following priority:

1. Custom Code: If an organizational unit is defined through custom code in the application, it takes the highest priority.
2. Registry: If no organizational unit is defined through custom code, the organizational unit configured in the registry is used.

Method Signature

getOrganizationalUnit()

Code Sample

var configuration = {organizationalUnit: 'GEO'};

window.appnaviApi.application.setOrganizationalUnit(configuration);

console.log("Organizational Unit: ", configuration.organizationalUnit);

Hotspots

The Hotspot API provides methods for controlling and interacting with the AppNavi hotspot feature.

getAvailableHotspotCollections :method

This method asynchronously returns a list of all hotspot collections available for the current application.

Method Signature

getAvailableHotspotCollections(configuration)

Arguments

The configuration object supports the following property:

Code Sample

var configuration = {filterByTargetAudience: true};

window.appnaviApi.hotspot.getAvailableHotspotCollections(configuration).then(function(resp) {
    console.log("Available hotspots are", resp);
});

getPageHotspots :method

This method returns a list of hotspots displayed on the current page that are visible to the current user, taking the target audience into account.

Method Signature

getPageHotspots()

Code Sample

window.appnaviApi.hotspot.getPageHotspots().then(function(resp) {
    console.log("Page hotspots are", resp);
});

hidePageHotspots :method

This method hides all hotspots displayed on the current page.

Method Signature

hidePageHotspots()

Code Sample

window.appnaviApi.hotspot.hidePageHotspots();

console.log("Page hotspots have been hidden");

showPageHotspots :method

This method displays the hotspots available on the current page that were previously hidden using hidePageHotspots().

Only hotspots that are available to the current user's target audience are displayed.

Method Signature

showPageHotspots()

Code Sample

window.appnaviApi.hotspot.showPageHotspots();

console.log("Page hotspots have been shown");

hideHotspotItem :method

This method hides a specific hotspot displayed on the current page.

Method Signature

hideHotspotItem(configuration)

Arguments

The configuration object supports the following property:

Code Sample

var configuration = {hotspotId: 'cdedcd72'};

window.setTimeout(function() {
    window.appnaviApi.hotspot.hideHotspotItem(configuration);

    console.log(
        "Hotspot with ID " + configuration.hotspotId + " has been hidden"
    );
});

showHotspotItem :method

This method displays a specific hotspot on the current page.

Method Signature

showHotspotItem(configuration)

Arguments

The configuration object supports the following property:

Code Sample

var configuration = {hotspotId: 'cdedcd72'};

window.appnaviApi.hotspot.showHotspotItem(configuration);

console.log(
    "Hotspot item has been shown with ID " + configuration.hotspotId
);

startHotspotAction :method

This method starts the action associated with the specified hotspot, such as displaying a hint or starting a route.

Method Signature

startHotspotAction(configuration)

Arguments

The configuration object supports the 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 associated with the specified hotspot, such as stopping a hint or a route.

Method Signature

stopHotspotAction(configuration)

Arguments

The configuration object supports the 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 searching for and rendering hotspots on the current page.

If the method is called while another hotspot search is running, the current search is stopped and a new search starts.

Method Signature

startRenderHotspots()

Code Sample

window.appnaviApi.hotspot.startRenderHotspots();

console.log("Hotspot rendering started");

stopRenderHotspots :method

This method stops an ongoing hotspot search.

Any hotspots that have not been found when the search is stopped are not displayed.

Method Signature

stopRenderHotspots()

Code Sample

window.appnaviApi.hotspot.stopRenderHotspots();

console.log("Hotspot rendering stopped");

Hotspot Events

hotspotActionStart :event

This event is triggered when a user starts the action associated with a hotspot, such as starting a route through 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 associated with a hotspot is stopped, such as when a route started through a hotspot is stopped.

This event is triggered only if the action was previously started through the 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 a hotspot is successfully found during the hotspot 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 when the hotspot search times out without finding the specified hotspot.

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 when a user hovers over a hotspot.

Arguments

Code Sample

appnavi.event.register("an-hotspotHover", function(event) {
    var eventDetails = event.detail;

    console.log(
        "The ID of the hotspot being hovered over is",
        eventDetails.hotspotId
    );
});

Automation

The Automation API provides methods for controlling the automation flow within a route.

insertValue :method

This method inserts dynamic text into an input field.

It is executed only when the route is started in Automation mode. It overrides the automation configuration defined in the user interface.

This method applies only to route steps of the Insert text type. The configuration is provided as a configuration object.

Method Signature

insertValue(configuration)

Arguments

The configuration object supports the following properties:

Code Sample

var configuration = {
    value: "javascript",
    fillingSpeed: "fast"
};

window.appnaviApi.automation.insertValue(configuration);

console.log(
    "Automation value " + configuration.value +
    " is inserted with a filling speed of " + configuration.fillingSpeed
);

skipAutomation :method

This method skips automation for the current route step.

It can be used in the onBeforeRender event hook.

The method only affects routes running in Automation mode. It is ignored when the route is running in Standard play mode.

Method Signature

skipAutomation()

Code Sample

window.appnaviApi.automation.skipAutomation();

console.log("Automation skipped");

Route

The Route API contains methods for controlling routes and managing route data flow. All Route API functions 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 started instead.

The method can start a route within the current application or a route from another application within the same tenant. If no stepId is provided, the route starts with the first active step. Deactivated steps cannot be played.

Method Signature

JavaScript

startRoute(configuration)

Arguments

The configuration object contains the following properties:

Code Sample

JavaScript

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 active route as a string. If no route is currently active, the method returns null.

Method Signature

JavaScript

getActiveRouteId()

Code Sample

JavaScript

var activeRouteId = window.appnaviApi.route.getActiveRouteId();
console.log('Active route ID: ' + activeRouteId);

getCurrentStepId :method

This method returns the ID of the current step in the active route as a string. If no route is being executed or no active step ID exists, the method returns null.

Method Signature

JavaScript

getCurrentStepId()

Code Sample

JavaScript

var stepId = window.appnaviApi.route.getCurrentStepId();
console.log('Current step ID: ' + stepId);

getStartMode :method

This method returns the mode in which the current route is being executed: learning or automation. If no route is currently active, the method returns null.

Method Signature

JavaScript

getStartMode()

Code Sample

JavaScript

var mode = window.appnaviApi.route.getStartMode();
console.log('Start mode: ' + mode);

stopRoute :method

This method stops the currently active route.

Method Signature

JavaScript

stopRoute()

Code Sample

JavaScript

window.appnaviApi.route.stopRoute();
console.log("Route stopped");

playStep :method

The playStep method starts a specific step of the currently active route. If no active route exists, the instruction is ignored.

Deactivated steps can also be played by providing the ID of the deactivated step in the configuration.

Method Signature

JavaScript

playStep(configuration);

Arguments

The configuration object contains the following property:

Code Sample

JavaScript

var configuration = {stepId:"6785ab00"}
window.appnaviApi.route.playStep(configuration);
console.log("Step played with ID", configuration.stepId);

getCurrentElement :method

This method returns the HTML element currently found for the active step. This method can only be used in the onAfterRender method of a route step.

Method Signature

JavaScript

getCurrentElement()

Code Sample

JavaScript

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. The method is executed asynchronously.

Method Signature

JavaScript

getAvailableRoutes(configuration)

Arguments

The configuration object contains the following property:

Code Sample

JavaScript

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 as a DOM object and allows it to be modified. This method can only be executed in the onAfterRender event hook.

Method Signature

JavaScript

getTooltipContainer()

Code Sample

JavaScript

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. The event can be registered at the application level.

Arguments

Code Sample

JavaScript

appnavi.event.register("an-routeStart", function(event){ 
    var eventDetails = event.detail;
    var detail = eventDetails.detail;
    console.log("Route started with ID", detail.routeId); 
});

routeStop :event

This event is triggered when a route is stopped within the application. The event can be registered at the application level.

Arguments

Code Sample

JavaScript

appnavi.event.register("an-routeStop", function(event){ 
    var eventDetails = event.detail;
    var detail = eventDetails.detail;
    console.log("Route stopped with ID", detail.routeId); 
});

playStep :event

This event is triggered when a user navigates to the next or previous step by clicking a navigation button. It is also triggered when navigation is performed programmatically using the playStep API.

Arguments

Code Sample

JavaScript

appnavi.event.register("an-playStep", function(event){ 
    var eventDetails = event.detail;
    var detail = eventDetails.detail;

    console.log("Step played with the 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 a route step is played. AppNavi supports two versions of Step Custom Code: V1 and V2. You can select which version to use on the Route screen by enabling or disabling the Use Custom Code V2 switch.

V1

V1 allows you to provide custom code for two events in separate rich code editors: BeforeRender and AfterRender.

BeforeRender code is executed before the step is rendered and before the step search begins. You can use this event to skip the current step by using the window.appnaviApi.route.playStep API.

AfterRender code is executed after the step has been completely rendered and displayed to the user.

V2

Custom Code V2 provides more flexibility by supporting additional events and providing a consistent way to respond to step events.

The following events are supported:

onBeforeSearch :event

This event is executed before the step search begins. You can use this event to skip the current step by using the window.appnaviApi.route.playStep API.

Arguments

Code Sample

JavaScript

appnavi.event.register("an-onBeforeSearch", function(event){ 
    var detail = event.detail;
    console.log("Step is about to be played with the following details:");
    console.log({ route: detail.route }, { step: detail.step });
});

onElementFound :event

This event is executed after the step search successfully finds the target element.

Arguments

Code Sample

JavaScript

appnavi.event.register("an-onElementFound", function(event){ 
    var detail = event.detail;
    console.log("Step is about to be played with the following details:");
    console.log(
        { route: detail.route },
        { step: detail.step },
        { element: detail.element }
    );
});

Example: Skip a Step Based on the Element's Attributes or Text

The following example checks an attribute of the found element and moves to another step when the condition is met.

JavaScript

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 when the step search times out without finding the target element.

Arguments

Code Sample

JavaScript

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: Skip a Step When the Element Is Not Found

JavaScript

appnavi.event.register("an-onElementNotFound", function(event){
    var configuration = {stepId:"5a3d4642"};
    window.appnaviApi.route.playStep(configuration);
});

onBeforeRender :event

This event is executed immediately before the tooltip is rendered and displayed to the user.

Arguments

Code Sample

JavaScript

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 complete tooltip.
    console.log(tooltipType); // Possible types: Content, Searching, Takes Longer, Not Found.

    header.set('Custom header text');
    body.set('<span><b>Custom body text</b></span>'); // HTML can be provided.

    // Override next button visibility.
    nextButton.show();
    // nextButton.hide();

    // Override back button visibility.
    backButton.hide();
    // backButton.show();
});

Example: Skip a Step Based on an Element Condition

JavaScript

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 target element is removed from the DOM and AppNavi loses tracking of it.

Arguments

Code Sample

JavaScript

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: Stop Searching for a Lost Element

The following example stops the search when AppNavi loses tracking of the target element.

JavaScript

appnavi.event.register("an-onElementLost", function(event){ 
    event.detail.stopSearch();
    
    console.log("New search is cancelled");
});