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.

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

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

npm install @amplitude/engagement-browser

npm install @amplitude/engagement-browser

Import Guides and Surveys into your project:

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

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

yarn add @amplitude/engagement-browser

yarn add @amplitude/engagement-browser

Import Guides and Surveys into your project:

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

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

Third-party analytics provider

If you don't use the Amplitude Analytics Browser SDK 2, you can still use Guides and Surveys but you need to configure the SDK to work with your third-party analytics provider. First, add the SDK to your project using the script tag, or through npm or Yarn as outlined above.
But, instead of calling amplitude.add(window.engagement.plugin()), you need to call init and boot.

Initialize the SDK

Call init to fully initialize the bundle and register engagement on the global window object.

engagement.init(apiKey: string, options: { serverZone: "US" | "EU", logger: Logger, logLevel: LogLevel }): void

engagement.init(apiKey: string, options: { serverZone: "US" | "EU", logger: Logger, logLevel: LogLevel }): 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.

Boot user

The final step before guides and surveys can show to your end-users is to call boot. This method triggers targeting resolution of your live guides and surveys. It also establishes the connection from the Guides and Surveys SDK to your third-party analytics provider. Call this method only once for a given session unless you want to change the active user.

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

engagement.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. Enables sending Guides and Surveys events to your third-party Analytics provider.

await window.engagement.boot({
  user: {
    // Guides and Surveys requires at least one of user_id or device_id for user identification
    user_id: 'USER_ID', 
    device_id: 'DEVICE_ID',
    user_properties: {},
  },
  integrations: [
    {
      track: (event) => {
        analytics.track(event.event_type, event.event_properties)
      }
    },
  ],
});

await window.engagement.boot({
  user: {
    // Guides and Surveys requires at least one of user_id or device_id for user identification
    user_id: 'USER_ID',
    device_id: 'DEVICE_ID',
    user_properties: {},
  },
  integrations: [
    {
      track: (event) => {
        analytics.track(event.event_type, event.event_properties)
      }
    },
  ],
});

To use On event tracked triggers, forward events from your third-party analytics provider to Guides and Surveys. The Guides and Surveys SDK doesn't send these events to the server.

analytics.on('track', (event, properties, options) => { // Example for Segment Analytics
  window.engagement.forwardEvent({ event_type: event, event_properties: properties});
});

analytics.on('track', (event, properties, options) => { // Example for Segment Analytics
  window.engagement.forwardEvent({ event_type: event, event_properties: properties});
});

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.

window.engagement.init("API_KEY", { serverZone: "US" });
 
analytics.ready(() => {
  await window.engagement.boot({
    user: {
      // User Provider: Guides and Surveys requires either user_id or device_id for user identification
      user_id: analytics.user().id(),
      device_id: analytics.user().anonymousId(),
      user_properties: {},
    },
    integrations: [
      {
        // Tracking Provider: Pass Guides and Surveys events to the 3rd party analytics provier
        track: (event) => {
          analytics.track(event.event_type, event.event_properties)
        }
      },
    ],
  });
 
  // (Optional) Forward events from segment to do event-based triggers for Guides and Surveys. These events aren't sent to the server
  analytics.on('track', (event, properties, options) => {
    window.engagement.forwardEvent({ event_type: event, event_properties: properties});
  });
 
  analytics.on('page', (event, properties, options) => {
    window.engagement.forwardEvent({ event_type: event, event_properties: properties});
  });
});

window.engagement.init("API_KEY", { serverZone: "US" });
analytics.ready(() => {
await window.engagement.boot({
user: {
// User Provider: Guides and Surveys requires either user_id or device_id for user identification
user_id: analytics.user().id(),
device_id: analytics.user().anonymousId(),
user_properties: {},
},
integrations: [
{
// Tracking Provider: Pass Guides and Surveys events to the 3rd party analytics provier
track: (event) => {
analytics.track(event.event_type, event.event_properties)
}
},
],
});
// (Optional) Forward events from segment to do event-based triggers for Guides and Surveys. These events aren't sent to the server
analytics.on('track', (event, properties, options) => {
window.engagement.forwardEvent({ event_type: event, event_properties: properties});
});
analytics.on('page', (event, properties, options) => {
window.engagement.forwardEvent({ event_type: event, event_properties: properties});
});
});

Import the Guides and Surveys package

npm install @amplitude/engagement-browser

npm install @amplitude/engagement-browser

Connect Guides and Surveys with Segment:

import { init as engagementInit } from '@amplitude/engagement-browser';
 
engagementInit("API_KEY", { serverZone: "US" });
 
