Javascript Event Listener API

Overview

Gainsight PX collects and stores all the Analytics data related to your Engagements. However, there could be some scenarios in which you need to send the Analytics data to some third-party applications. This third party application could even be your own internal server. Gainsight PX's Javascript Event Listener allows you to easily send Engagement Analytics data to other applications.

Syntax

The Syntax for the API is:

aptrinsic('addListener', [eventType], [callback])

In the above syntax, eventType describes an event and callback refers to a Function that must be performed when the event occurs. Since this API is designed to send engagement data to third-party applications, the event generally refers to an instance of the engagement Analytics data being recorded. The callback function describes how this event data (latest Engagement Analytics data) must be sent to the required third-party application. Currently, the Multi Question survey is not supported.

Engagement Event Listener Types

Engagement analytics data that are currently supported as Events are as follows:

Event Type	Description
engagementView	This event occurs when a user views an engagement.
engagementCompleted	This event occurs when a user completes an engagement.
engagementViewedStep	This event occurs when a user views a step in an engagement.
surveyResponded	This event occurs when a user responds to a survey.
linkClick	This event occurs when a user clicks any URLs in an engagement.
customButtonClick	This event occurs when a user clicks any buttons added to an engagement.

Engagement completed example

aptrinsic('addListener', 'engagementCompleted', function(eventData)
{
  console.log(JSON.stringify(eventData));
});

Payload example

{
"engagementId":"f6bfbe59-643c-4b66-a6c8-30af8d8c5ab6",
"executionId":"13c42c83-5930-437e-bf4f-854f47f5979c",
"executionTimestamp":1620838876611,
"engagementType":"Guide",
"activation":"Auto",
"engagementName":"Demo JS Listener ",
"interaction":"Completed",
"identifyId":"LNZUgb555555y5EXrAAQzbVJ3"
}

IMPORTANT: In the case of a multi-page application, ensure to register the listeners on every page load.

Custom Button Click and Link Click Events

Use the following syntax for custom button click and link click events:

aptrinsic('addListener', ‘linkClick’, (url, engagement, step) => {
    console.log(url, engagement, step);
})
aptrinsic('addListener', 'customButtonClick', (url, engagement, step) => {
    console.log(url, engagement, step);
})

Notes:

You need to run the script before clicking the button/link.
Link Click and Custom Button Click events are not supported for Surveys currently.

Link Click Event Example:

"gainsight.com",
 {
    "engagementId":"f6bfbe59-643c-4b66-a6c8-30af8d8c5ab6",
    "executionId":"13c42c83-5930-437e-bf4f-854f47f5979c",
    "executionTimestamp":1620838876611,
    "engagementType":"Guide",
    "activation":"Auto",
    "engagementName":"Demo JS Listener ",
    "interaction":"Link Clicked",
    "identifyId":"LNZUgb555555y5EXrAAQzbVJ3"
},
{
     "stepId": "f6bfbe59-643c-4b66-a6c8-30af8d8c5ab6",
     "stepName": "Demo Slider Step",
}

Callback Event Object Fields

The Callback function gets an object as a parameter. This object has a few common fields for each event type and these fields are listed below.

Common Fields

Name	Type	Description
engagementId	string	PX engagement UUID
engagementName	string	PX engagement name
executionId	string	Runtime UUID - in case on interval / paywall scheduling
executionDate	long	Runtime timestamp
engagementType	string	can be one of: Dialog, Slider, Guide, NPS, CES, Rating, Boolean
activation	string	can be one of: Auto Bot Badge Journey Orchestration
interaction	string	can be one of: Viewed Completed Responded (for survey) Viewed Step
identifyId	string	user identifier

The engagementViewedStep event has a separate field as given below:

Name	Type	Description
stepNumber	integer	step sequence number

The surveyResponded event has two separate fields as given below:

Name	Type	Description
score	integer	score the user inserted depends on the type of survey
scoreType	string	for NPS® have naming based on the score: Promoter 9-10 Passive 7-8 Detractor 0-6
comment	string	if the user left a comment it is added to the event

The Link Click/Custom Button Click events have separate model for the Step data as given below:

Name	Type	Description
stepId	String	Unique identification number for the step
stepName	String	The name given to the step

KC Bot Event Types

The following events from the KC Bot widget are supported:

Event Type	Description
articleView	This event occurs when a user has viewed a KC Bot article.
kcSearch	This event occurs when a text entered for the article search.
kcOpened	This event occurs when a user opens the KC Bot window.
kcClosed	This event occurs when a user closes the KC Bot window.
kcTriggered	This event occurs when a KC Bot is triggered for a user when they qualify.

Supported Fields

The articleView event has four separate fields as shown below:

Name	Type	Description
kcId	string	ID of PX Knowledge Center widget
articleId	string	ID of article
categoryId	string	ID of PX category
articleUrl	string	URL of article

The kcSearch event has two separate fields as shown below:

Name	Type	Description
Search terms	string	Text entered for article search
kcId	string	ID of PX Knowledge Center widget

Example of a search for ‘potato’:

{   "searchTerms":"potato",   "kcId":"3b3a2ab9-1f06-4933-bc28-37833c756f12" }

The kcOpened and kcClosed events have the following field:

Name	Type	Description
kcId	string	ID of PX Knowledge Center widget

NPS, Net Promoter, and Net Promoter Score are registered trademarks of Satmetrix Systems, Inc., Bain & Company and Fred Reichheld