Amplitude's Guides and Surveys SDK enables you to deploy Guides and Surveys on your website or application.
Guides and Surveys supports different installation options to work best with your existing Amplitude implementation, if you have one.
Install the Guides and Surveys SDK with a script, or as a package with npm or Yarn.
<script src="https://cdn.amplitude.com/script/API_KEY.engagement.js"></script><script>amplitude.add(window.engagement.plugin())</script>
npm install @amplitude/engagement-browser
Import Guides and Surveys into your project:
import { plugin as engagementPlugin } from '@amplitude/engagement-browser';amplitude.add(engagementPlugin());
yarn add @amplitude/engagement-browser
Import Guides and Surveys into your project:
import { plugin as engagementPlugin } from '@amplitude/engagement-browser';amplitude.add(engagementPlugin());
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
.
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
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
.
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. This method should be called only once for a given session unless you want to change the active user.
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) } }, ],});
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});});
First, the initialization code requires you to map the
Connect Guides and Surveys with Segment:
Connect Guides and Surveys with Segment:
Initialize with Segment analytics
user_id
and device_id
fields, and optionally configure event forwarding to enable event-based triggers.
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
If the response is undefined
, Guides and Surveys isn't installed properly.
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;
Configure the visual theme mode if your app supports light and dark modes.
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 preferenceswindow.engagement.setThemeMode("auto"); // Set dark mode explicitlywindow.engagement.setThemeMode("dark_mode"); // Set light mode explicitlywindow.engagement.setThemeMode("light_mode");
Configure how Guides and Surveys handles URLs in a single page application (SPA).
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 implementationimport { useNavigate } from "react-router-dom"; const MyComponent = () => { const navigate = useNavigate(); React.useEffect(() => { window.engagement.setRouter((newUrl) => navigate(newUrl)); }, []);};
Reset a guide or survey to a specific step.
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. |
Retrieve a list of all live guides and surveys along with their status.
engagement.gs.list(): Array<GuideOrSurvey>
interface GuideOrSuvey { id: number; status: "visible" | "active"; step: number; title: string}
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
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 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
Parameter | Type | Description |
---|---|---|
event |
Event | Required. An event object. It triggers a guide or survey if its event_type matches. |
Close all active guides and surveys.
engagement.gs.closeAll(): void
Thanks for your feedback!
February 7th, 2025
Need help? Contact Support
Visit Amplitude.com
Have a look at the Amplitude Blog
Learn more at Amplitude Academy
© 2025 Amplitude, Inc. All rights reserved. Amplitude is a registered trademark of Amplitude, Inc.