analytics.ready(() => {
  await window.engagement.boot({
    user: {
      // User Provider: Guides and Surveys requires either user_id or device_id for user identification
      user_id: analytics.user().id(),
      device_id: analytics.user().anonymousId(),
      user_properties: {},
    },
    integrations: [
      {
        // Tracking Provider: Pass Guides and Surveys events to the 3rd party analytics provier
        track: (event) => {
          analytics.track(event.event_type, event.event_properties)
        }
      },
    ],
  });
 
  // (Optional) Forward events from segment to do event-based triggers for Guides and Surveys. These events aren't sent to the server
  analytics.on('track', (event, properties, options) => {
    window.engagement.forwardEvent({ event_type: event, event_properties: properties});
  });
 
  analytics.on('page', (event, properties, options) => {
    window.engagement.forwardEvent({ event_type: event, event_properties: properties});
  });
});

import { init as engagementInit } from '@amplitude/engagement-browser';
engagementInit("API_KEY", { serverZone: "US" });
analytics.ready(() => {
await window.engagement.boot({
user: {
// User Provider: Guides and Surveys requires either user_id or device_id for user identification
user_id: analytics.user().id(),
device_id: analytics.user().anonymousId(),
user_properties: {},
},
integrations: [
{
// Tracking Provider: Pass Guides and Surveys events to the 3rd party analytics provier
track: (event) => {
analytics.track(event.event_type, event.event_properties)
}
},
],
});
// (Optional) Forward events from segment to do event-based triggers for Guides and Surveys. These events aren't sent to the server
analytics.on('track', (event, properties, options) => {
window.engagement.forwardEvent({ event_type: event, event_properties: properties});
});
analytics.on('page', (event, properties, options) => {
window.engagement.forwardEvent({ event_type: event, event_properties: properties});
});
});

Import the Guides and Surveys package

yarn add @amplitude/engagement-browser

yarn add @amplitude/engagement-browser

Connect Guides and Surveys with Segment:

import { init as engagementInit } from '@amplitude/engagement-browser';
 
engagementInit("API_KEY", { serverZone: "US" });
 
analytics.ready(() => {
  await window.engagement.boot({
    user: {
      // User Provider: Guides and Surveys requires either user_id or device_id for user identification
      user_id: analytics.user().id(),
      device_id: analytics.user().anonymousId(),
      user_properties: {},
    },
    integrations: [
      {
        // Tracking Provider: Pass Guides and Surveys events to the 3rd party analytics provier
        track: (event) => {
          analytics.track(event.event_type, event.event_properties)
        }
      },
    ],
  });
 
  // (Optional) Forward events from segment to do event-based triggers for Guides and Surveys. These events aren't sent to the server
  analytics.on('track', (event, properties, options) => {
    window.engagement.forwardEvent({ event_type: event, event_properties: properties});
  });
 
  analytics.on('page', (event, properties, options) => {
    window.engagement.forwardEvent({ event_type: event, event_properties: properties});
  });
});

import { init as engagementInit } from '@amplitude/engagement-browser';
engagementInit("API_KEY", { serverZone: "US" });
analytics.ready(() => {
await window.engagement.boot({
user: {
// User Provider: Guides and Surveys requires either user_id or device_id for user identification
user_id: analytics.user().id(),
device_id: analytics.user().anonymousId(),
user_properties: {},
},
integrations: [
{
// Tracking Provider: Pass Guides and Surveys events to the 3rd party analytics provier
track: (event) => {
analytics.track(event.event_type, event.event_properties)
}
},
],
});
// (Optional) Forward events from segment to do event-based triggers for Guides and Surveys. These events aren't sent to the server
analytics.on('track', (event, properties, options) => {
window.engagement.forwardEvent({ event_type: event, event_properties: properties});
});
analytics.on('page', (event, properties, options) => {
window.engagement.forwardEvent({ event_type: event, event_properties: properties});
});
});

Google Tag Manager

If you haven't already, update to the latest version of the Amplitude template. Find the update icon on the Templates page in GTM.

Next, on the Tags page, enable Guides and Surveys.

Info

The Amplitude template doesn't enable Guides and Surveys by default. This prevents organizations who enable automatic template updates from enabling Guides and Surveys accidentally.

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:

window.engagement

window.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. Add the following CSP directives to your policy:

script-src: https://*.amplitude.com;
connect-src: https://*.amplitude.com;
img-src: https://*.amplitude.com;
media-src: https://*.amplitude.com;
style-src: https://*.amplitude.com;

script-src: https://*.amplitude.com;
connect-src: https://*.amplitude.com;
img-src: https://*.amplitude.com;
media-src: https://*.amplitude.com;
style-src: https://*.amplitude.com;

Manage themes

Configure the visual theme mode if your app supports light and dark modes.

engagement.setThemeMode(mode: ThemeMode): void

engagement.setThemeMode(mode: ThemeMode): void

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

// Automatically detect user's system preferences
window.engagement.setThemeMode("auto");
 
// Set dark mode explicitly
window.engagement.setThemeMode("dark_mode");
 
