Initialisation Options

The Spotlight.init() method accepts a configuration object that controls all aspects of SDK behaviour. Only apiKey is required.

Basic Usage

Spotlight.init({
  apiKey: 'sk_live_your_api_key_here',
});

Full Configuration

Spotlight.init({
  // Required
  apiKey: 'sk_live_abc123def456',

  // API
  baseUrl: 'https://api.example.com',

  // User identification
  userId: 'user-42',
  tokens: { plan: 'enterprise', role: 'admin' },
  tokenSource: 'cookie',
  tokenKey: 'spot_session',

  // Behaviour
  autoStart: true,
  demoMode: false,
  debug: false,
  allowKeyboardNav: true,

  // Theming
  theme: {
    '--spot-primary': '#4f46e5',
    '--spot-radius': '8px',
  },
  customCSS: '',

  // Admin overlay
  overlay: true,
});

Option Reference

`apiKey`


Type	`string`
Required	Yes
Default	--

Your Spotlight API key. Starts with sk_live_ for production or sk_test_ for staging environments. Obtained from the Spotlight admin panel under Settings > API Keys.

Spotlight.init({
  apiKey: 'sk_live_abc123def456',
});

DANGER

Never use a production API key (sk_live_) in a staging or development environment. Use sk_test_ keys instead. Production keys track real user analytics and count towards your billing.

`baseUrl`


Type	`string`
Required	No
Default	`'https://api.example.com'`

The base URL for the Spotlight API. Override this if you are using a self-hosted deployment, a custom domain, or need to point at a staging API.

Spotlight.init({
  apiKey: 'sk_test_abc123',
  baseUrl: 'https://spotlight-staging.yourcompany.com/api',
});

`userId`


Type	`string`
Required	No
Default	`undefined`

A unique identifier for the current user. When provided, the SDK tracks per-user progress (which tours have been completed, which steps viewed, which content dismissed) and evaluates audience targeting rules.

When not provided, the SDK operates in anonymous mode -- content is shown without progress tracking or audience targeting.

Spotlight.init({
  apiKey: 'sk_live_abc123',
  userId: getCurrentUser().id,
});

TIP

Set userId to a stable identifier from your authentication system (database ID, auth provider sub). Avoid using email addresses or other PII as user IDs.

`tokens`


Type	`Record<string, string>`
Required	No
Default	`{}`

Key-value pairs of user attributes used for audience targeting. These tokens are sent with every SDK content request and evaluated against audience rules defined in the admin panel.

Spotlight.init({
  apiKey: 'sk_live_abc123',
  userId: 'user-42',
  tokens: {
    plan: 'enterprise',
    role: 'admin',
    signup_date: '2025-01-15',
    company: 'Acme Corp',
  },
});

Common token patterns:

Token	Example Values	Use Case
`plan`	`'free'`, `'pro'`, `'enterprise'`	Show upgrade prompts to free users
`role`	`'viewer'`, `'editor'`, `'admin'`	Target admin-only feature tours
`signup_date`	`'2025-01-15'`	Target users who signed up recently
`company`	`'Acme Corp'`	Target specific accounts

`tokenSource`


Type	`'cookie' \| 'localStorage' \| 'header' \| 'manual'`
Required	No
Default	`'manual'`

Where the SDK reads authentication tokens from. This determines how the SDK authenticates its API requests.

'manual' -- Tokens are provided directly via the tokens option (default).
'cookie' -- The SDK reads a session cookie specified by tokenKey.
'localStorage' -- The SDK reads from localStorage using tokenKey.
'header' -- The SDK includes a custom header in API requests.

Spotlight.init({
  apiKey: 'sk_live_abc123',
  tokenSource: 'cookie',
  tokenKey: 'session_id',
});

`tokenKey`


Type	`string`
Required	When `tokenSource` is `'cookie'`, `'localStorage'`, or `'header'`
Default	`undefined`

The key name used to read the authentication token from the configured tokenSource. Ignored when tokenSource is 'manual'.

`autoStart`


Type	`boolean`
Required	No
Default	`true`

When true, the SDK automatically fetches content from the API after initialisation and displays any content that matches the current page and user. When false, the SDK initialises but does not fetch or display content until you call Spotlight.start() or Spotlight.show(contentId).

// Delay content display until after your app has finished loading
Spotlight.init({
  apiKey: 'sk_live_abc123',
  autoStart: false,
});

// Later, when your app is ready:
myApp.onReady(() => {
  Spotlight.start();
});

`demoMode`


Type	`boolean`
Required	No
Default	`false`

When true, the SDK renders content without sending analytics events or tracking user progress. Content is always shown regardless of audience rules, schedules, or completion state. Useful for demos, testing, and local development.

