Overview
Once UserGuiding is correctly installed on your website, a whole toolbox of methods
and callback functions are readily available for you through UserGuiding's JavaScript API (aka JS API).
In the example below, a Guide is being triggered through the userGuiding.previewGuide() method, one of the available commands from our API.
If you'd like to know in detail how this guide was called through the API, click here to watch the full video.
The browser console is used here to illustrate it. However, in a real scenario, you'd call these methods and callback functions directly from your website's source code. You can share this article with your development team for help.
Important: Remember that all the JavaScript commands mentioned in this article should be positioned and called after the Container code.
Guides
previewGuide (guideId, options)
This method triggers a Guide. If another Guide is being previewed, it will interrupt it and start the requested one.
To locate the Guide's ID, access your panel and go to the Guide's settings page. Its ID will be under the "Guide Information" section.
Below, you will find the available options.
initialStep: the Guide step number from which the Guide will start. The default value is 0.
initialStep: number
checkHistory: if false, it tries to meet only the targeting conditions. If true, it tries to meet the targeting, appearance frequency (even if it is turned off), and segmentation conditions. The default value is false.
checkHistory: boolean
Example
// Triggers a Guide with default options
userGuiding.previewGuide(1234)
// Starts a Guide from the 2nd step and tries to meet the segmentation conditions
userGuiding.previewGuide(1234, {
initialStep: 2,
checkHistory: true
})
finishPreview()
This method interrupts the current Guide being previewed.
Example
userGuiding.finishPreview(1234)
onPreviewStart
Executes a callback function when a Guide's preview has started.
window.userGuidingLayer.push({
event: 'onPreviewStart',
fn: (data) => console.log(data)
})
Output example
{
guideId: 1234
}
onPreviewStep
Executes a callback function when a Guide's step is being previewed.
window.userGuidingLayer.push({
event: 'onPreviewStep',
fn: (data) => console.log(data)
})
Output example
{
guideId: 1234,
stepIndex: 1
}
onPreviewEnd
Executes a callback function when a Guide's preview has ended.
window.userGuidingLayer.push({
event: 'onPreviewEnd',
fn: (data) => console.log(data)
})
Output example
{
completed: true, // false if user bounced
guideId: 1234
}
onPreviewComplete
Executes a callback function when all steps of the Guide are played.
window.userGuidingLayer.push({
event: 'onPreviewComplete',
fn: (data) => console.log(data)
})
Output example
{
guideId: 1234
}
Checklists
launchChecklist(checklistId, options)
This method triggers a Checklist. If another Checklist is being previewed, it will interrupt it and start the requested one.
To locate the Checklist's ID, access your panel and edit any existing Checklist. Its ID will be at the end of the URL.
Below, you will find the available options.
itemsShown: defines if a Checklist should start open. The default value is false.
itemsShown: boolean
Example
// Triggers a Checklist with default options
userGuiding.launchChecklist(1234)
// Triggers an open Checklist
userGuiding.launchChecklist(1234, {
itemsShown:true
})
hideChecklist()
This method removes the current active Checklist from the page.
Example
userGuiding.hideChecklist(1234)
expandChecklist()
This method expands the content area of an active Checklist widget.
Example
userGuiding.expandChecklist(1234)
collapseChecklist()
This method collapses the content area of an active Checklist widget.
Example
userGuiding.collapseChecklist(1234)
Resource Centers
launchResourceCenter(resourceCenterId)
This method triggers a Resource Center. If another Resource Center is being previewed, it will interrupt it and start the requested one.
To locate the Resource Center's ID, access your panel and edit any existing Resource Center. Its ID will be at the end of the URL.
Example
userGuiding.launchResourceCenter(1234)
hideResourceCenter()
This method removes the current active Resource Center from the page.
Example
userGuiding.hideResourceCenter(1234)
expandResourceCenter()
This method expands the content area of an active Resource Center widget.
Example
userGuiding.expandResourceCenter(1234)
collapseResourceCenter()
This method collapses the content area of an active Resource Center widget.
Example
userGuiding.collapseResourceCenter(1234)
Surveys
launchSurvey(surveyId)
This method triggers a Survey.
Example
// Triggers a Survey
userGuiding.launchSurvey(1234)
onSurveyView
Executes a callback function when a Survey is visible to end user.
window.userGuidingLayer.push({
event: 'onSurveyView',
fn: (data) => console.log(data),
})
Output example
{
event: 'surveyView',
surveyId: 'SURVEY_ID',
}
onSurveyQuestionView
Executes a callback function when a Survey question is visible to the end user. Each question in the survey omits a new question view event.
window.userGuidingLayer.push({
event: 'onSurveyQuestionView',
fn: (data) => console.log(data),
})
Output example
{
event: 'surveyQuestionView',
surveyId: 'SURVEY_ID',
questionId: 'QUESTION_ID'
questionType: 'NPS Rating',
responseId: 'RESPONSE_ID',
}
onSurveyAnswer
Executes a callback function when a Survey answer is submitted. For each survey question, we fire a separate answer event. The user may click back and change the answer, and multiple events would be thrown in such a case. You can use responseId to update the existing answer, and both events would have the same responseId.
window.userGuidingLayer.push({
event: 'onSurveyAnswer',
fn: (data) => console.log(data),
})
Output example
{
event: 'surveyAnswer',
surveyId: 'SURVEY_ID',
questionId: 'QUESTION_ID'
questionType: 'Number Rating (10)',
responseId: 'RESPONSE_ID',
// depending on the question type, you will get
// one of the answer fields below
score: 10,
feedback: 'very happy!',
choices: 'this,and,that',
emojiScore: 'Positive'
}
User Identification
onIdentificationComplete
Executes a callback function when an end-user has been successfully identified through the User Identification feature.
window.userGuidingLayer.push({
event: 'onIdentificationComplete',
fn: (data) => console.log(data)
})
Output example
{
"userStorage": {
"account_id": 1,
"user_id": "1",
"preview_start": [],
"preview_step": [],
"preview_complete": [],
"hotspot_interact": [],
"checklist_item_trigger": [],
"segment": {
"isTrial": false,
"userName": "User",
"userEmail": "[email protected]",
}
}
}
forceIdentify
Get the latest attributes of the user. This is handy when you send attributes through a server-side integration and need a user's attribute updated on the front end.
window.userGuiding.forceIdentify()
Others
onload
Executes a callback function when the UserGuiding script has loaded and the JavaScript API is ready to use.
window.userGuidingLayer.push({
event: 'onload',
fn: () => console.log('UserGuiding script loaded'),
})onload
page
This method updates UserGuiding SDK's internal page URL attribute and sends an page_view
event to user storage. Our SDK handles this in default settings. But, if you want more control over UserGuiding's updates to page changes if the URL or page history changes too much, you can disable the auto page view capturing and make calls to the page
method instead.
disablePageViewAutoCapture
Make sure to set this variable before loading the SDK.
window.userGuidingSettings = {
disablePageViewAutoCapture: true
}
You need to make page()
calls on every page change and the first page when userGuiding is loaded.
window.userGuiding.page()