Public API Methods

The Spotlight global object exposes the following methods for controlling the SDK programmatically.

Method	Description
init(options)	Initialise the SDK (async).
start(tourId?)	Start displaying content or a specific tour (async).
show(contentId)	Programmatically show a piece of content by id (async).
track(eventName, data?)	Fire a custom event for event-triggered content.
stop()	Dismiss all active content.
destroy()	Remove the SDK from the page.
on(event, handler)	Subscribe to an SDK event.
getVersion()	Return the bundled SDK version string.
requestAdminAccess(opts?)	Initiate the admin sign-in flow from the page.

Content fires on the rules attached to it in the admin panel — trigger type, audience, schedule, page match. Tours additionally support programmatic start via start(tourId).

---

init(options)

Initialises the SDK with the provided configuration. Creates the Shadow DOM host element, applies the theme, fetches the tenant configuration from the API, and (if autoStart is true) begins displaying content.

Signature:

Spotlight.init(options: InitOptions): Promise<void>

Parameters:

Parameter	Type	Description
options	InitOptions	Configuration object. Only apiKey is required.

Example:

await Spotlight.init({
  apiKey: 'sk_live_abc123',
  userId: 'user-42',
  tokens: { plan: 'enterprise' },
});

Behaviour:

1. Creates <div id="spotlight-host"> and attaches a Shadow DOM root.
2. Injects base styles and theme CSS custom properties into the shadow root.
3. Fetches tenant configuration from GET /v1/sdk/config.
4. Loads enabled content type modules via dynamic import().
5. If autoStart: true, fetches and evaluates content for the current page.

WARNING

Calling init() more than once is a no-op. To reinitialise with different options, call destroy() first.

---

start(tourId?)

Starts displaying content. If called without arguments, fetches and evaluates all content for the current page and user. If called with a tourId, starts that specific tour.

Signature:

Spotlight.start(tourId?: string): Promise<void>

Parameters:

Parameter	Type	Description
tourId	string (optional)	The ID of a specific tour to start. If omitted, all matching content is evaluated.

Examples:

// Start all content matching the current page
await Spotlight.start();

// Start a specific tour
await Spotlight.start('onboarding-tour');

Behaviour without tourId:

1. Sends POST /v1/sdk/content with the current page URL, user ID, and tokens.
2. The server evaluates audience rules, schedules, progress, and page matching.
3. Returns content items eligible for display.
4. The SDK's TriggerEngine registers listeners for each item's trigger conditions.
5. Content appears when its trigger fires (immediately for page_load, after conditions are met for other trigger types).

Behaviour with tourId:

1. Fetches the specified tour regardless of trigger conditions.
2. Begins the tour at step 1 (or the first step with a valid target element).
3. Ignores audience rules and schedules (manual start overrides all targeting).

---

show(contentId)

Programmatically show a piece of content by id. Bypasses the trigger system entirely — calling show() with event, delay, element_click, etc. content shows it immediately.

Signature:

Spotlight.show(contentId: string): Promise<{ shown: boolean, reason?: string }>

Example:

const result = await Spotlight.show('welcome_modal');
if (!result.shown) {
  console.warn('welcome_modal not loaded on this page:', result.reason);
}

Lookup scope: content already loaded for the current page — i.e. content whose URL pattern matched the current path on init. To make a piece of content reachable from anywhere via show(), give it a global URL pattern (* or empty) in the admin panel.

Return values:

reason	When
(none, shown: true)	Content was rendered.
not_found	No content with that id is loaded for the current page.
invalid_content_id	The argument was empty or missing.
sdk_not_initialised	Called before init().
show_failed	The renderer threw (e.g. missing target element). Check the console with debug: true.

---

track(eventName, data?)

Fires a custom event into the SDK. Two effects:

1. Any content with trigger.type === "event" and a matching event_name fires immediately.
2. Host code subscribed via Spotlight.on('event:<name>', handler) receives the payload.

Signature:

Spotlight.track(eventName: string, data?: object): boolean

Example:

// In your checkout flow, fire after successful purchase
document.querySelector('#checkout').addEventListener('submit', async () => {
  await processCheckout();
  Spotlight.track('purchase_complete', { plan: 'pro', amount: 19 });
});

// In the admin panel, set a content's trigger to:
//   { type: 'event', event_name: 'purchase_complete' }
// — it'll fire as soon as track() is called.

Returns: true if dispatched, false if the name was missing or the SDK isn't initialised.

---

stop()

Stops and hides all currently active content. Dismisses any visible tours, tooltips, modals, banners, spotlights, and hotspots. Clears all active trigger listeners.

Signature:

Spotlight.stop(): void

Example:

// Stop all Spotlight content before showing your own modal
function showAppModal() {
  Spotlight.stop();
  myModal.open();
}

Behaviour:

1. Fires content:dismiss events for any visible content.
2. Removes all rendered Spotlight components from the Shadow DOM.
3. Disconnects all trigger listeners (IntersectionObserver, scroll, idle, etc.).
4. Does not destroy the SDK -- call start() to resume.

---

destroy()

Completely removes the SDK from the page. Removes the Shadow DOM host element, clears all state, disconnects all observers and listeners, and cleans up all internal references.

Signature:

Spotlight.destroy(): void

Example:

// Clean up when user logs out
function handleLogout() {
  Spotlight.destroy();
  redirectToLogin();
}

Behaviour:

1. Calls stop() to dismiss all active content.
2. Removes <div id="spotlight-host"> from the DOM (including the shadow root and all children).
3. Disconnects all MutationObservers and IntersectionObservers.
4. Clears all setTimeout/setInterval handles.
5. Removes the SPA navigation listener.
6. Resets internal state. The SDK can be re-initialised with a new init() call.

WARNING

After calling destroy(), any references to SDK internals become invalid. Always call init() before using any other SDK method after a destroy.

---

on(event, handler)

Registers a callback for an SDK lifecycle event. Returns an unsubscribe function.

Signature:

Spotlight.on(event: string, handler: (data: EventData) => void): () => void

Parameters:

Parameter	Type	Description
event	string	The event name. See Events for the full list.
handler	(data: EventData) => void	Callback function invoked when the event fires.

Returns: A function that, when called, removes the event listener.

Example:

// Listen for content dismissal
const unsubscribe = Spotlight.on('content:dismiss', (data) => {
  console.log(`User dismissed content: ${data.contentId}`);
});

// Later, remove the listener
unsubscribe();

See Events for the complete list of event names and their payload shapes.

---

getVersion()

Returns the bundled SDK version string (semver).

Signature:

Spotlight.getVersion(): string

Example:

console.log('Spotlight SDK version:', Spotlight.getVersion());
// 'Spotlight SDK version: 1.0.0'

Returns '0.0.0' if the SDK has not been initialised.

---

requestAdminAccess(opts?)

Initiates the admin sign-in flow from the running SDK on the page. Used by the bookmarklet / overlay to bootstrap an authoring session for the current tenant.

Signature:

Spotlight.requestAdminAccess(opts?: object): Promise<void>

Calling this requires the SDK to be initialised (init() first). The exact options accepted are evolving; see frontend-sdk/src/index.js for the current contract.