How to add guides and surveys to an Angular app

npm install @amplitude/unified

Content-Security-Policy: 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 'unsafe-inline'
Cross-Origin-Opener-Policy: same-origin-allow-popups

// 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): void {
  if (!init) {
    markReady(false);
    return;
  }
  init.then(
    () => markReady(true),
    (error: unknown) => {
      console.warn('[amplitude] initAll failed', error);
      markReady(false);
    },
  );
}

// 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 server rendering.
  if (typeof window === 'undefined') return undefined;
  return (window as unknown as { engagement?: Engagement }).engagement;
}

// Keep lines other Angular pages added here: debugMode and privacyConfig
// (/build/angular-session-replay), pageViews: { trackHistoryChanges: 'pathOnly' }
// (/build/angular-web-analytics), the experiment block and deviceId handoff
// (/build/angular-feature-flags), and the webExperiment.plugin() registration
// (/build/angular-web-experiment).
import * as amplitude from '@amplitude/unified';
import { environment } from '../environments/environment';
import { setAmplitudeReady } from './amplitude-ready';

export function initAmplitude(): void {
  if (!environment.amplitudeApiKey) {
    console.warn('amplitudeApiKey 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(environment.amplitudeApiKey, {
      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: environment.production ? 0.01 : 1,
        debugMode: !environment.production,
        // From /build/angular-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 { Injectable, NgZone, PLATFORM_ID, inject } from '@angular/core';
import { HashLocationStrategy, LocationStrategy, isPlatformBrowser } from '@angular/common';
import { Router } from '@angular/router';
import { amplitudeReady } from './amplitude-ready';
import { getEngagement } from './engagement';

@Injectable({ providedIn: 'root' })
export class EngagementBridgeService {
  private readonly router = inject(Router);
  private readonly zone = inject(NgZone);
  private readonly locationStrategy = inject(LocationStrategy);
  private readonly isBrowser = isPlatformBrowser(inject(PLATFORM_ID));

  constructor() {
    // No guides or surveys during server rendering.
    if (!this.isBrowser) return;

    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.href);
        const appUrl = this.toAppUrl(target);

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

        this.navigate(appUrl);
      });

      // Guide buttons with "Run callback" and the name open_new_project.
      engagement.addCallback('open_new_project', () => this.navigate('/projects/new'));
    });
  }

  // The SDK calls these functions outside the Angular zone.
  private navigate(url: string): void {
    this.zone.run(() => void this.router.navigateByUrl(url));
  }

  // The router URL for a link inside this app, or null for anything else.
  private toAppUrl(target: URL): string | null {
    if (target.origin !== window.location.origin) return null;

    // withHashLocation(): the route is everything after the #.
    if (this.locationStrategy instanceof HashLocationStrategy) {
      return target.hash ? target.hash.slice(1) || '/' : target.pathname + target.search;
    }

    // Drop the <base href> so the router doesn't add it a second time.
    const base = this.locationStrategy.getBaseHref().replace(/\/$/, '');
    let path = target.pathname;
    if (base) {
      if (path !== base && !path.startsWith(`${base}/`)) return null;
      path = path.slice(base.length) || '/';
    }
    return path + target.search + target.hash;
  }
}

// Angular 19 and earlier: src/app/app.component.ts, class AppComponent.
import { EngagementBridgeService } from './engagement-bridge.service';

export class App {
  constructor() {
    inject(AmplitudeIdentityService);
    // Registers guide links and Run callback buttons once, in the browser.
    inject(EngagementBridgeService);
  }
}

// Keep lines other Angular pages added here: experiment()?.clear() and
// refetch() after reset(), and the FlagsService import and inject() field
// (/build/angular-feature-flags).
import { Injectable, signal } from '@angular/core';
import * as amplitude from '@amplitude/unified';
import { getEngagement } from './engagement';

export interface User {
  id: string;
  plan?: string;
}

// Stand-in for your auth. Replace the bodies with your own logic.
@Injectable({ providedIn: 'root' })
export class AuthService {
  readonly user = signal<User | null>(null);

  signIn(user: User): void {
    // ... your sign-in logic
    this.user.set(user);
  }

  async signOut(): Promise<void> {
    // ... your sign-out logic
    this.user.set(null);
    getEngagement()?.gs.closeAll(); // close anything still on screen
    // Clears the user ID and issues a new device ID for the next person.
    amplitude.reset();
  }
}

// Keep lines other Angular pages added here: data-exp attributes
// (/build/angular-web-experiment).
import { RouterLink } from '@angular/router';

@Component({
  // Add RouterLink to the component's imports.
  imports: [RouterLink],
  template: `
    <!-- Add to your existing template. -->
    <a routerLink="/projects/new" data-guide="new-project-button">New project</a>
  `,
})
export class Home {}

import { Component } from '@angular/core';
import { getEngagement } from './engagement';

