Overview
When users interact with UserGuiding content or certain events occur (such as a Guide or Survey triggering), the UserGuiding SDK can notify your code via callback events. These events are accessed through the global window.userGuidingLayer array using the push() method.
By pushing an object with an event name and a callback function (fn), you subscribe to that event. This mechanism is similar to how one might listen for analytics events.
Guide
These events relate to Guides being started, progressed, or completed.
onPreviewStart
Executes a callback function when a Guide's preview has started.
Callback Function Signature
onUgPreviewStart({
event: 'previewStart',
guideId: number,
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onPreviewStart',
fn: onUgPreviewStart,
})onPreviewStep
Executes a callback function when a Guide's step is being previewed.
Callback Function Signature
onUgPreviewStep({
event: 'onPreviewStep',
guideId: number,
stepIndex: number,
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onPreviewStep',
fn: onUgPreviewStep,
})onPreviewEnd
Executes a callback function when a Guide's preview has ended.
Callback Function Signature
onUgPreviewEnd({
event: 'previewEnd',
guideId: number,
completed: boolean,
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onPreviewEnd',
fn: onUgPreviewEnd,
})onPreviewComplete
Executes a callback function when all steps of the Guide are played.
Callback Function Signature
onUgPreviewComplete({
event: 'previewComplete',
guideId: number,
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onPreviewComplete',
fn: onUgPreviewComplete,
})onPreviewDismiss
Executes a callback function when the Guide is dismissed by the user.
Callback Function Signature
onUgPreviewStart({
event: 'previewDismiss',
guideId: number,
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onPreviewDismiss',
fn: onUgPreviewDismiss,
})Hotspot
The events below help track interactions with Hotspots.
onHotspotInteract
Executes a callback function when a Hotspot is interacted with.
Callback Function Signature
onUgHotspotInteract({
event: 'hotspotInteract',
groupId: number,
hotspotId: string,
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onHotspotInteract',
fn: onUgHotspotInteract,
})onHotspotDismiss
Executes a callback function when a Hotspot is dismissed.
Callback Function Signature
onUgHotspotDismiss({
event: 'hotspotDismiss',
groupId: number,
hotspotId: string,
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onHotspotDismiss',
fn: onUgHotspotDismiss,
})Banner
If you are using Banners, the following events apply. These correspond to actions on Banners (the individual update announcements).
onBannerDismiss
Executes a callback function when the Banner is dismissed by the user.
Callback Function Signature
onUgBannerDismiss({
event: 'bannerDismiss',
bannerId: number,
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onBannerDismiss',
fn: onUgBannerDismiss,
})onBannerButtonClick
Executes a callback function when a Banner's button is clicked.
Callback Function Signature
onUgBannerButtonClick({
event: 'bannerButtonClick',
bannerId: number,
buttonId: string,
buttonText: string,
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onBannerButtonClick',
fn: onUgBannerButtonClick,
})Checklist
These events pertain to user interactions with Checklists.
onChecklistComplete
Executes a callback function when all items in the Checklist are complete.
Callback Function Signature
onUgChecklistComplete({
event: 'checklistComplete',
checklistId: number,
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onChecklistComplete',
fn: onUgChecklistComplete,
})onChecklistItemTrigger
Executes a callback function when a Checklist item is triggered.
Callback Function Signature
onUgChecklistItemTrigger({
event: 'checklistItemTrigger',
checklistId: number,
checklistItemId: number,
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onChecklistItemTrigger',
fn: onUgChecklistItemTrigger,
})onChecklistUrlClick
Executes a callback function when a Checklist URL item is clicked.
Callback Function Signature
onUgChecklistUrlClick({
event: 'checklistUrlClick',
checklistId: number,
checklistItemId: string,
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onChecklistUrlClick',
fn: onUgChecklistUrlClick,
})onChecklistDismiss
Executes a callback function when the user dismisses the Checklist.
Callback Function Signature
onUgChecklistDismiss({
event: 'checklistDismiss',
checklistId: number,
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onChecklistDismiss',
fn: onUgChecklistDismiss,
})Resource Center
Resource Center events fire when users interact with modules inside the Resource Center.
onResourceCenterGuideTrigger
Executes a callback function when a Guide within the Resource Center is triggered.
Callback Function Signature
onUgResourceCenterGuideTrigger({
event: 'resourceCenterGuideTrigger',
resourceCenterId: number,
guideId: number,
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onResourceCenterGuideTrigger',
fn: onUgResourceCenterGuideTrigger,
})onResourceCenterSurveyTrigger
Executes a callback function when a Survey within the Resource Center is triggered.
Callback Function Signature
onUgResourceCenterSurveyTrigger({
event: 'resourceCenterSurveyTrigger',
resourceCenterId: number,
surveyId: number,
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onResourceCenterSurveyTrigger',
fn: onUgResourceCenterSurveyTrigger,
})onResourceCenterChecklistGuideTrigger
Executes a callback function when a Checklist's Guide item within the Resource Center is triggered.
Callback Function Signature
onUgResourceCenterChecklistGuideTrigger({
event: 'resourceCenterChecklistGuideTrigger',
resourceCenterId: number,
checklistId: number,
guideId: number,
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onResourceCenterChecklistGuideTrigger',
fn: onUgResourceCenterChecklistGuideTrigger,
})onResourceCenterChecklistUrlClick
Executes a callback function when a Checklist's URL item within the Resource Center is triggered.
Callback Function Signature
onUgResourceCenterChecklistUrlClick({
event: 'resourceCenterChecklistUrlClick',
resourceCenterId: number,
checklistId: number,
checklistItemId: string,
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onResourceCenterChecklistUrlClick',
fn: onUgResourceCenterChecklistUrlClick,
})onResourceCenterArticleLinkClick
Executes a callback function when an Article Link within the Resource Center is clicked.
Callback Function Signature
onUgResourceCenterArticleLinkClick({
event: 'resourceCenterArticleLinkClick',
resourceCenterId: number,
articleLink: string,
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onResourceCenterArticleLinkClick',
fn: onUgResourceCenterArticleLinkClick,
})onResourceCenterExternalUrlClick
Executes a callback function when a URL item within the Resource Center is clicked.
Callback Function Signature
onUgResourceCenterExternalUrlClick({
event: 'resourceCenterExternalUrlClick',
resourceCenterId: number,
externalUrl: string,
}) => void"
Registration Example
window.userGuidingLayer.push({
event: 'onResourceCenterExternalUrlClick',
fn: onUgResourceCenterExternalUrlClick,
})Survey
These events pertain to Surveys being shown and answered.
onSurveyView
Executes a callback function when a Survey is visible to the end user.
Callback Function Signature
onUgSurveyView({
event: 'surveyView',
surveyId: number,
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onSurveyView',
fn: onUgSurveyView,
})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.
Callback Function Signature
onUgSurveyQuestionView({
event: 'surveyQuestionView',
surveyId: number,
questionId: string,
questionType: 'Star Rating' | 'Number Rating (5)' | 'Number Rating (10)' | 'Emoji Rating' | 'Thumbs Up/Down' | 'NPS Rating' | 'Multiple Choice' | 'Written Feedback',
responseId: string,
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onSurveyQuestionView',
fn: onUgSurveyQuestionView,
})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.
Callback Function Signature
onUgSurveyAnswer({
event: 'surveyAnswer',
surveyId: number,
questionId: string,
questionType: 'Star Rating' | 'Number Rating (5)' | 'Number Rating (10)' | 'Emoji Rating' | 'Thumbs Up/Down' | 'NPS Rating' | 'Multiple Choice' | 'Written Feedback',
responseId: string,
score?: number,
emojiScore?: string,
choices?: string,
feedback?: string,
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onSurveyAnswer',
fn: onUgSurveyAnswer,
})AI Assistant
If you have the AI Assistant enabled, there are many events to understand user engagement with the assistant. These events cover views, hides, and message exchanges with the assistant.
onAiAssistantLauncherView
Executes a callback function when the AI Assistant launcher becomes visible to the user.
Callback Function Signature
onUgAiAssistantLauncherView({
event: 'aiAssistantLauncherView',
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onAiAssistantLauncherView',
fn: onUgAiAssistantLauncherView,
})onAiAssistantLauncherHide
Executes a callback function when the AI Assistant launcher is hidden or closed.
Callback Function Signature
onUgAiAssistantLauncherView({
event: 'aiAssistantLauncherHide',
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onAiAssistantLauncherHide',
fn: onUgAiAssistantLauncherHide,
})onAiAssistantBoosterTooltipView
Executes a callback function when the AI Assistant booster tooltip is displayed to the user.
Callback Function Signature
onUgAiAssistantBoosterTooltipView({
event: 'aiAssistantBoosterTooltipView',
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onAiAssistantBoosterTooltipView',
fn: onUgAiAssistantBoosterTooltipView,
})onAiAssistantWidgetView
Executes a callback function when the AI Assistant widget becomes visible to the user.
Callback Function Signature
onUgAiAssistantWidgetView({
event: 'aiAssistantWidgetView',
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onAiAssistantWidgetView',
fn: onUgAiAssistantWidgetView,
})onAiAssistantWidgetHide
Executes a callback function when the AI Assistant widget is closed or hidden.
Callback Function Signature
onUgAiAssistantWidgetHide({
event: 'aiAssistantWidgetHide',
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onAiAssistantWidgetHide',
fn: onUgAiAssistantWidgetHide,
})onAiAssistantConversationStart
Executes a callback function when a new AI Assistant conversation is started.
Callback Function Signature
onUgAiAssistantConversationStart({
event: 'aiAssistantConversationStart',
threadId: string,
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onAiAssistantConversationStart',
fn: onUgAiAssistantConversationStart,
})onAiAssistantMessageSend
Executes a callback function when the user sends a message to the AI Assistant.
Callback Function Signature
onUgAiAssistantMessageSend({
event: 'aiAssistantMessageSend',
threadId: string,
role: 'user',
message: string,
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onAiAssistantMessageSend',
fn: onUgAiAssistantMessageSend,
})onAiAssistantMessageReceive
Executes a callback function when the AI Assistant sends a response message to the user.
Callback Function Signature
onUgAiAssistantMessageReceive({
event: 'aiAssistantMessageReceive',
threadId: string,
role: 'assistant',
message: string,
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onAiAssistantMessageReceive',
fn: onUgAiAssistantMessageReceive,
})onAiAssistantFallbackMessageReceive
Executes a callback function when the AI Assistant sends a fallback message. Typically used when no suitable automated response is available.
Callback Function Signature
onUgAiAssistantFallbackMessageReceive({
event: 'aiAssistantFallbackMessageReceive',
threadId: string,
role: 'assistant',
message: string,
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onAiAssistantFallbackMessageReceive',
fn: onUgAiAssistantFallbackMessageReceive,
})onAiAssistantFallbackActionClick
Executes a callback function when the user clicks a fallback action in the AI Assistant response.
Callback Function Signature
onUgAiAssistantFallbackActionClick({
event: 'aiAssistantFallbackActionClick',
type: 'javascript' | 'url',
url?: string,
threadId: string,
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onAiAssistantFallbackActionClick',
fn: onUgAiAssistantFallbackActionClick,
})onAiAssistantArticleClick
Executes a callback function when the user clicks on a Knowledge Base article listed in the AI Assistant’s response.
Callback Function Signature
onUgAiAssistantArticleClick({
event: 'aiAssistantArticleClick',
articleId: string,
articleName: string,
articleLink: string,
threadId: string,
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onAiAssistantArticleClick',
fn: onUgAiAssistantArticleClick,
})onAiAssistantGuideTrigger
Executes a callback function when a guide suggested by the AI Assistant is launched by the user.
Callback Function Signature
onUgAiAssistantGuideTrigger({
event: 'aiAssistantGuideTrigger',
guideId: string,
guideName: string,
threadId: string,
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onAiAssistantGuideTrigger',
fn: onUgAiAssistantGuideTrigger,
})User Identification
There is an event related to the user identification process:
onIdentificationComplete
Executes a callback function when an end-user has been successfully identified through the User Identification feature.
Callback Function Signature
onUgIdentificationComplete({
userStorage: Object
}) => void
Registration Example
window.userGuidingLayer.push({
event: 'onIdentificationComplete',
fn: onUgIdentificationComplete,
})Others
onload
Executes a callback function when the UserGuiding script has loaded and the JavaScript API is ready to use.
Callback Function Signature
onUgload() => void
Registration Example
window.userGuidingLayer.push({
event: 'onLoad',
fn: onUgLoad,
})
Important: For all the above callbacks, ensure that you register them before the events can occur. A common practice is to include all your window.userGuidingLayer.push({...}) calls before the UserGuiding script is loaded (the script will process any events you’ve queued once it initializes), or immediately after loading. Alternatively, you can register events inside the onload event of UserGuiding to ensure that the SDK is ready.
By utilizing these callback functions, you can integrate UserGuiding deeply with your application’s logic — for example, logging events to your analytics, conditionally showing other UI elements, or guiding users based on their interaction with the onboarding content. Each event gives you an opportunity to respond to user behavior in real time, making your user onboarding and support more dynamic and personalized.