How to add guides and surveys to a SvelteKit app

npm install @amplitude/unified

PUBLIC_AMPLITUDE_API_KEY=your-project-api-key

csp: {
  directives: {
    'script-src': ['self', 'https://*.amplitude.com'],
    'connect-src': ['self', 'https://*.amplitude.com'],
    'img-src': ['self', 'https://*.amplitude.com'],
    'media-src': ['self', 'https://*.amplitude.com'],
    'style-src': ['self', 'https://*.amplitude.com'],
  },
},

// Resolves to true once initAll has finished in the browser, or false
// if analytics is off. Nothing awaits it on the server.
let markReady: (ok: boolean) => void = () => {};
export const amplitudeReady = new Promise<boolean>((resolve) => {
  markReady = resolve;
});

export function setAmplitudeReady(init: Promise<unknown> | null) {
  if (!init) {
    markReady(false);
    return;
  }
  init.then(
    () => markReady(true),
    (error) => {
      console.warn('[amplitude] initAll failed', error);
      markReady(false);
    },
  );
}

import { browser } from '$app/environment';

// The window.engagement methods this page calls, as the Guides and Surveys Web SDK docs define them.
type Engagement = {
  setRouter(fn: (url: string) => void): void;
  addCallback(name: string, fn: () => void): void;
  gs: {
    show(key: string, stepIndex?: number): void;
    closeAll(): void;
  };
  _debugStatus?: () => unknown;
};

export function getEngagement(): Engagement | undefined {
  // No window during the server render.
  if (!browser) return undefined;
  return (window as unknown as { engagement?: Engagement }).engagement;
}

import type { ClientInit } from '@sveltejs/kit';
import { dev } from '$app/environment';
import { PUBLIC_AMPLITUDE_API_KEY } from '$env/static/public';
import * as amplitude from '@amplitude/unified';
import { setAmplitudeReady } from '$lib/amplitude-ready';

export const init: ClientInit = () => {
  if (!PUBLIC_AMPLITUDE_API_KEY) {
    console.warn('PUBLIC_AMPLITUDE_API_KEY is not set; analytics is off.');
    setAmplitudeReady(null);
    return;
  }

  // initAll starts analytics, session replay, Feature Experiment, and
  // guides and surveys. Guides and surveys boot with the analytics user.
  setAmplitudeReady(
    amplitude.initAll(PUBLIC_AMPLITUDE_API_KEY, {
      analytics: {
        autocapture: {
          attribution: true,
          pageViews: true,
          sessions: true,
          formInteractions: true,
          fileDownloads: true,
          elementInteractions: true,
        },
      },
      sessionReplay: {
        // Every session while you build; about 1% in production.
        sampleRate: dev ? 1 : 0.01,
        debugMode: dev,
        // From /build/sveltekit-session-replay. Keep your masking rules when you paste this file.
        privacyConfig: {
          maskSelector: ['[data-amp-mask]'],
          blockSelector: ['[data-amp-block]'],
          unmaskSelector: ['[data-amp-unmask]'],
        },
      },
    }),
  );
};

import { goto } from '$app/navigation';
import { base } from '$app/paths';
import { amplitudeReady } from '$lib/amplitude-ready';
import { getEngagement } from '$lib/engagement';

export function registerEngagementBridge() {
  void amplitudeReady.then((ok) => {
    // Analytics is off or initAll failed.
    if (!ok) return;

    const engagement = getEngagement();
    if (!engagement) {
      console.warn('window.engagement not found; guide links will reload the page.');
      return;
    }

    // Guide links set to "Use router" call this instead of reloading.
    engagement.setRouter((url) => {
      const target = new URL(url, window.location.origin);
      const inApp =
        target.origin === window.location.origin &&
        (!base || target.pathname === base || target.pathname.startsWith(`${base}/`));

      // Other sites, and paths outside the app's base path, load normally.
      if (!inApp) {
        window.location.assign(target.href);
        return;
      }

      // goto takes the full path, base path included.
      void goto(target.pathname + target.search + target.hash);
    });

    // Guide buttons with "Run callback" and the name open_new_project.
    engagement.addCallback('open_new_project', () => {
      void goto(`${base}/projects/new`);
    });
  });
}

<script lang="ts">
  import { onMount } from 'svelte';
  import { registerEngagementBridge } from '$lib/engagement-bridge';

  onMount(() => {
    registerEngagementBridge();
  });
</script>

<script lang="ts">
  import { enhance } from '$app/forms';
  import * as amplitude from '@amplitude/unified';
  import { getEngagement } from '$lib/engagement';
</script>

<form
  method="POST"
  action="/logout"
  use:enhance={() => {
    return async ({ result, update }) => {
      if (result.type === 'success' || result.type === 'redirect') {
        getEngagement()?.gs.closeAll(); // close anything still on screen
        amplitude.reset(); // clears the user ID and issues a new device ID
      }
      await update();
    };
  }}
>
  <button>Sign out</button>
</form>

<script lang="ts">
  import { base } from '$app/paths';
</script>