@Component({
  selector: 'app-feedback-button',
  template: `<button type="button" (click)="openFeedback()">Give feedback</button>`,
})
export class FeedbackButton {
  protected openFeedback(): void {
    getEngagement()?.gs.show('product-feedback');
  }
}

// Angular 19 and earlier: src/app/app.component.ts, class AppComponent.
// Keep lines other Angular pages added here: nav links (/build/angular-session-replay,
// /build/angular-heatmaps), ServerFlagsService (/build/angular-feature-flags).
import { EngagementBridgeService } from './engagement-bridge.service';
import { FeedbackButton } from './feedback-button';

@Component({
  // Add FeedbackButton to your existing imports array.
  imports: [RouterOutlet, RouterLink, FeedbackButton],
  template: `
    <nav>
      <!-- Keep your existing links and sign-in buttons; add: -->
      <app-feedback-button />
    </nav>
    <router-outlet />
  `,
})
export class App {
  constructor() {
    inject(AmplitudeIdentityService);
    // Registers guide links and Run callback buttons once, in the browser.
    inject(EngagementBridgeService);
  }
}

// -- src/app/amplitude-ready.ts --
// 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): void {
  if (!init) {
    markReady(false);
    return;
  }
  init.then(
    () => markReady(true),
    (error: unknown) => {
      console.warn('[amplitude] initAll failed', error);
      markReady(false);
    },
  );
}

// -- src/app/engagement.ts --
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 (typeof window === 'undefined') return undefined;
  return (window as unknown as { engagement?: Engagement }).engagement;
}

// -- src/app/amplitude.ts --
// Keep lines other Angular pages added here: debugMode and privacyConfig
// (/build/angular-session-replay), pageViews: { trackHistoryChanges: 'pathOnly' }
// (/build/angular-web-analytics), the experiment block and deviceId handoff
// (/build/angular-feature-flags), and the webExperiment.plugin() registration
// (/build/angular-web-experiment).
import * as amplitude from '@amplitude/unified';
import { environment } from '../environments/environment';
import { setAmplitudeReady } from './amplitude-ready';

export function initAmplitude(): void {
  if (!environment.amplitudeApiKey) {
    console.warn('amplitudeApiKey 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(environment.amplitudeApiKey, {
      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: environment.production ? 0.01 : 1,
        debugMode: !environment.production,
        // From /build/angular-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/app/engagement-bridge.service.ts --
import { Injectable, NgZone, PLATFORM_ID, inject } from '@angular/core';
import { HashLocationStrategy, LocationStrategy, isPlatformBrowser } from '@angular/common';
import { Router } from '@angular/router';
import { amplitudeReady } from './amplitude-ready';
import { getEngagement } from './engagement';

@Injectable({ providedIn: 'root' })
export class EngagementBridgeService {
  private readonly router = inject(Router);
  private readonly zone = inject(NgZone);
  private readonly locationStrategy = inject(LocationStrategy);
  private readonly isBrowser = isPlatformBrowser(inject(PLATFORM_ID));

  constructor() {
    if (!this.isBrowser) return;

    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.href);
        const appUrl = this.toAppUrl(target);

        if (appUrl === null) {
          window.location.assign(target.href);
          return;
        }

        this.navigate(appUrl);
      });

      engagement.addCallback('open_new_project', () => this.navigate('/projects/new'));
    });
  }

  private navigate(url: string): void {
    this.zone.run(() => void this.router.navigateByUrl(url));
  }

  private toAppUrl(target: URL): string | null {
    if (target.origin !== window.location.origin) return null;

    if (this.locationStrategy instanceof HashLocationStrategy) {
      return target.hash ? target.hash.slice(1) || '/' : target.pathname + target.search;
    }

    const base = this.locationStrategy.getBaseHref().replace(/\/$/, '');
    let path = target.pathname;
    if (base) {
      if (path !== base && !path.startsWith(`${base}/`)) return null;
      path = path.slice(base.length) || '/';
    }
    return path + target.search + target.hash;
  }
}

// -- src/app/auth.service.ts --
// Keep lines other Angular pages added here: experiment()?.clear() and
// refetch() after reset(), and the FlagsService import and inject() field
// (/build/angular-feature-flags).
import { Injectable, signal } from '@angular/core';
import * as amplitude from '@amplitude/unified';
import { getEngagement } from './engagement';

export interface User {
  id: string;
  plan?: string;
}

@Injectable({ providedIn: 'root' })
export class AuthService {
  readonly user = signal<User | null>(null);

  signIn(user: User): void {
    // ... your sign-in logic
    this.user.set(user);
  }

  async signOut(): Promise<void> {
    // ... your sign-out logic
    this.user.set(null);
    getEngagement()?.gs.closeAll();
    amplitude.reset();
  }
}

// -- src/app/feedback-button.ts --
import { Component } from '@angular/core';
import { getEngagement } from './engagement';

