Guides and Surveys SDK

Amplitude's Guides and Surveys SDK enables you to deploy Guides and Surveys on your website or application.

Install the SDK

Guides and Surveys supports different installation options to work best with your existing Amplitude implementation, if you have one.

Amplitude Browser SDK

Install the Guides and Surveys SDK with a script, or as a package with npm or Yarn.

Place the script tag below your Amplitude script tag.

1<script src="https://cdn.amplitude.com/script/API_KEY.engagement.js"></script>
2<script>amplitude.add(window.engagement.plugin())</script>

1npm install @amplitude/engagement-browser

Import Guides and Surveys into your project:

1import { plugin as engagementPlugin } from '@amplitude/engagement-browser';
2amplitude.add(engagementPlugin());

1yarn add @amplitude/engagement-browser

Import Guides and Surveys into your project:

1import { plugin as engagementPlugin } from '@amplitude/engagement-browser';
2amplitude.add(engagementPlugin());

Third-party analytics provider

Using the Guides and Surveys standalone SDK with another analytics provider requires extra configuration to help map properties to Amplitude.

Usign NPM or Yarn

Calling init is only required when loading Guides and Surveys using NPM or Yarn. If you're using the script installation, skip straight to calling boot.

1engagement.init(apiKey: string, options: { serverZone: "US" | "EU" }): void

Parameter	Type	Description
`apiKey`	`string`	Required. API key of the Amplitude project you want to use.
`initOptions.serverZone`	`EU` or `US`	Optional. Sets the Amplitude server zone. Set this to EU for Amplitude projects created in EU data center. Default: `US`
`initOptions.logger`	Logger interface	Optional. Sets a custom logging provider class. Default: Amplitude Logger
`initOptions.logLevel`	`LogLevel.None` or `LogLevel.Error` or `LogLevel.Warn` or `LogLevel.Verbose` or `LogLevel.Debug`.	Optional. Sets the log level. Default: `LogLevel.Warn`

After calling this function, you can access window.engagement and call the SDK functions. However, Guides and Surveys isn't fully functional until you call boot.

This initialization code accepts parameters that define the user and any integrations.

1engagement.boot(options: BootOptions): Promise<void>

Parameter	Type	Description
`options.user`	`EndUser` or `(() => EndUser)`	Required. User information or a function that returns user information.
`options.integrations`	`Array<Integration>`	Optional. An array of integrations for tracking events.

 1await window.engagement.boot({
 2  user: {
 3    // Guides and Surveys requires either user_id or device_id for user identification
 4    user_id: 'USER_ID', 
 5    device_id: 'DEVICE_ID',
 6    user_properties: {},
 7  },
 8  integrations: [
 9    {
10      track: (event) => {
11        analytics.track(event.event_type, event.event_properties)
12      }
13    },
14  ],
15});

Initialize with Segment analytics

Initializing the SDK and launching a guide or survey with third-party analytics requires a few more steps.

First, the initialization code requires you to map the user_id and device_id fields, and optionally configure event forwarding to enable event-based triggers.

Make sure you've added the Engagement script tag to your site before continuing.

 1analytics.ready(() => {
 2  await window.engagement.boot({
 3    user: {
 4      // User Provider: Guides and Surveys requires either user_id or device_id for user identification
 5      user_id: analytics.user().id(),
 6      device_id: analytics.user().anonymousId(),
 7      user_properties: {},
 8    },
 9    integrations: [
10      {
11        // Tracking Provider: Pass Guides and Surveys events to the 3rd party analytics provier
12        track: (event) => {
13          analytics.track(event.event_type, event.event_properties)
14        }
15      },
16    ],
17  });
18 
19  // (Optional) Forward events from segment to do event-based triggers for Guides and Surveys. These events aren't sent to the server
20  analytics.on('track', (event, properties, options) => {
21    window.engagement.forwardEvent({ event_type: event, event_properties: properties});
22  });
23 
24  analytics.on('page', (event, properties, options) => {
25    window.engagement.forwardEvent({ event_type: event, event_properties: properties});
26  });
27});

Import the Guides and Surveys package

1npm install @amplitude/engagement-browser

Connect Guides and Surveys with Segment:

 1import { init as engagementInit } from '@amplitude/engagement-browser';
 2 
 3engagementInit("API_KEY", { serverZone: "US" });
 4 
 5analytics.ready(() => {
 6  await window.engagement.boot({
 7    user: {
 8      // User Provider: Guides and Surveys requires either user_id or device_id for user identification
 9      user_id: analytics.user().id(),
10      device_id: analytics.user().anonymousId(),
11      user_properties: {},
12    },
13    integrations: [
14      {
15        // Tracking Provider: Pass Guides and Surveys events to the 3rd party analytics provier
16        track: (event) => {
17          analytics.track(event.event_type, event.event_properties)
18        }
19      },
20    ],
21  });
22 
23  // (Optional) Forward events from segment to do event-based triggers for Guides and Surveys. These events aren't sent to the server
24  analytics.on('track', (event, properties, options) => {
25    window.engagement.forwardEvent({ event_type: event, event_properties: properties});
26  });
27 
28  analytics.on('page', (event, properties, options) => {
29    window.engagement.forwardEvent({ event_type: event, event_properties: properties});
30  });
31});

