Tracking events
Subscribe to SDK events (session starts, user messages, captured fields, and action clicks) for your analytics.
The SDK emits events you can subscribe to for analytics. You need the embed.js script from the quick start on the page.
window.handhold only exists once embed.js has executed, so attach listeners from the script's load event (or any code that is guaranteed to run after it):
<script
async
src="https://handhold.io/demo/embed.js"
onload="window.handhold.addEventListener('onusermessage', (data) => console.log(data))"
></script>Unsubscribe with window.handhold.removeEventListener('onusermessage', handler). Attaching from React or Vue components is shown in the framework examples.
Events
| Event name | Description | Payload |
|---|---|---|
onusermessage | User sends a message via the input | { event, agentId, sessionId } |
onclose | User closes the demo overlay | { event, agentId, sessionId? } |
onfieldvalueset | A discovery field value is captured | { event, agentId, sessionId, field: { id, name, type }, value } |
onnudgeaction | User clicks a nudge action | { event, agentId, sessionId?, actionId, label? } |
onsessionstarted | A session starts | { event, agentId, sessionId, qualificationFieldPresets? } |
onsessionfinished | AI agent completes the session | { event, agentId, sessionId } |
onactionclick | User clicks an action button (e.g. CTA on the finished screen) | { event, agentId, sessionId, actionId, label } |
For AI agents: a clean Markdown version is available at /docs/events.md.