Advanced

Custom Events

GuideSail emits browser CustomEvents on window throughout the guide lifecycle. Use these to react to guide activity — for example, tracking completions in your analytics, showing UI elements after a guide ends, or syncing state with your app.

Events fire for both automatic and manual guides.

---

guideStarted

Fired when a guide begins.

window.addEventListener('guideStarted', (e) => {
  console.log(e.detail)
})

Property	Type	Description
guideId	string	ID of the guide that started
title	string	Title of the guide
stepCount	number	Total number of steps
trigger	'automatic' | 'manual'	How the guide was launched
timestamp	number	Unix timestamp of when it started

---

guideStepChanged

Fired each time the user advances to a new step.

window.addEventListener('guideStepChanged', (e) => {
  console.log(e.detail)
})

Property	Type	Description
guideId	string	ID of the active guide
stepIndex	number	Zero-based index of the current step
stepCount	number	Total number of steps

---

guideEnded

Fired when a guide is completed or dismissed.

window.addEventListener('guideEnded', (e) => {
  console.log(e.detail)
})

Property	Type	Description
guideId	string	ID of the guide that ended
completedSteps	number	Number of steps the user reached before ending

---

Example — track completion in your analytics

window.addEventListener('guideEnded', (e) => {
  const { guideId, completedSteps } = e.detail

  myAnalytics.track('Guide Ended', {
    guideId,
    completedSteps,
  })
})

Example — show a follow-up prompt after a guide finishes

window.addEventListener('guideEnded', (e) => {
  if (e.detail.guideId === 'YOUR_GUIDE_ID') {
    document.querySelector('#followup-banner').style.display = 'block'
  }
})