Configuration

Full reference for all SDK initialisation options. Pass these as an object to Spotlight.init().

Initialisation

await Spotlight.init({
  apiKey: 'sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  // ... other options
});

If you load the SDK via a <script> tag with data-api-key, the apiKey is read automatically and init() is called for you with default settings. To customise options, call init() explicitly instead.

Options Reference

Option	Type	Default	Description
apiKey	string	null	Required. API key identifying your tenant. Read from the data-api-key script attribute if not provided.
baseUrl	string	'https://api.example.com'	Base URL of the Spotlight API. The hosted production endpoint is https://api.spotlight.help; override for self-hosted deployments. Trailing slashes are stripped.
tokenSource	'cookie' | 'localStorage'	'cookie'	Where to read the user's JWT auth token.
tokenKey	string	'auth_token'	Name of the cookie or localStorage key containing the JWT.
debug	boolean	false	Enable verbose console logging for content loading, events, and navigation.
autoStart	boolean	true	Automatically load and display content for the current page on init. Set to false to control content loading manually.
zIndex	number	999999	Base z-index for the SDK's Shadow DOM host element.
overlay	boolean	true	Show a backdrop overlay with cutout around the target element during tours.
allowKeyboardNav	boolean	true	Enable keyboard navigation in tours (arrow keys, Enter, Escape).
closeOnOverlayClick	boolean	true	Dismiss the current tour or content when the user clicks the backdrop overlay.
closeOnEscape	boolean	true	Dismiss the current tour when the user presses the Escape key.
scrollBehavior	'smooth' | 'auto' | 'instant'	'smooth'	Scroll behaviour when bringing a target element into view.
padding	number	8	Padding (in pixels) around the target element's cutout in the overlay.
demoMode	'admin' | 'user' | null	null	Enable demo mode for local development. Sends X-Spotlight-Demo-Mode header. The backend must have ALLOW_DEMO_AUTH=true set.
userId	string | null	null	Override user identification for demo or testing purposes. Sends X-Spotlight-Demo-User header.
tokens	object	{}	Personalisation tokens for content rendering (e.g. { user_name: 'Jane' }). Used by the backend's token renderer to substitute in tour content.

Minimal Configuration

The only required option is apiKey. Everything else has sensible defaults:

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

Common Configurations

SPA with localStorage Auth

await Spotlight.init({
  apiKey: 'sk_live_xxxx',
  tokenSource: 'localStorage',
  tokenKey: 'access_token',
});

Self-Hosted with Debug

await Spotlight.init({
  apiKey: 'sk_live_xxxx',
  baseUrl: 'https://spotlight.yourcompany.com/api',
  debug: true,
});

Manual Content Loading

Disable auto-start and load content yourself when the page is ready:

await Spotlight.init({
  apiKey: 'sk_live_xxxx',
  autoStart: false,
});

// Later, when your page is ready:
await Spotlight.start('tour_onboarding_v1');

Personalisation Tokens

Pass user-specific tokens that are substituted into tour content at render time:

await Spotlight.init({
  apiKey: 'sk_live_xxxx',
  tokens: {
    user_name: 'Jane',
    company_name: 'Acme Corp',
    plan: 'Pro',
  },
});

In tour content, use and the backend renders it as Jane.

Development Demo Mode

For local development without a real JWT:

await Spotlight.init({
  apiKey: 'sk_live_xxxx',
  baseUrl: 'http://localhost:8000',
  demoMode: 'admin', // 'admin' or 'user'
  userId: 'dev-user-1',
  debug: true,
});

Demo mode is for development only

The backend only honours X-Spotlight-Demo-Mode when the ALLOW_DEMO_AUTH environment variable is set. This is never enabled in production.

Public API Methods

After initialisation, the SDK exposes these methods on the Spotlight global (or the default export if using ESM):

init(config)

Initialise the SDK. Can only be called once. Call destroy() first to re-initialise.

await Spotlight.init({ apiKey: 'sk_live_xxxx' });

start(tourId)

Start a specific tour by ID. Fetches content from the API and renders the tour if found:

await Spotlight.start('tour_onboarding_v1');

stop()

Stop the currently active tour without destroying the SDK. Content and hotspots remain available:

Spotlight.stop();

destroy()

Tear down the SDK completely. Removes all UI, cleans up event listeners, and flushes pending analytics:

Spotlight.destroy();

on(event, handler)

Subscribe to SDK lifecycle and analytics events. Returns an unsubscribe function:

const unsubscribe = Spotlight.on('tour:complete', (data) => {
  console.log('Tour completed:', data.tourId);
});

// Later:
unsubscribe();

Events

The SDK emits these events via the on() method:

Event	Payload	Description
sdk:init	{ config }	SDK successfully initialised
sdk:navigate	{ path }	SPA navigation detected
sdk:stop	--	Tour stopped via stop()
sdk:destroy	--	SDK destroyed
tour:complete	{ tourId }	User finished all steps in a tour
tour:dismiss	{ tourId }	User dismissed a tour before completion
content:dismiss	{ contentId }	User dismissed standalone content (tooltip, modal, banner)
analytics:event	{ type, contentId, data }	Any analytics event was tracked

Keyboard Shortcuts

When allowKeyboardNav is true and a tour is active:

Key	Action
ArrowRight / Enter	Advance to the next step
ArrowLeft	Go back to the previous step
Escape	Dismiss the tour (when closeOnEscape is true)

Theme Variables

The SDK's appearance is controlled by CSS custom properties set on the Shadow DOM host. These are configured per-tenant in the backend and applied at runtime. The full list of variables is documented in the Theming guide.

Key variables include:

Variable	Default	Description
--spot-primary	#4f46e5	Primary brand colour
--spot-primary-hover	#4338ca	Hover state for primary colour
--spot-primary-text	#ffffff	Text colour on primary backgrounds
--spot-bg	#ffffff	Background colour for tooltips and modals
--spot-text	#111827	Main text colour
--spot-text-secondary	#6b7280	Secondary text colour
--spot-border	#e5e7eb	Border colour
--spot-radius	8px	Border radius for components
--spot-font-family	system-ui, -apple-system, sans-serif	Font stack
--spot-overlay-bg	rgba(0, 0, 0, 0.5)	Backdrop overlay colour
--spot-hotspot-color	#4f46e5	Pulsing hotspot indicator colour
--spot-z-index	999999	Z-index for SDK elements