Skip to main content
Gainsight Inc.

Javascript Event Listener API

This article explains Gainsight PX's 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.

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