Spotlight

Appearance

Getting Started ​

Spotlight running on your site in about 15 minutes. You'll sign in, mint an API key for a project, drop a script tag into your app, and ship your first tour from the dashboard.

What you'll need ​

  • A modern browser
  • Edit access to your application's HTML (or build pipeline)
  • Optional: a JWT-based user identity in your app (so Spotlight can show per-user tours and track per-user progress). Without it, every visitor is treated as anonymous.

1. Sign in to the dashboard ​

The hosted dashboard lives at https://dashboard.spotlight.help. Auth is via Clerk — if you don't have an account yet, the sign-in page will walk you through creating one.

The first time you sign in you'll land on the tenant switcher. A tenant is one organisation's workspace; pick the one you've been invited to (or, if you're the platform super-admin, click + New tenant).

2. Create a project ​

Inside a tenant, projects are the unit of isolation that a key binds to. One project per site / environment is the usual setup (e.g. app.acme.com and staging.acme.com get separate projects).

Sidebar → Projects → + New project → give it a name (Production, Staging, …) and a URL slug. The first project you create is auto-marked as the tenant's default.

3. Mint an API key ​

Inside the project: API keys → + New key.

  • Name — anything memorable, e.g. Production embed.
  • Environment — live for the real site, test for staging / preview branches.

Hit Mint key. The full sk_live_... (or sk_test_...) string is shown once — copy it somewhere safe right now. After this, only the prefix is kept; if you lose it, mint another and revoke the original.

Keys are project-scoped. The tenant UUID is encoded into the key string itself, so the API can resolve the tenant without a cross-tenant scan. Treat the key like a publishable secret — safe to embed in page source under origin lockdown.

4. Lock the key to your domains ​

Still inside the project: Sites → add the origins this key is allowed to run on, e.g. https://app.acme.com, https://www.acme.com. The API rejects browser requests from any other origin (server-to-server calls without an Origin header are still allowed).

A tenant that hasn't configured any origins is in default-deny for browser requests — the SDK will fail to load until at least one origin is registered.

5. Drop the SDK into your page ​

Pick the variant that matches your stack:

html
<script
  src="https://sdk.spotlight.help/latest/spotlight.min.js"
  data-api-key="sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  defer
></script>
html
<script src="https://sdk.spotlight.help/latest/spotlight.min.js" defer></script>
<script>
  Spotlight.init({
    apiKey: 'sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    baseUrl: 'https://api.spotlight.help',
    userId: window.CURRENT_USER_ID,    // your user identifier; omit for anonymous
    tokens: { plan: 'pro' },           // attributes for audience targeting
  });
</script>

The SDK reads the data-api-key attribute (or the explicit init() call), creates a Shadow-DOM host on the page, fetches the tenant config from https://api.spotlight.help, and starts listening for trigger conditions.

You can verify it loaded by opening DevTools and looking for the spotlight-host element under <body>, or by enabling debug mode:

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

Debug mode logs every content fetch, trigger evaluation, and event to the browser console.

6. Author your first tour ​

Two ways:

From the dashboard ​

Sidebar → Tours (inside your project) → + New tour → walk the four-step wizard:

  1. Steps — what each tooltip says + which element it points at. Use the URL of your real site in the Preview field; the dashboard's element picker iframes your page so you can click the target instead of writing selectors by hand.
  2. Trigger — when the tour starts (page_load, first_visit, event, idle, scroll_depth, etc.).
  3. Audience — who sees it (rules over the tokens you sent in Spotlight.init).
  4. Review — preview, then publish.

From the bookmarklet ​

If editing on the live site is easier than using the picker: sidebar → Bookmarklet → drag the link to your bookmarks bar. Open your site, click the bookmarklet — Spotlight loads in admin mode and you can author tours directly on the page.

7. Verify it's live ​

Open your site, hit the URL you matched, and the tour should appear. If it doesn't:

  • Browser console: look for [Spotlight] logs. With debug: true, you'll see why the tour was skipped (trigger didn't match, target selector not found, audience rule excluded the user, etc.).
  • Dashboard → Tours → Analytics: shows per-tour view / completion counts so you can confirm events are reaching the backend.
  • Dashboard → Audit log: shows every admin action with the Clerk user who took it.

Next steps ​

  • Configuration — the full set of init() options
  • Targeting — how to pick stable selectors that survive UI changes
  • MCP — connect Claude Desktop and let an agent author tours for you
  • Architecture — how the pieces fit together

Spotlight