Event Reference

Overview

The SDK automatically tracks events as users interact with Stories. This reference documents every event type, when it fires, and what properties it includes.

Event Structure

All events share this base structure:

interface AnalyticsEvent {
  // Event identity
  event: string           // Event type (see below)
  eventId: string         // UUID v4, unique per event

  // App context
  appId: string           // Your app ID

  // Story context
  carouselId?: string     // Story ID
  carouselName?: string   // Story name from dashboard
  carouselVersion?: number
  storyVersion?: string   // Content version hash

  // Screen context
  screenIndex?: number    // 0-based screen position
  screenId?: string       // Screen identifier

  // Element context
  elementId?: string      // Interacted element ID
  elementType?: string    // Element type (button, toggle, etc.)

  // User context
  userId?: string         // Set via identify()
  deviceId: string        // Persistent device ID
  sessionId: string       // Current session ID

  // Timing
  timestamp: number       // Client timestamp (ms)
  serverTimestamp?: number // Added by server

  // Device info
  platform: 'ios' | 'android' | 'web'
  osVersion: string
  appVersion: string
  sdkVersion: string

  // A/B testing
  experimentId?: string   // If in an experiment
  variantId?: string      // Assigned variant

  // Custom data
  properties?: Record<string, any>
}

Story Lifecycle Events

carousel_viewed

Fired when a Story is displayed to the user.

When: Snoopr.showStory() or Snoopr.showScreen() is called and the modal appears.

Properties:

Example:

{
  "event": "carousel_viewed",
  "carouselId": "story-123",
  "carouselName": "Onboarding Flow",
  "properties": {
    "trigger": "showStory",
    "screensCount": 5
  }
}

carousel_completed

Fired when a user reaches the last screen and the Story closes successfully.

When: User taps the final button or the Story auto-closes after the last screen.

Properties:

carousel_dismissed

Fired when a user closes the Story before completing.

When: User taps dismiss button, swipes to close, or taps outside the modal.

Properties:

carousel_skipped

Fired when a user taps a Close button before the final screen.

When: User taps a button with Close action before reaching the last screen.

Screen Events

screen_viewed

Fired when a screen becomes visible.

When: Story opens (first screen) or user navigates to a new screen.

Properties:

Example:

{
  "event": "screen_viewed",
  "carouselId": "story-123",
  "screenIndex": 2,
  "screenId": "interests",
  "properties": {
    "screenTitle": "What are you interested in?"
  }
}

screen_time

Fired when leaving a screen to track time spent.

When: User navigates away from a screen or Story closes.

Properties:

Interaction Events

button_clicked

Fired when a user taps a button.

When: Any button element is tapped.

Properties:

Example:

{
  "event": "button_clicked",
  "elementType": "button",
  "screenIndex": 0,
  "properties": {
    "actionType": "next"
  }
}

element_clicked

Fired when any interactive element is tapped (excluding buttons).

When: User taps on cards, images, or other interactive elements.

element_interaction

Fired when a data-capture element value changes.

When: User makes a selection, toggles a switch, or changes any input value.

Properties (for selections):

Properties (for toggles):

Example (selection):

{
  "event": "element_interaction",
  "elementType": "selection",
  "screenIndex": 2,
  "properties": {
    "elementName": "interests",
    "selectedCount": 3,
    "values": ["fitness", "nutrition", "sleep"]
  }
}

swipe_gesture

Fired when a user swipes on the Story modal.

When: User performs a swipe gesture (navigation or dismiss attempt).

Error Events

carousel_error

Fired when a Story fails to load or render.

When: API error, network failure, or rendering exception.

Properties:

api_error

Fired when an API request fails.

When: Story fetch, analytics send, or other API call fails.

Properties:

New to Snoopr Analytics? See the Analytics Overview for dashboard features.

Related

• Analytics Configuration - Setup and options
• A/B Testing - Experiment tracking