Import the Guides and Surveys package

1yarn add @amplitude/engagement-browser

Connect Guides and Surveys with Segment:

 1import { init as engagementInit } from '@amplitude/engagement-browser';
 2 
 3engagementInit("API_KEY", { serverZone: "US" });
 4 
 5analytics.ready(() => {
 6  await window.engagement.boot({
 7    user: {
 8      // User Provider: Guides and Surveys requires either user_id or device_id for user identification
 9      user_id: analytics.user().id(),
10      device_id: analytics.user().anonymousId(),
11      user_properties: {},
12    },
13    integrations: [
14      {
15        // Tracking Provider: Pass Guides and Surveys events to the 3rd party analytics provier
16        track: (event) => {
17          analytics.track(event.event_type, event.event_properties)
18        }
19      },
20    ],
21  });
22 
23  // (Optional) Forward events from segment to do event-based triggers for Guides and Surveys. These events aren't sent to the server
24  analytics.on('track', (event, properties, options) => {
25    window.engagement.forwardEvent({ event_type: event, event_properties: properties});
26  });
27 
28  analytics.on('page', (event, properties, options) => {
29    window.engagement.forwardEvent({ event_type: event, event_properties: properties});
30  });
31});

Verify installation and initialization

To verify that the Guides and Surveys SDK is running on your site or dev environment, open your browser's Developer Tools, and enter the following in the console:

1window.engagement

If the response is undefined, Guides and Surveys isn't installed properly.

Content Security Policy (CSP)

If your organization has a strict Content Security Policy (CSP), Guides and Surveys requires some additions to ensure smooth operation.

When you use the Amplitude Browser SDK 2 for analytics, add the following items to your CSP:

1script-src: https://*.amplitude.com;
2connect-src: https://*.amplitude.com;

Regardless of the analytics provider you use, Guides and Surveys requires the following additions:

1img-src: https://*.amplitude.com;
2media-src: https://*.amplitude.com;
3style-src: https://*.amplitude.com;

Manage themes

Configure the visual theme that displays to the user.

1engagement.setThemeMode(mode: ThemeMode): void

Parameter	Type	Description
`mode`	`light_mode`, `dark_mode`, `auto`	Required. Select the theme to apply.

1// Automatically detect user's system preferences
2window.engagement.setThemeMode("auto");
3 
4// Set dark mode explicitly
5window.engagement.setThemeMode("dark_mode");
6 
7// Set light mode explicitly
8window.engagement.setThemeMode("light_mode");

Router configuration

Configure how Guides and Surveys handles URLs in a single page application (SPA).

1engagement.setRouter(routerFn: (url: string) => void): void

Parameter	Type	Description
`routerRn`	`(url: string) => void`	Required. A function that handles changes to the URL.

 1// React Router v6 implementation
 2import { useNavigate } from "react-router-dom";
 3 
 4const MyComponent = () => {
 5  const navigate = useNavigate();
 6 
 7  React.useEffect(() => {
 8    window.engagement.setRouter((newUrl) => navigate(newUrl));
 9  }, []);
10};

Reset

Reset a guide or survey to a specific step.

1engagement.gs.reset(key: string, stepIndex?: number)

Parameter	Type	Description
`key`	`string`	Required. The guide or survey's key.
`stepIndex`	`number`	Required. The zero-based index of the step to reset to. Defaults to the initial step.

List

Retrieve a list of visible guides or surveys

1engagement.gs.list(): Array<GuideOrSurvey>

1interface GuideOrSuvey {
2  id: number;
3  status: "visible" | "active";
4  step: number;
5  title: string
6}

Show

Display a specific guide or survey.

1engagement.gs.show(key: string, stepIndex?: number): void

Parameter	Type	Description
`key`	`string`	Required. The guide or survey's key.
`stepIndex`	`number`	The zero-based index of the step to show. Defaults to the initial step if not provided.

Forward event

Trigger Guides and Surveys programmatically.

1engagement.forwardEvent(event: Event): void

Parameter	Type	Description
`event`	Event	Required. An event object that launches a guide or survey.

Close all

Close all active guides and surveys.

1engagement.gs.closeAll(): void