Overview

Once UserGuiding is correctly installed on your website, a whole toolbox of methods

and callback functions are readily available for you through the 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 as a way 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: Keep in mind that all the JavaScript commands mentioned in this article should be positioned and called after the Container code.

Sections

Guides
Checklists
Resource Centers
Promoter Survey
User Identification
Others

Guides

previewGuide (guideId, options)

This method triggers a Guide. If there is another Guide being previewed, it will interrupt it, then 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, appear 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(1226) 

// Starts a Guide from the 2nd step and tries to meet the segmentation conditions

userGuiding.previewGuide(1226, {
  initialStep: 2,
  checkHistory: true
})

finishPreview()

This method interrupts the current Guide being previewed.

Example

userGuiding.finishPreview()

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: 1226
}

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: 1226,
  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: 123456
}

Checklists

launchChecklist(checklistId, options)

This method triggers a Checklist. If another Checklist is being previewed, it will interrupt it, then 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(123)

// Triggers an open Checklist

userGuiding.launchChecklist(123, {
  itemsShown:true
})

hideChecklist()

This method removes the current active Checklist from the page.

Example

userGuiding.hideChecklist()

expandChecklist()

This method expands the content area of an active Checklist widget.

Example

userGuiding.expandChecklist()

collapseChecklist()

This method collapses the content area of an active Checklist widget.

Example

userGuiding.collapseChecklist()

Resource Centers

launchResourceCenter(resourceCenterId)

This method triggers a Resource Center. If another Resource Center is being previewed, it will interrupt it, then 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(123)

hideResourceCenter()

This method removes the current active Resource Center from the page.

Example

userGuiding.hideResourceCenter()

expandResourceCenter()

This method expands the content area of an active Resource Center widget.

Example

userGuiding.expandResourceCenter()

collapseResourceCenter()

This method collapses the content area of an active Resource Center widget.

Example

userGuiding.collapseResourceCenter()

Promoter Survey

triggerNps(options)

This method triggers a Promoter Survey.

Below you will find the available options.

force: the Promoter Survey will be triggered, ignoring any targeting or appearance conditions. The default value is false.
```
force: boolean
```

Example

// Triggers a Promoter Survey with default options.

userGuiding.triggerNps()

// Triggers a Promoter Survey ignoring any targeting or appearance conditions.

userGuiding.triggerNps({
  force: true
})

onNpsOpen

Executes a callback function when a Promoter Survey is visible to an end-user.

window.userGuidingLayer.push({
   event: 'onNpsOpen',
   fn: (data) => console.log(data),
})

Output example

{
  event: 'npsShown'
}

onScoreSubmit

Executes a callback function when a Promoter Survey score is submitted.

window.userGuidingLayer.push({
   event: 'onScoreSubmit',
   fn: (data) => console.log(data),
})

Output example

{
  event: 'npsScoreSubmit',
  score: 10,
  surveyQuestion: 'How likely are you to recommend UserGuiding to a friend or colleague?'
}

onUniqueScoreSubmit

Executes a callback function when a Promoter Survey score is first submitted. The user may click back and change the score.

window.userGuidingLayer.push({
   event: 'onUniqueScoreSubmit',
   fn: (data) => console.log(data),
})

Output example

{
  event: 'npsUniqueScoreSubmit',
  score: 10,
}

onFeedbackSubmit

Executes a callback function when a Promoter Survey feedback is submitted.

window.userGuidingLayer.push({
   event: 'onFeedbackSubmit',
   fn: (data) => console.log(data),
})

Output example

{
  event: 'npsFeedbackSubmit',
  feedbackQuestion: 'Why did you choose that score?',
  feedback: 'I love this!',
}

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]",
   }
 }
}
General use

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

forceIdentify

Get the latest state of the user. This is handy when you send attributes through a server-side integration and need a user's attribute to be updated on the front-end.

window.userGuiding.forceIdentify()

UserGuiding JavaScript API

Overview

Sections

Guides

previewGuide (guideId, options)

finishPreview()

onPreviewStart

onPreviewStep

onPreviewEnd

Checklists

launchChecklist(checklistId, options)

hideChecklist()

expandChecklist()

collapseChecklist()

Resource Centers

launchResourceCenter(resourceCenterId)

hideResourceCenter()

expandResourceCenter()

collapseResourceCenter()

Promoter Survey

triggerNps(options)

onNpsOpen

onScoreSubmit

onUniqueScoreSubmit

onFeedbackSubmit

User Identification

onIdentificationComplete

Others

onload

forceIdentify