Spotlight.init({
  apiKey: 'sk_test_abc123',
  demoMode: true,
});

WARNING

Demo mode bypasses all targeting rules, progress tracking, and event recording. Never enable it in production.

`debug`


Type	`boolean`
Required	No
Default	`false`

When true, the SDK logs detailed information to the browser console, including:

Configuration resolution
API requests and responses
Content matching decisions
Element targeting attempts and results
Trigger evaluation
Event dispatch

Spotlight.init({
  apiKey: 'sk_test_abc123',
  debug: true,
});

Console output is prefixed with [Spotlight] for easy filtering.

TIP

Enable debug during development to understand why specific content is or is not appearing. Combine with demoMode: true to see all content regardless of targeting rules.

`allowKeyboardNav`


Type	`boolean`
Required	No
Default	`true`

When true, users can navigate tours using keyboard shortcuts:

Key	Action
`ArrowRight` / `Enter`	Next step
`ArrowLeft`	Previous step
`Escape`	Dismiss tour

Set to false if these keyboard shortcuts conflict with your application's own key bindings.

Spotlight.init({
  apiKey: 'sk_live_abc123',
  allowKeyboardNav: false,
});

`theme`


Type	`Record<string, string>`
Required	No
Default	`{}`

A flat object of --spot-* CSS custom property overrides. These values are applied as inline styles on the Shadow DOM host element and cascade into all Spotlight components. Any properties not specified use the defaults from your tenant's theme (configured in the admin panel) or the built-in defaults.

Spotlight.init({
  apiKey: 'sk_live_abc123',
  theme: {
    '--spot-primary': '#FF6B00',
    '--spot-radius': '12px',
    '--spot-font-family': '"Inter", sans-serif',
  },
});

See Theming for the full list of supported CSS custom properties.

`customCSS`


Type	`string`
Required	No
Default	`''`

An optional CSS string injected as a <style> block inside the Shadow DOM root. This is an advanced escape hatch for styling that cannot be achieved with --spot-* custom properties alone.

Spotlight.init({
  apiKey: 'sk_live_abc123',
  customCSS: `
    .spot-tooltip__title {
      text-transform: uppercase;
      letter-spacing: 0.05em;
    }
  `,
});

DANGER

Custom CSS targets internal class names that are not a stable API. These class names may change between SDK versions without notice. Use --spot-* custom properties whenever possible.

`overlay`


Type	`boolean`
Required	No
Default	`true`

When true and the current user has admin permissions (AuthContext.is_admin), the SDK loads the admin overlay. The overlay enables visual tour building, element selection, theme editing, and content preview directly on your live application.

When false, the admin overlay is never loaded, even for admin users. This is useful for performance-critical pages where the additional ~15KB admin bundle is undesirable.

Spotlight.init({
  apiKey: 'sk_live_abc123',
  overlay: false, // Never load admin overlay on this page
});

Complete Example

Spotlight.init({
  apiKey: 'sk_live_abc123def456',
  baseUrl: 'https://api.example.com',
  userId: currentUser.id,
  tokens: {
    plan: currentUser.plan,
    role: currentUser.role,
    company: currentUser.company.name,
  },
  autoStart: false,
  debug: process.env.NODE_ENV === 'development',
  demoMode: false,
  allowKeyboardNav: true,
  theme: {
    '--spot-primary': '#4f46e5',
    '--spot-font-family': '"Inter", system-ui, sans-serif',
    '--spot-radius': '8px',
  },
  overlay: true,
});

// Start after app is fully loaded
appRouter.onReady(() => {
  Spotlight.start();
});

Auto-Init via Script Tag

When using the script tag with data-api-key, the SDK auto-initialises on load:

html

<script
  src="https://sdk.example.com/latest/spotlight.min.js"
  data-api-key="sk_live_abc123"
  data-user-id="user-42"
  data-debug="true"
  data-auto-start="false"
  async
></script>

Supported data-* attributes:

Attribute	Maps to Option
`data-api-key`	`apiKey`
`data-base-url`	`baseUrl`
`data-user-id`	`userId`
`data-auto-start`	`autoStart`
`data-demo-mode`	`demoMode`
`data-debug`	`debug`
`data-allow-keyboard-nav`	`allowKeyboardNav`
`data-overlay`	`overlay`

For complex options (tokens, theme, customCSS), use the JavaScript init() method instead.

Initialisation Options ​

Basic Usage ​

Full Configuration ​

Option Reference ​

apiKey ​

baseUrl ​

userId ​

tokens ​

tokenSource ​

tokenKey ​

autoStart ​

demoMode ​

debug ​

allowKeyboardNav ​

theme ​

customCSS ​

overlay ​

Complete Example ​

Auto-Init via Script Tag ​