<section data-guide="home">
  <h1>Your projects</h1>
  <a href="{base}/projects/new" data-guide="new-project-button">New project</a>
</section>

<script lang="ts">
  import { getEngagement } from '$lib/engagement';

  function openFeedback() {
    getEngagement()?.gs.show('product-feedback');
  }
</script>

<button type="button" onclick={openFeedback}>Give feedback</button>

<script lang="ts">
  import { onMount } from 'svelte';
  import * as amplitude from '@amplitude/unified';
  import { registerEngagementBridge } from '$lib/engagement-bridge';
  import FeedbackButton from '$lib/components/FeedbackButton.svelte';

  let { data, children } = $props();

  // Guide links and Run callback buttons, registered once in the browser.
  onMount(() => {
    registerEngagementBridge();
  });

  // Layout data reloads after every form action. Only act when the
  // identity actually changes.
  let lastIdentity: string | undefined;

  $effect(() => {
    const id = data.user?.id;
    const plan = data.user?.plan ?? 'unknown';
    const identity = id ? `user-${id}|${plan}` : 'anonymous';
    if (identity === lastIdentity) return;
    lastIdentity = identity;

    // Signed out or not signed in yet: keep the same device ID.
    // Reset only from your sign-out handler.
    if (!id) return;

    // Amplitude drops IDs shorter than 5 characters. Use the same
    // string your server sends as user_id.
    amplitude.setUserId(`user-${id}`);

    const identify = new amplitude.Identify();
    identify.set('plan', plan);
    amplitude.identify(identify);
  });
</script>

<header>
  <FeedbackButton />
</header>

{@render children()}

// -- .env --
PUBLIC_AMPLITUDE_API_KEY=your-project-api-key

// -- src/lib/amplitude-ready.ts --
let markReady: (ok: boolean) => void = () => {};
export const amplitudeReady = new Promise<boolean>((resolve) => {
  markReady = resolve;
});

export function setAmplitudeReady(init: Promise<unknown> | null) {
  if (!init) {
    markReady(false);
    return;
  }
  init.then(
    () => markReady(true),
    (error) => {
      console.warn('[amplitude] initAll failed', error);
      markReady(false);
    },
  );
}

// -- src/lib/engagement.ts --
import { browser } from '$app/environment';

type Engagement = {
  setRouter(fn: (url: string) => void): void;
  addCallback(name: string, fn: () => void): void;
  gs: {
    show(key: string, stepIndex?: number): void;
    closeAll(): void;
  };
  _debugStatus?: () => unknown;
};

export function getEngagement(): Engagement | undefined {
  if (!browser) return undefined;
  return (window as unknown as { engagement?: Engagement }).engagement;
}

// -- src/hooks.client.ts --
import type { ClientInit } from '@sveltejs/kit';
import { dev } from '$app/environment';
import { PUBLIC_AMPLITUDE_API_KEY } from '$env/static/public';
import * as amplitude from '@amplitude/unified';
import { setAmplitudeReady } from '$lib/amplitude-ready';

export const init: ClientInit = () => {
  if (!PUBLIC_AMPLITUDE_API_KEY) {
    console.warn('PUBLIC_AMPLITUDE_API_KEY is not set; analytics is off.');
    setAmplitudeReady(null);
    return;
  }

  setAmplitudeReady(
    amplitude.initAll(PUBLIC_AMPLITUDE_API_KEY, {
      analytics: {
        autocapture: {
          attribution: true,
          pageViews: true,
          sessions: true,
          formInteractions: true,
          fileDownloads: true,
          elementInteractions: true,
        },
      },
      sessionReplay: {
        sampleRate: dev ? 1 : 0.01,
        debugMode: dev,
        // From /build/sveltekit-session-replay. Keep your masking rules when you paste this file.
        privacyConfig: {
          maskSelector: ['[data-amp-mask]'],
          blockSelector: ['[data-amp-block]'],
          unmaskSelector: ['[data-amp-unmask]'],
        },
      },
    }),
  );
};

// -- src/lib/engagement-bridge.ts --
import { goto } from '$app/navigation';
import { base } from '$app/paths';
import { amplitudeReady } from '$lib/amplitude-ready';
import { getEngagement } from '$lib/engagement';

export function registerEngagementBridge() {
  void amplitudeReady.then((ok) => {
    if (!ok) return;

    const engagement = getEngagement();
    if (!engagement) {
      console.warn('window.engagement not found; guide links will reload the page.');
      return;
    }

    engagement.setRouter((url) => {
      const target = new URL(url, window.location.origin);
      const inApp =
        target.origin === window.location.origin &&
        (!base || target.pathname === base || target.pathname.startsWith(`${base}/`));

      if (!inApp) {
        window.location.assign(target.href);
        return;
      }

      void goto(target.pathname + target.search + target.hash);
    });

    engagement.addCallback('open_new_project', () => {
      void goto(`${base}/projects/new`);
    });
  });
}

// -- src/routes/+layout.server.ts --
import type { LayoutServerLoad } from './$types';

export const load: LayoutServerLoad = ({ locals }) => {
  return {
    user: locals.user ? { id: locals.user.id, plan: locals.user.plan } : null,
  };
};