// Set light mode explicitly
window.engagement.setThemeMode("light_mode");

// Automatically detect user's system preferences
window.engagement.setThemeMode("auto");
// Set dark mode explicitly
window.engagement.setThemeMode("dark_mode");
// Set light mode explicitly
window.engagement.setThemeMode("light_mode");

Router configuration

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

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

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

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

// React Router v6 implementation
import { useNavigate } from "react-router-dom";
 
const MyComponent = () => {
  const navigate = useNavigate();
 
  React.useEffect(() => {
    window.engagement.setRouter((newUrl) => navigate(newUrl));
  }, []);
};

// React Router v6 implementation
import { useNavigate } from "react-router-dom";
const MyComponent = () => {
const navigate = useNavigate();
React.useEffect(() => {
window.engagement.setRouter((newUrl) => navigate(newUrl));
}, []);
};

Reset

Reset a guide or survey to a specific step.

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

engagement.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 all live guides and surveys along with their status.

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

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

interface GuideOrSuvey {
  id: number;
  status: "visible" | "active";
  step: number;
  title: string
}

interface GuideOrSuvey {
  id: number;
  status: "visible" | "active";
  step: number;
  title: string
}

Show

Display a specific guide or survey. This ignores any targeting rules and limits except for page targeting.

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

engagement.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

Forward third-party Analytics events to the Guides and Surveys SDK to trigger guides and surveys that use the *On event tracked* trigger.

engagement.forwardEvent(event: Event): void

engagement.forwardEvent(event: Event): void

Parameter	Type	Description
`event`	Event	Required. An event object. It triggers a guide or survey if its `event_type` matches.

Close all

Close all active guides and surveys.

engagement.gs.closeAll(): void

engagement.gs.closeAll(): void

Troubleshoot your installation

If your Guides and Surveys instrumentation doesn't work, verify the following topics.

Verify Guides and Surveys is installed

Open your browser's developer console, and enter window.engagement. If the return is undefined, Guides and Surveys installation wasn't successful.
If window.engagement returns a valid response, enter window.engagement._.user. A return of undefined indicates an issue with the plugin configuration.
For additional debugging, enter window.engagement._debugStatus(). The output should look like:

{
    "user": {
        "user_id": "test-base-user-1vxxkg",
        "device_id": "62c5e45a-94ab-4090-b053-3f28e848763f",
        "user_properties": {
            "foo": "bar"
        }
    },
    "apiKey": "6ae8d3d7d48eadfb0b2489db692e14c9",
    "stateInitialized": true,
    "decideSuccessful": true,
    "num_guides_surveys": 2,
    "analyticsIntegrations": 1
}

{
    "user": {
        "user_id": "test-base-user-1vxxkg",
        "device_id": "62c5e45a-94ab-4090-b053-3f28e848763f",
        "user_properties": {
            "foo": "bar"
        }
    },
    "apiKey": "6ae8d3d7d48eadfb0b2489db692e14c9",
    "stateInitialized": true,
    "decideSuccessful": true,
    "num_guides_surveys": 2,
    "analyticsIntegrations": 1
}

Verify that:

the user object is present
apiKey is set
stateInitialized is true
decideSuccessful is true
num_guides_surveys is a non-zero integer if a guide or survey should be display on the page.

Verify plugin configuration

If you use Amplitude Browser SDK 2.0, check the browser's console for errors. If there are none, verify that your code matches code provided in the installation instructions. In particular, ensure that amplitude.add(window.engagement.plugin()) is present in the code.

If you see something like amplitude is not defined and cannot read properties of undefined .add(), this means that the G&S is trying to load before the Amplitude SDK loads. Check your code to ensure that the Amplitude Browser SDK loads before the Guides and Surveys SDK.

If you use Google Tag Manager, ensure you update to the latest Amplitude template.

Guides and Surveys requires Browser SDK 2 and doesn't support the legacy Amplitude JavaScript SDK.

Common root causes

This section contains some common errors that may prevent running Guides and Surveys.

`boot` is called more than once

This results in unexpected behavior, especially for guides and surveys that should appear immediately.

Info

If you implement Guides and Surveys with amplitude.add(window.engagement.plugin()), don't call boot. The add() method includes this call with a very specific set of parameters.

Wrong project used

Ensure the API key you provide:

is the same key you use to initialize the Browser SDK
belongs to the project that contains the Guides and Surveys configuration

Guides and Surveys SDK

Install the SDK

Amplitude Browser SDK

Third-party analytics provider

Initialize the SDK

Boot user

Google Tag Manager

Info

Verify installation and initialization

Content Security Policy (CSP)

Manage themes

Router configuration

Reset

List

Show

Forward event

Close all

Troubleshoot your installation

Verify Guides and Surveys is installed

Verify plugin configuration

Common root causes

boot is called more than once

Info

Wrong project used

`boot` is called more than once