Tour Builder

The tour builder is the primary admin overlay tool for creating and managing guided product tours. It provides a visual wizard flow for composing multi-step tours, a step editor for configuring each step's content and targeting, and a preview mode for testing tours before publishing.

Tour Lifecycle

Tours follow a defined lifecycle managed through the admin API:

Draft  -->  Published  -->  Archived
  ^            |
  |            v
  +--- (new version)

Status	Visible to Users	Editable
draft	No	Yes
published	Yes	No (create new version)
archived	No	No (can duplicate)

Each publish creates a new version stored in Spotlight.Tours.Versions with an auto-incrementing version number.

Wizard Flow

The tour builder guides admins through a structured creation process:

Step 1 -- Tour Settings

Configure the tour's metadata and targeting rules:

{
  "title": "Getting Started with Analytics",
  "description": "Walk new users through the analytics dashboard",
  "url_patterns": [
    { "pattern": "/dashboard/analytics*", "is_regex": false }
  ],
  "audience_id": "aud_new_users",
  "priority": 100,
  "rollout": {
    "enabled": true,
    "percentage": 50
  },
  "schedule": {
    "start_at": "2025-06-01T00:00:00Z",
    "end_at": null
  }
}

URL patterns determine which pages the tour applies to. Patterns support both glob-style matching and regex:

/dashboard/*          -- matches /dashboard/analytics, /dashboard/reports
/projects/*/settings  -- matches /projects/123/settings
^/app/v2/.*           -- regex: any path under /app/v2/

Audience links the tour to a predefined audience segment (e.g., new users, trial users, enterprise plan).

Rollout allows gradual rollout by percentage, so you can test a tour with a subset of users before full deployment.

Step 2 -- Add Steps

Each step in a tour targets a specific element and displays content:

{
  "step_id": "step_1",
  "title": "Welcome to Analytics",
  "body": "This is your analytics dashboard. Let's explore the key metrics.",
  "element_target": {
    "data_attribute": "analytics-overview",
    "description": "Analytics overview panel"
  },
  "positioning": {
    "placement": "bottom",
    "offset_x": 0,
    "offset_y": 8,
    "arrow": true
  },
  "advance_on": "click",
  "highlight_element": true
}

The step editor provides:

• Element selection -- click any element on the page to target it. The element selector evaluates confidence automatically.
• Content editing -- rich text editor for title and body fields.
• Positioning controls -- dropdown for placement (top, bottom, left, right, auto) and numeric offset inputs.
• Advance conditions -- configure how the user proceeds: button click, target element click, custom event, or timed auto-advance.
• Spotlight mode -- toggle the backdrop overlay that dims everything except the targeted element.

Step 3 -- Configure Triggers

Define when the tour should appear:

{
  "trigger": {
    "trigger_type": "page_load",
    "delay_ms": 2000
  }
}

Supported trigger types:

Trigger Type	Description	Options
page_load	Fires when the matching page loads	delay_ms
element_visible	Fires when a specific element enters the viewport	trigger_element
event	Fires when your app dispatches a named event	event_name
visit_count	Fires on the Nth visit to the page	visit_count
idle	Fires after user is idle for N seconds	idle_seconds
scroll_depth	Fires when user scrolls past a percentage	scroll_percentage

Step 4 -- Localization (Optional)

Add translations for multi-locale deployments:

{
  "default_locale": "en",
  "locale_variants": {
    "es": {
      "title": "Bienvenido a Analytics",
      "body": "Este es tu panel de analytics. Exploremos las metricas clave."
    },
    "fr": {
      "title": "Bienvenue sur Analytics",
      "body": "Voici votre tableau de bord analytics. Explorons les metriques cles."
    }
  }
}

Step 5 -- Review and Publish

The review screen shows a summary of all configuration. From here admins can:

• Save as draft -- persist without making visible to users.
• Preview -- enter preview mode to walk through the tour.
• Publish -- create a version and make the tour live.

Preview Mode

Preview mode lets admins experience the tour exactly as end users would, without affecting analytics or user progress:

1. Activate preview from the tour builder or from the tours list.
2. The tour renders with a "Preview Mode" banner.
3. Events are not recorded -- no impact on completion rates or analytics.
4. Navigation between steps works identically to the live experience.
5. Exit preview to return to the editor with any notes.

Preview after changes

Always preview a tour after editing. Selectors may not resolve if the target element is behind a route change or lazy-loaded component.

Version Management

Publishing a tour creates an immutable version snapshot in the Spotlight.Tours.Versions table:

Spotlight.Tours.Versions
PK: tenant_tour_id = "tenant_abc#tour_456"
SK: version = 1, 2, 3, ...

The Spotlight.Tours.Definitions table always holds the current working state. When users view a published tour, the SDK fetches the latest published version.

Admin actions on versions:

Action	API Endpoint	Audit Event
Publish new version	POST /v1/admin/tours/{id}/publish	TourPublishedByAdmin
View version history	GET /v1/admin/tours/{id}/versions	--
Roll back to version	POST /v1/admin/tours/{id}/rollback	TourVersionRolledBackByAdmin
Copy tour	POST /v1/admin/tours/{id}/copy	TourCopiedByAdmin

Feature Flags

Tours can be gated behind feature flags for conditional activation:

{
  "feature_flag": "show_analytics_tour"
}

The feature_flag field is a plain string (max 200 chars). The SDK checks the named flag at render time via its host application's feature-flag provider; if the flag evaluates to false, the tour is not displayed regardless of other targeting criteria.

API Reference

All tour management operations go through the admin API:

# List tours
GET /v1/admin/tours?limit=20&offset=0

# Create tour
POST /v1/admin/tours

# Get tour
GET /v1/admin/tours/{tour_id}

# Update tour
PUT /v1/admin/tours/{tour_id}

# Publish tour
POST /v1/admin/tours/{tour_id}/publish

# Archive tour
POST /v1/admin/tours/{tour_id}/archive

# Duplicate tour
POST /v1/admin/tours/{tour_id}/duplicate

# Get version history
GET /v1/admin/tours/{tour_id}/versions

# Roll back to version
POST /v1/admin/tours/{tour_id}/rollback

All endpoints require admin authentication. See Admin API Endpoints for full request/response schemas.