@Component({
  selector: 'app-feedback-button',
  template: `<button type="button" (click)="openFeedback()">Give feedback</button>`,
})
export class FeedbackButton {
  protected openFeedback(): void {
    getEngagement()?.gs.show('product-feedback');
  }
}

// -- src/app/app.ts (add to your root component) --
// Angular 19 and earlier: src/app/app.component.ts, class AppComponent.
// Keep lines other Angular pages added here: nav links (/build/angular-session-replay,
// /build/angular-heatmaps), ServerFlagsService (/build/angular-feature-flags).
import { EngagementBridgeService } from './engagement-bridge.service';
import { FeedbackButton } from './feedback-button';

@Component({
  // Add FeedbackButton to your existing imports array.
  imports: [RouterOutlet, RouterLink, FeedbackButton],
  template: `
    <nav>
      <!-- Keep your existing links and sign-in buttons; add: -->
      <app-feedback-button />
    </nav>
    <router-outlet />
  `,
})
export class App {
  constructor() {
    inject(AmplitudeIdentityService);
    // Registers guide links and Run callback buttons once, in the browser.
    inject(EngagementBridgeService);
  }
}

// -- src/app/home.ts (add to your Home component) --
// Keep lines other Angular pages added here: data-exp attributes
// (/build/angular-web-experiment).
import { RouterLink } from '@angular/router';

@Component({
  // Add RouterLink to the component's imports.
  imports: [RouterLink],
  template: `
    <!-- Add to your existing template. -->
    <a routerLink="/projects/new" data-guide="new-project-button">New project</a>
  `,
})
export class Home {}

// Unchanged from earlier pages; keep your versions: src/environments/environment.ts, src/environments/environment.development.ts, src/main.ts, src/app/amplitude-identity.service.ts, src/app/projects/new-project.ts, src/app/app.routes.ts.

First complete https://amplitude.com/build/angular-product-analytics, or
confirm this Angular app already has its setup: @amplitude/unified,
amplitudeApiKey and production in both environment files, initAmplitude()
in src/app/amplitude.ts called from src/main.ts before
bootstrapApplication, AuthService exposing the user as a signal,
AmplitudeIdentityService injected in the root component's constructor,
and the Home and NewProject routes. Use the root component file the app
already has (app.ts or app.component.ts); never create a second one.

Then add Amplitude guides and surveys by following
https://amplitude.com/build/angular-guides-surveys exactly. Other Amplitude
Build pages for Angular add lines to the same files this page touches.
Merge into existing files and never delete lines another Amplitude Build
page added. Don't change the environment files, new-project.ts,
app.routes.ts or AmplitudeIdentityService.

Keep the single initAll call in src/app/amplitude.ts and everything
already there: sessionReplay.debugMode and privacyConfig, pageViews:
{ trackHistoryChanges: 'pathOnly' }, the experiment block and any
analytics.deviceId handoff, and the webExperiment.plugin() registration
after initAll. If src/app/amplitude-ready.ts exists, keep it and its
setAmplitudeReady(...) wrapper; otherwise create it from the page and
pass the initAll promise directly to setAmplitudeReady(), with no
Promise.resolve wrapper (setAmplitudeReady(null) when the key is
missing), without returning it from initAmplitude(). Never call
engagement.init() or engagement.boot(), and never initialize in a
component, service, provideAppInitializer, or main.server.ts. Read
window.engagement only through getEngagement() in src/app/engagement.ts,
which returns undefined on the server; don't augment the global Window
type.

Add src/app/engagement-bridge.service.ts as on the page: return early
when not in the browser, wait for amplitudeReady and return if it
resolves false, warn if window.engagement is missing, call setRouter with
a function that turns the URL into an in-app path (same origin, base href
stripped, hash route for HashLocationStrategy, falling back to the path
when the URL has no hash) and navigates with router.navigateByUrl inside
NgZone.run, and register addCallback('open_new_project', ...) that
navigates to /projects/new the same way. Inject it in the root
component's constructor after AmplitudeIdentityService. Add
src/app/feedback-button.ts that calls
getEngagement()?.gs.show('product-feedback') on click, and add
<app-feedback-button /> to the existing root template, keeping its nav
links and any other inject(...) lines. In src/app/home.ts, add
data-guide="new-project-button" to an existing link to /projects/new (the
Web Experiment page's Create a project link, for example), or add a New
project link with that attribute if there's none; keep any data-exp
attributes. In the sign-out method, call getEngagement()?.gs.closeAll()
before amplitude.reset(), keep any existing lines there (including the
feature flags page's FlagsService clear() and refetch() after reset()),
and call reset() only after a successful sign-out, never when the user
is null.

If a CSP blocks inline styles, tell me rather than inventing a nonce
workaround. If the app sends Cross-Origin-Opener-Policy, set it to
same-origin-allow-popups, or unsafe-none if the app also runs Web
Experiment. Tell me session replay records every session under ng serve
and about 1% in production, and how to turn it off. Report every file
you changed.