// -- src/routes/+layout.svelte --
<script lang="ts">
  import { onMount } from 'svelte';
  import * as amplitude from '@amplitude/unified';
  import { registerEngagementBridge } from '$lib/engagement-bridge';
  import FeedbackButton from '$lib/components/FeedbackButton.svelte';

  let { data, children } = $props();

  onMount(() => {
    registerEngagementBridge();
  });

  // Layout data reloads after every form action.
  let lastIdentity: string | undefined;

  $effect(() => {
    const id = data.user?.id;
    const plan = data.user?.plan ?? 'unknown';
    const identity = id ? `user-${id}|${plan}` : 'anonymous';
    if (identity === lastIdentity) return;
    lastIdentity = identity;
    if (!id) return;
    // Amplitude drops IDs shorter than 5 characters.
    amplitude.setUserId(`user-${id}`);
    const identify = new amplitude.Identify();
    identify.set('plan', plan);
    amplitude.identify(identify);
  });
</script>

<header>
  <FeedbackButton />
</header>

{@render children()}

// -- src/lib/components/SignOutButton.svelte --
<script lang="ts">
  import { enhance } from '$app/forms';
  import * as amplitude from '@amplitude/unified';
  import { getEngagement } from '$lib/engagement';
</script>

<form
  method="POST"
  action="/logout"
  use:enhance={() => {
    return async ({ result, update }) => {
      if (result.type === 'success' || result.type === 'redirect') {
        getEngagement()?.gs.closeAll();
        amplitude.reset();
      }
      await update();
    };
  }}
>
  <button>Sign out</button>
</form>

// -- src/lib/components/FeedbackButton.svelte --
<script lang="ts">
  import { getEngagement } from '$lib/engagement';

  function openFeedback() {
    getEngagement()?.gs.show('product-feedback');
  }
</script>

<button type="button" onclick={openFeedback}>Give feedback</button>

// -- src/routes/+page.svelte --
// Example: add the data-guide attributes to your own markup.
<script lang="ts">
  import { base } from '$app/paths';
</script>

<section data-guide="home">
  <h1>Your projects</h1>
  <a href="{base}/projects/new" data-guide="new-project-button">New project</a>
</section>

// -- src/routes/projects/new/+page.svelte --
// Your existing page from /build/sveltekit-product-analytics, which tracks
// Project Created from its click handler. The open_new_project callback
// navigates here.

// -- src/app.d.ts and src/hooks.server.ts --
// Unchanged from /build/sveltekit-product-analytics. App.Locals must declare
// user (with id and plan) for +layout.server.ts to type-check.

First complete https://amplitude.com/build/sveltekit-product-analytics, or
confirm this app already has its setup: initAll in the init export of
src/hooks.client.ts, user typed on App.Locals in src/app.d.ts,
src/routes/+layout.server.ts returning user { id, plan }, the identity
$effect in src/routes/+layout.svelte, and SignOutButton.svelte. Then add
Amplitude guides and surveys by following
https://amplitude.com/build/sveltekit-guides-surveys exactly. Use
@amplitude/unified and keep the single initAll call in src/hooks.client.ts,
keeping any sessionReplay.privacyConfig and other options already there. If
you added the setAmplitudeReady(...) wrapper on
/build/sveltekit-feature-flags or /build/sveltekit-guides-surveys, keep it
around initAll. Otherwise create src/lib/amplitude-ready.ts from the page
and pass the initAll promise to setAmplitudeReady() (call
setAmplitudeReady(null) when the key is missing) without returning it from
init. Never call engagement.init() or engagement.boot(), and never
initialize in onMount, a component script, or a load function. Read
window.engagement only through a typed getEngagement() helper in
src/lib/engagement.ts that returns undefined on the server; don't augment
the global Window type. Add registerEngagementBridge() in
src/lib/engagement-bridge.ts, called from onMount in the root
+layout.svelte, that waits for the amplitudeReady promise, returns if it
resolves false, warns in the console if window.engagement is missing, calls
setRouter with goto for same-origin URLs inside the app's base path, and
registers addCallback('open_new_project', ...) that calls
goto(`${base}/projects/new`). Add src/lib/components/FeedbackButton.svelte
that calls getEngagement()?.gs.show('product-feedback') on click, and
render it in a <header> in the root layout. Add
data-guide="new-project-button" to the New project link on the home page
(src/routes/+page.svelte), keeping my existing markup; if the app has no
home page link to /projects/new, add one. Keep the layout's identity
$effect as it is, including its lastIdentity check and any code other
SvelteKit pages added. In the sign-out use:enhance callback, call
getEngagement()?.gs.closeAll() before amplitude.reset(), keep any existing
lines there, and call reset() only after a successful sign-out, never when
the user is null. If kit.csp blocks inline styles, tell me rather than
inventing a nonce workaround. Read PUBLIC_AMPLITUDE_API_KEY from
$env/static/public and don't hardcode it. Tell me session replay records
every session in development and about 1% in production, and how to turn it
off. Report every file you changed.