# Amplitude Documentation — Guides and Surveys
# Generated: 2026-09-07T09:58:23Z
# Pages included: 37 of 37
# Source: https://amplitude.com/docs/llms.txt
# Product feed: llms-guides-surveys.txt
> In-product guides, surveys, targeting, and Guides and Surveys SDKs.
> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.
================================================================================
# Guides and Surveys
URL: https://amplitude.com/docs/guides-and-surveys
================================================================================
# Guides and Surveys
Build in-product guides and surveys to drive feature adoption and gather feedback in context. Amplitude Guides and Surveys helps users learn your product and shares signals back to the teams who shape it.
**Outcome:** [Help users get to value faster](https://amplitude.com/docs/guides-and-surveys/guides)
Add tooltips, modals, and walkthroughs so users discover features and finish onboarding without a support ticket.
**Outcome:** [Ask users while it's fresh](https://amplitude.com/docs/guides-and-surveys/survey-overview)
Capture sentiment, intent, and unmet needs in the moment, not in a post-hoc email survey.
**Outcome:** [Make every message feel native](https://amplitude.com/docs/guides-and-surveys/themes)
Style guides and surveys with reusable themes so they look like your product, not a third-party widget.
**Outcome:** [Reach the user who needs it](https://amplitude.com/docs/guides-and-surveys/setup-and-target)
Trigger on behavior, properties, and cohorts so each user sees the message that fits where they are.
**Outcome:** [Speak every user's language](https://amplitude.com/docs/guides-and-surveys/localization)
Localize guides and surveys from one source so international users get the same experience.
**Outcome:** [Prove guides moved the needle](https://amplitude.com/docs/guides-and-surveys/analyze-a-survey)
Tie guide and survey interactions back to product metrics so you know which messages actually changed behavior.
## Design in-product experiences
Create guides and surveys that match your product, ask timely questions, and help users complete important workflows.
- [Create guides](https://amplitude.com/docs/guides-and-surveys/guides) to introduce features, announce changes, and support onboarding.
- [Build surveys](https://amplitude.com/docs/guides-and-surveys/build-a-survey) to collect feedback while users work in your product.
- [Use templates](https://amplitude.com/docs/guides-and-surveys/templates) to start from common guide and survey patterns.
- [Customize themes](https://amplitude.com/docs/guides-and-surveys/themes) so each experience matches your brand.
## Target and measure experiences
Use behavioral data to decide who receives an experience, then measure how users respond.
- [Set up targeting](https://amplitude.com/docs/guides-and-surveys/setup-and-target) to trigger guides and surveys for specific users.
- [Personalize content with variables](https://amplitude.com/docs/guides-and-surveys/personalize-with-variables) to tailor messages with user and account properties.
- [Localize guides and surveys](https://amplitude.com/docs/guides-and-surveys/localization) to support users across languages.
- [Analyze survey results](https://amplitude.com/docs/guides-and-surveys/analyze-a-survey) to connect responses to product behavior.
### [Engage Your Users with Guides and Surveys](https://academy.amplitude.com/engage-your-users-with-guides-and-surveys)
Learn to deliver targeted, in-product messages that drive adoption, engagement, and retention with Amplitude's Guides and Surveys.
================================================================================
# Guides and Surveys Web SDK
URL: https://amplitude.com/docs/sdks/guides-and-surveys/sdk
Updated: 2025-08-25
================================================================================
# Guides and Surveys Web SDK
- **Package:** `@amplitude/engagement-browser` ([npm](https://www.npmjs.com/package/@amplitude/engagement-browser))
- **Latest version:** 1.0.12
Amplitude's Guides and Surveys SDK enables you to deploy [Guides and Surveys](https://amplitude.com/docs/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.
> **Note:** Shopify installation
>
> If you use the [Amplitude Shopify Plugin](https://amplitude.com/docs/data/amplitude-shopify-plugin), install the Guides and Surveys Web SDK separately. The Shopify plugin includes Amplitude Analytics, Session Replay, and Web Experiment, but doesn't include Guides and Surveys.
### Amplitude Browser SDK 2
If you use the [Amplitude Browser SDK v2](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2), install the Guides and Surveys SDK with a script, or as a package with npm or Yarn.
This approach uses the Amplitude Browser SDK's plugin system, which lets you extend the core Analytics SDK with additional capabilities. Calling `amplitude.add(engagementPlugin())` registers Guides and Surveys as a plugin. Guides and Surveys initializes alongside Analytics, shares the same API key and user identity, and communicates with Analytics directly. You don't need to call `init` or `boot` separately.
Call `amplitude.add(engagementPlugin())` before `amplitude.init()`. This lets the Analytics SDK control the plugin's initialization, so the user identity and session are ready when Guides and Surveys boots.
#### script
Place the script tag below your Amplitude script tag.
```html
```
> **Warning:** Load scripts synchronously
>
> When using script tags to load Analytics and Engagement SDKs, don't set `async = true` on your Amplitude Analytics script tag. The Analytics SDK must load before the Engagement SDK. Loading them asynchronously can cause initialization errors.
#### npm
```bash
npm install @amplitude/engagement-browser
```
Import Guides and Surveys into your project, and add the plugin before you call `amplitude.init()`:
```ts
import * as amplitude from "@amplitude/analytics-browser";
import { plugin as engagementPlugin } from "@amplitude/engagement-browser";
amplitude.add(engagementPlugin());
amplitude.init("API_KEY");
```
#### yarn
```bash
yarn add @amplitude/engagement-browser
```
Import Guides and Surveys into your project, and add the plugin before you call `amplitude.init()`:
```ts
import * as amplitude from "@amplitude/analytics-browser";
import { plugin as engagementPlugin } from "@amplitude/engagement-browser";
amplitude.add(engagementPlugin());
amplitude.init("API_KEY");
```
> **Warning:** Add the plugin before calling init
>
> Adding the plugin while the Analytics SDK is still initializing can cause Guides and Surveys to boot with a missing or incorrect user. Always call `amplitude.add(engagementPlugin())` before `amplitude.init()`, so the Analytics SDK initializes the plugin at the right point in its own startup sequence.
>
> If your setup doesn't allow adding the plugin first, wait for initialization to complete before adding it:
>
> ```ts
> await amplitude.init("API_KEY").promise;
> amplitude.add(engagementPlugin());
> ```
>
> Keep in mind that with this approach, the plugin doesn't receive events tracked before you add it, so guides and surveys with an "On event tracked" trigger don't react to those early events.
For additional configuration, supply `InitOptions` to the `plugin` function. Go to [Initialize the SDK](#initialize-the-sdk) for the available options.
For example, use `autoRefreshIntervalSeconds` to configure auto-refresh at plugin time, since the plugin calls `boot()` automatically:
```ts
import { plugin as engagementPlugin } from "@amplitude/engagement-browser";
amplitude.add(
engagementPlugin({
autoRefreshIntervalSeconds: 3600,
}),
);
```
> **Note:**
>
> After the installation steps are complete, the SDK sends all Guides and Surveys events to your project by default.
> **Warning:** Use the same API key for Guides & Surveys and Analytics
>
> To avoid analytics mismatches and ensure accurate data collection, use the same API key for both Guides & Surveys and your Analytics SDK. Both should reference the same Amplitude project. Using different API keys can cause:
>
> - The SDK to fetch guides and surveys from the wrong project.
> - Analytics data to appear in different projects.
> - Insights and survey responses to be incomplete or mismatched.
>
> Make sure the API key you provide to Guides & Surveys matches the API key used to initialize your Amplitude Analytics SDK.
> **Note:** No need to call init or boot
>
> When using the Amplitude Browser SDK plugin with `amplitude.add(engagementPlugin())`, don't call `engagement.init()` or `engagement.boot()`. The plugin handles initialization automatically.
>
> Only call `init` and `boot` manually if you need to:
>
> - Use a proxy. Refer to [Standalone installation](https://amplitude.com/docs/sdks/guides-and-surveys/sdk#standalone-installation-other-amplitude-sdks-third-party-analytics-providers-and-proxy-setups) and [Proxy configuration](https://amplitude.com/docs/guides-and-surveys/proxy).
> - Customize event handling with the `integrations` option. Refer to [Standalone installation](https://amplitude.com/docs/sdks/guides-and-surveys/sdk#standalone-installation-other-amplitude-sdks-third-party-analytics-providers-and-proxy-setups).
>
> Use this option only with the [Amplitude Analytics Browser SDK 2](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2).
### Amplitude Browser Unified SDK
The [Amplitude Browser Unified SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk) includes Guides and Surveys by default. Provide the engagement options during initialization:
```ts
import { initAll } from "@amplitude/unified";
initAll("YOUR_API_KEY", {
// Other Amplitude SDK options...
engagement: {
// Guides and Surveys options go here...
},
});
```
Enable Guides and Surveys in your Amplitude project settings before guides and surveys can display. Go to [Unified SDK documentation](https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk#guides-and-surveys-options) for details.
### Standalone installation: Other Amplitude SDKs, third-party analytics providers, and proxy setups
Use this standalone installation path if you:
- Use an Amplitude SDK other than [Browser SDK 2](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2) or [Browser Unified SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk).
- Use a third-party analytics provider (like Segment, Heap, or Mixpanel).
- Use [Browser SDK 2](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2) with a proxy server.
> **Warning:** Proxy setups require standalone installation
>
> If you use Browser SDK 2 with a proxy (custom `serverUrl` in your Analytics initialization), don't use the plugin installation path (`amplitude.add(engagementPlugin())`). The plugin doesn't support proxy configuration. Instead, use this standalone installation path with `init` and `boot`, and configure the Guides and Surveys proxy URLs separately. Review [proxy configuration](https://amplitude.com/docs/guides-and-surveys/proxy) for details.
This installation requires these steps:
1. Add the Guides and Surveys SDK with the script tag, or through `npm` or `yarn`.
2. Call `init` and `boot` directly to initialize Guides and Surveys and connect it to your analytics provider.
> **Warning:** Required and recommended setup for this installation path
>
> - **Required**: Include `integrations` in your `boot` call to send Guides and Surveys events to your analytics provider. Without it, guide insights, survey insights, and survey responses won't appear.
> - **Strongly recommended**: Set up event forwarding using `forwardEvent` to enable the _On event tracked_ trigger in Guides and Surveys. Without it, you can only trigger guides and surveys on page load or other non-event conditions.
#### Initialize the SDK
Call `init` to fully initialize the bundle and register `engagement` on the global window object.
```js
engagement.init(apiKey: string, options: { serverZone: "US" | "EU", serverUrl: string, cdnUrl: string, mediaUrl: string, logger: Logger, logLevel: LogLevel, locale: string, nonce: string, autoRefreshIntervalSeconds: number, skip: boolean, transport: { headers: Record | (() => Record), handleHttpRequest: (request: TransportHttpRequest) => Promise } }): 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 the EU data center. Default: `US`. |
| `initOptions.serverUrl` | `string` | Optional. Sets a custom server URL for API requests. Use this option for [proxy setups](https://amplitude.com/docs/guides-and-surveys/proxy). Default: `https://gs.amplitude.com` (US) or `https://gs.eu.amplitude.com` (EU). |
| `initOptions.cdnUrl` | `string` | Optional. Sets a custom CDN URL for static assets. Use this option for [proxy setups](https://amplitude.com/docs/guides-and-surveys/proxy). Default: `https://cdn.amplitude.com` (US) or `https://cdn.eu.amplitude.com` (EU). |
| `initOptions.mediaUrl` | `string` | Optional. Sets a custom URL for proxying nudge images. Use this option for [proxy setups](https://amplitude.com/docs/guides-and-surveys/proxy) when firewalls block images. Default: `https://engagement-static.amplitude.com` (US) or `https://engagement-static.eu.amplitude.com` (EU). |
| `initOptions.chatUrl` | `string` | Optional. Sets a custom URL for AI Assistant chat requests, which don't go to `serverUrl`. Use this option for [proxy setups](https://amplitude.com/docs/guides-and-surveys/proxy) when you use the AI assistant. Default: `https://houston-chat.prod.us-west-2.amplitude.com` (US) or `https://houston-chat.prod.eu-central-1.amplitude.com` (EU). |
| `initOptions.logger` | [Logger interface](https://github.com/amplitude/Amplitude-TypeScript/blob/main/packages/analytics-types/src/logger.ts#L1-L8) | Optional. Sets a custom logging provider class. Default: [Amplitude Logger](https://github.com/amplitude/Amplitude-TypeScript/blob/main/packages/analytics-core/src/logger.ts) |
| `initOptions.logLevel` | `LogLevel.None` or `LogLevel.Error` or `LogLevel.Warn` or `LogLevel.Verbose` or `LogLevel.Debug`. | Optional. Sets the log level. Default: `LogLevel.Warn`. |
| `initOptions.locale` | `string` | Optional. Sets the locale for [localization](https://amplitude.com/docs/sdks/guides-and-surveys/sdk#localization). Default: `undefined`. If you don't set a language, the SDK uses the default language. |
| `initOptions.nonce` | `string` | Optional. Sets a nonce value for Content Security Policy (CSP) compliance. The nonce lets Guides and Surveys execute required inline styles when you enable CSP. Default: `undefined`. |
| `initOptions.autoRefreshIntervalSeconds` | `number` | Optional. Auto-refresh interval in seconds. The SDK automatically refreshes (re-fetches targeting data and reloads configuration) at this interval. Must be 60 seconds or greater. If not specified, 0, or negative, the SDK disables auto-refresh. In plugin mode, set this at init time since the plugin manages `boot()` automatically. |
| `initOptions.skip` | `boolean` | Optional. Skips initialization and doesn't set up the proxy. Call `init` again later without `skip` to initialize, then call `boot()` to start. Default: `false`. |
| `initOptions.transport` | `{ headers: Record | (() => Record), handleHttpRequest: (request) => Promise }` | Optional. Customizes outgoing SDK requests. `headers` attaches custom HTTP headers to every request. It accepts a static object or a synchronous function that returns one. The SDK calls the function before each request, so rotated credentials stay current. Go to [Custom HTTP request headers](#custom-http-request-headers). `handleHttpRequest` replaces the SDK's internal `fetch` for every request, so you fully own the outbound call — for example, to send cookies to an authenticating proxy with `credentials: "include"`. Go to [Custom transport](#custom-transport). |
##### Example: Basic initialization
```js
engagement.init("YOUR_API_KEY", {
serverZone: "US",
logLevel: LogLevel.Warn,
});
```
##### Example: Initialization with proxy
For [proxy setups](https://amplitude.com/docs/guides-and-surveys/proxy), specify `serverUrl`, `cdnUrl`, and `mediaUrl`. Add `chatUrl` if you use the AI assistant, which sends its chat requests to a different host:
```js
engagement.init("YOUR_API_KEY", {
serverUrl: "https://your-proxy-domain.cloudfront.net",
cdnUrl: "https://your-proxy-domain.cloudfront.net",
mediaUrl: "https://your-proxy-domain.cloudfront.net",
chatUrl: "https://your-proxy-domain.cloudfront.net",
});
```
> **Note:**
>
> When using a proxy, call `window.engagement.boot` to fully install Guides and Surveys, even if you are using the Browser SDK v2. Make sure to set up event handling through the `integrations` option.
##### Example: Initialization with CSP nonce
For Content Security Policy (CSP) compliance, include a nonce value:
```js
engagement.init("YOUR_API_KEY", {
nonce: "YOUR_NONCE",
});
```
##### Example: Initialization with auto-refresh
Enable auto-refresh to periodically re-fetch targeting data and reload configuration:
```js
engagement.init("YOUR_API_KEY", {
autoRefreshIntervalSeconds: 3600,
});
```
##### Example: Deferred initialization with skip
Use `skip` to register `engagement` on the window object without initializing the SDK or setting up the proxy. Call `init` again later without `skip` to complete initialization, then call `boot()` to start.
```js
// Register the engagement object without initializing
engagement.init("YOUR_API_KEY", { skip: true });
// Later, when ready to initialize
engagement.init("YOUR_API_KEY", { serverZone: "US" });
engagement.boot({ user_id: "USER_ID" });
```
After calling this function, you can access `window.engagement` and call the SDK functions. Guides and Surveys isn't fully functional until you call `boot`.
#### Boot user
Call `boot` after `init` to make Guides and Surveys available to users. In standalone installations, Guides and Surveys doesn't work until you call `boot`, even if the SDK script loads on the page.
For detailed documentation on the `boot` method, including parameter options, type definitions, and usage examples, refer to [Boot](#boot).
The following example calls `boot` with a user ID, device ID, and user properties. It also specifies `integrations` to forward Guides and Surveys events to an analytics provider.
```js
await window.engagement.boot({
user: {
user_id: "user123",
device_id: "device456",
user_properties: {
plan: "premium",
},
},
integrations: [
{
track: (event) => {
amplitude.track(event.event_type, event.event_properties);
},
},
],
});
```
## Verify your setup and ingestion
> **Tip:** Verify first event ingestion
>
> After `boot()` resolves, verify the Guides and Surveys installation and the first forwarded event:
>
> 1. In the browser console, confirm that `window.engagement` has a value.
> 2. Run `window.amplitude.getDeviceId()` and note the device ID.
> 3. Open the browser's **Network** panel, filter requests by `api2.amplitude.com`, and trigger the event. Browser SDK 2 uploads queued events every 1 second or after 30 events by default, whichever comes first. To check the event immediately, run `await window.amplitude.flush()`.
> 4. Open [User Lookup activity](https://amplitude.com/docs/analytics/user-data-lookup#activity), search for the device ID, and enable **Live event updates**. Confirm that the forwarded event appears in the activity stream.
#### Forwarding events
To use the **On event tracked** [trigger](https://amplitude.com/docs/guides-and-surveys/setup-and-target#triggers), forward events from your analytics provider to Guides and Surveys. The Guides and Surveys SDK doesn't send these events to Amplitude. The SDK uses them only for local trigger evaluation.
> **Tip:** Strongly recommended for this installation path
>
> Amplitude strongly recommends setting up event forwarding when not using the Amplitude Browser SDK plugin. Without it, you can't use the _On event tracked_ trigger, which limits your ability to show guides and surveys based on user behavior in your app.
```js
analytics.on("track", (event, properties, options) => {
// Example for Segment Analytics
window.engagement.forwardEvent({
event_type: event,
event_properties: properties,
});
});
```
#### Example of booting and forwarding events if using Segment
#### Initialize with Segment analytics
Initializing the SDK and launching a guide or survey with third-party analytics requires additional steps.
First, map the `user_id` and `device_id` fields. Optionally, configure event forwarding to enable event-based triggers.
#### script
Make sure you've added the Engagement script tag to your site before continuing.
```js
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: analytics.user().traits(),
},
integrations: [
{
// Tracking Provider: Pass Guides and Surveys events to the 3rd party analytics provider
track: (event) => {
analytics.track(event.event_type, event.event_properties)
}
},
],
});
// (Strongly recommended) Forward events from Segment to enable event-based triggers for Guides and Surveys. These events aren't sent to Amplitude servers
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});
});
});
```
#### npm
Import the Guides and Surveys package
```bash
npm install @amplitude/engagement-browser
```
Connect Guides and Surveys with Segment:
```ts
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 provider
track: (event) => {
analytics.track(event.event_type, event.event_properties);
},
},
],
});
// (Strongly recommended) Forward events from Segment to enable event-based triggers for Guides and Surveys. These events aren't sent to Amplitude servers
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,
});
});
});
```
#### yarn
Import the Guides and Surveys package
```bash
yarn add @amplitude/engagement-browser
```
Connect Guides and Surveys with Segment:
```ts
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 provider
track: (event) => {
analytics.track(event.event_type, event.event_properties);
},
},
],
});
// (Strongly recommended) Forward events from Segment to enable event-based triggers for Guides and Surveys. These events aren't sent to Amplitude servers
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 default prevents organizations with automatic template updates from enabling Guides and Surveys accidentally.
> **Warning:** Google Tag Manager isn't the recommended install method
>
> While Google Tag Manager is a convenient way to test the Guides and Surveys SDK, Amplitude recommends deploying through the Browser SDK v2, the Browser Unified SDK, or the standalone installation code path. GTM can cause timing and sequencing issues that affect guide and survey delivery. Installing the SDK directly through code gives you greater control over targeting, SDK usage, localization, and access to new features as the product evolves.
## 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:
```js
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:
```text
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;
```
For environments with stricter CSP requirements that block inline styles, use the `nonce` parameter during initialization. The parameter lets Guides and Surveys execute necessary inline styles by including your CSP nonce value:
```js
engagement.init("YOUR_API_KEY", {
nonce: "YOUR_NONCE",
});
```
### iframe support and limitations
Guides and Surveys has limited support for applications that use iframes. Consider these limitations when implementing Guides and Surveys in iframe-based applications.
**Targeting elements inside iframes:**
- Pins and tooltips can't target elements inside an iframe from the parent application.
- Each iframe requires its own SDK instance to display guides or surveys within that iframe.
- CSS selectors can't cross iframe boundaries, which prevents the SDK from locating elements inside iframes.
**SDK instances and multi-step experiences:**
- Each iframe requires a separate SDK instance, initialized with the same API key as the parent application.
- Multi-step tours that span across the parent application and iframes aren't supported.
- Each SDK instance operates independently and can't coordinate steps across different contexts.
**Event tracking and user identification:**
- Events tracked in an iframe are independent from events in the parent application.
- Ensure consistent user identification (user ID and device ID) across all SDK instances.
- Each SDK instance maintains its own state and doesn't share data with other instances.
**Toolbars and previewing:**
- Each SDK instance renders its own debug and preview toolbar, so a page with an iframe shows more than one toolbar.
- Each toolbar shows a colored badge with the instance name (`default` or `iframe: {id}`) and stacks vertically with other toolbars, so an overlapped toolbar stays reachable.
- Each toolbar controls only its own instance. Element selection and preview act on the frame that instance booted in, so pick the toolbar that matches the frame holding your target element.
**Recommended approach:**
- Install the SDK in both the parent application and each iframe that needs to display guides or surveys.
- Use the same API key for all SDK instances to ensure consistent user identification.
- Design guides and surveys to work within a single context (either parent or a specific iframe).
## Troubleshoot your installation
If your Guides and Surveys instrumentation doesn't work, verify the following topics:
### Verify Guides and Surveys installation
> **Tip:**
>
> Use the [Amplitude Chrome extension](https://amplitude.com/docs/data/chrome-extension-debug) to debug Guides & Surveys. The extension includes tools to verify SDK setup, troubleshoot why guides or surveys aren't showing, and test event-based triggers.
1. Open your browser's developer console, and enter `window.engagement`. If the return is `undefined`, Guides and Surveys installation wasn't successful.
2. If `window.engagement` returns a valid response, enter `window.engagement._.user`. A return of `undefined` indicates an issue with the Amplitude Browser SDK plugin configuration.
3. For additional debugging, enter `window.engagement._debugStatus()`. The output should look like:
```json
{
"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 display on the page.
### Verify Amplitude Browser SDK 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 the installation instructions. In particular, ensure that `amplitude.add(window.engagement.plugin())` is present in the code.
If you see errors like `amplitude is not defined` and `cannot read properties of undefined .add()`, Guides and Surveys may load before the Amplitude SDK loads. Check your code to ensure that the Amplitude Browser SDK loads before the Guides and Surveys SDK.
Guides and Surveys requires Browser SDK 2 and doesn't support the legacy Amplitude JavaScript SDK.
### Google Tag Manager configuration
If you use Google Tag Manager, ensure you update to the latest Amplitude template.
> **Warning:** Google Tag Manager custom tags
>
> If Guides and Surveys doesn't work with a Google Tag Manager (GTM) custom HTML tag, verify that you enabled the **Support document.write** checkbox in the tag configuration. Guides and Surveys requires this setting to load properly through GTM.
>
> To enable this setting:
>
> 1. In GTM, navigate to your Amplitude tag.
> 2. Expand the **Advanced Settings** section.
> 3. Check the **Support document.write** checkbox.
> 4. Save and publish your changes.
### Common root causes
The following common errors can prevent Guides and Surveys from running.
#### `boot` runs more than once
Calling `boot` more than once causes 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.
Using different API keys for Guides & Surveys and Analytics causes the SDK to fetch guides and surveys from the wrong project and results in incomplete or mismatched analytics data. Always use the same API key for both SDKs to ensure they're tied to the same Amplitude project.
## Localization
Set the `locale` option during initialization to localize a guide or survey.
- If you use the Amplitude Browser SDK 2 plugin installation (using `amplitude.add()`), set the locale in `InitOptions`.
- If you use a [third-party analytics provider](#other-amplitude-sdks-and-third-party-analytics-providers), set the locale in `options` within the `engagement.init()` method.
To dynamically update the language after the SDK initializes, use the following `updateLanguage` method. Calling `updateLanguage` re-fetches the configuration with the new locale.
```js
engagement.updateLanguage(locale: string): Promise
```
| Parameter | Type | Description |
| --- | --- | --- |
| `locale` | `string` | Required. The new language code (for example, `en`, `es`, `fr`) to set for localization. |
```js
// Example: Update language to French
await window.engagement.updateLanguage("fr");
// Example: Update language to English
await window.engagement.updateLanguage("en");
```
## Custom HTTP request headers
Attach custom HTTP headers to every outgoing request from the Guides and Surveys SDK by passing a `transport` option at initialization. Use this to authenticate requests through a security proxy or egress gateway, or to add tenant-identifying headers that your infrastructure requires. This pairs well with [proxy setups](https://amplitude.com/docs/guides-and-surveys/proxy) configured through `serverUrl`.
`headers` accepts a static object of header key-value pairs:
```js
engagement.init("YOUR_API_KEY", {
transport: {
headers: {
"X-Corp-Auth": "your-gateway-token",
"X-Tenant-Id": "your-tenant-id",
},
},
});
```
For credentials that rotate, such as short-lived JWTs required by a corporate gateway, pass a function instead. The SDK calls the function synchronously before each request, so the headers it returns are always current without re-initializing the SDK. The function must return the headers object directly — async functions aren't supported, so read the token from where your application stores it rather than fetching it inside the function:
```js
engagement.init("YOUR_API_KEY", {
transport: {
headers: () => ({
// Synchronous read of a token your application keeps up to date
"X-Corp-Auth": getCurrentGatewayJwt(),
}),
},
});
```
Keep in mind the following behavior:
- Custom headers merge after SDK-internal headers, so a custom header with the same name overrides the SDK's own value. Avoid setting `Authorization`: the SDK uses it internally to authenticate some requests with your project API key, and overriding it breaks those requests.
- If the headers function throws, the SDK logs a warning and sends the request without the custom headers instead of failing the request.
To customize more than headers (for example, the `credentials` policy for a cookie-authenticated proxy), go to [Custom transport](#custom-transport).
## Custom transport
If custom headers aren't enough, for example, your security proxy authenticates with cookies, which require the `credentials` fetch option rather than a header, provide a `transport.handleHttpRequest` callback at initialization. When set, the SDK invokes your callback instead of its internal `fetch` for every outgoing request, and your callback fully owns the HTTP call. This mirrors the [custom transport hooks of the Session Replay SDK](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin).
The SDK hands your callback a fully-formed request: the resolved URL (respecting `serverUrl` and related options), merged headers (including any `transport.headers`), and the serialized body. Your callback's only job is to execute the request and return the `Response`. Batching, serialization, retry, and error handling stay inside the SDK, which invokes your callback once per retry attempt.
For a cookie-authenticated proxy, forward the request with `credentials: "include"` so the browser sends your site's cookies to the proxy:
```js
engagement.init("YOUR_API_KEY", {
serverUrl: "https://your-proxy-domain.example.com/gs",
transport: {
handleHttpRequest: ({ url, method, headers, body, signal, keepalive }) =>
fetch(url, {
method,
headers,
body,
signal,
keepalive,
credentials: "include",
}),
},
});
```
For a JWT-authenticated proxy, spread the SDK-supplied headers and add your own:
```js
engagement.init("YOUR_API_KEY", {
transport: {
handleHttpRequest: ({ url, method, headers, body, signal, keepalive }) =>
fetch(url, {
method,
headers: { ...headers, "X-Corp-Auth": getCurrentGatewayJwt() },
body,
signal,
keepalive,
}),
},
});
```
The request object your callback receives has the following fields:
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | Resolved request URL. Respects `serverUrl` and `chatUrl` configuration. |
| `method` | `string` | HTTP method. |
| `headers` | `Record` | Fully merged request headers, including any configured `transport.headers`. Forward them unchanged (spread them if you add your own) so required headers like `Content-Type` and `Authorization` aren't dropped. |
| `body` | `string` or `FormData` (optional) | JSON string for API and chat requests, `FormData` for AI Assistant attachment uploads, absent for GET requests. Forward it unchanged. |
| `signal` | `AbortSignal` (optional) | Forward to your `fetch` call so the SDK can cancel or time out the request. |
| `keepalive` | `boolean` (optional) | Forward to your `fetch` call. |
Keep in mind the following behavior:
- Forward every field you receive, including fields added in future SDK versions, so SDK behavior like cancellation and page-exit delivery keeps working through your callback.
- Return the `Response` from your `fetch` call unmodified. AI Assistant chat requests are consumed incrementally from the response body, so the response must be a genuine streaming `Response`.
- Unlike a throwing `headers` function, callback errors fail the request. The SDK never falls back to its built-in `fetch` when you configure a callback, because an unauthenticated request would bypass your proxy's authentication.
- The callback covers core API calls, AI Assistant REST requests, SSE streams, and attachment uploads. It doesn't cover media and CDN asset loads; use `cdnUrl` and `mediaUrl` [proxy configuration](https://amplitude.com/docs/guides-and-surveys/proxy) for those.
## Preview mode for desktop apps
If you use the SDK within a desktop framework, you must perform extra instrumentation to support previewing Guides & Surveys.
The Amplitude dashboard passes your app a special query parameter through a deep link (for example, `your-app://?gs-debug-id=123`). Add logic within your app to listen for this query parameter on a deep link and call the `_startNudgeDebug` SDK method with it.
Use the following framework examples.
### Electron
Use the following minimal example to implement Guides & Surveys within Electron:
1. Register an inter-process communication function during preload.
2. In the main process: listen for and parse the `gs-debug-id` query parameter.
3. In the renderer process: listen for a message from the main process and pass the debug parameter to the Engagement SDK.
#### main.js
```javascript
const { app } = require("electron");
// Handle deep link on macOS
app.on("open-url", (event, url) => {
const parsedUrl = new URL(url);
const debugId = parsedUrl.searchParams.get("gs-debug-id");
if (debugId) {
mainWindow.webContents.send("start-engagement-debug", {
debugId: debugId,
});
}
});
// Handle deep link on Windows/Linux
app.on("second-instance", (event, commandLine, workingDirectory) => {
// Find the deep link URL in command line arguments
const url = commandLine.find((arg) => arg.startsWith(PROTOCOL + "://"));
if (url) {
const parsedUrl = new URL(url);
const debugId = parsedUrl.searchParams.get("gs-debug-id");
if (debugId) {
mainWindow.webContents.send("start-engagement-debug", {
debugId: debugId,
});
}
}
});
```
#### preload.js
```javascript
const { contextBridge, ipcRenderer } = require("electron");
contextBridge.exposeInMainWorld("electronAPI", {
startEngagementDebug: (callback) => {
ipcRenderer.on("start-engagement-debug", (_event, data) => callback(data));
},
});
```
#### renderer.js
```javascript
window.electronAPI.startEngagementDebug((data) => {
window.engagement._startNudgeDebug({
nudge: { variantId: Number(data.debugId) },
});
});
```
## Lifecycle SDK methods
### Boot
Call `boot` to initialize the Guides and Surveys SDK and make it available to users. If you don't use the [Amplitude Browser SDK v2](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2) or the [Amplitude Browser Unified SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk), Guides and Surveys doesn't work until you call `boot`, even if the SDK script loads on the page. The method triggers targeting resolution for your live guides and surveys and establishes the connection from the Guides and Surveys SDK to your analytics provider. Call `boot` once per session unless you need to change the active user.
```js
engagement.boot(options: BootOptions): Promise
```
| Parameter | Type | Description |
| --- | --- | --- |
| `options.user` | `EndUser`, `(() => EndUser)`, or `string` | Required. User information in one of these formats: an `EndUser` object, a function that returns a user object (useful for dynamic user data), or a simple user ID string. You must provide at least `user_id` or `device_id` in the user object. If you provide neither field, the method logs an error and returns early. |
| `options.integrations` | `Array` | Required. An array of integrations for tracking events. Enables sending Guides and Surveys events to your analytics provider. Without integrations, guide insights, survey insights, and survey responses won't appear. Pass `[{ track: () => {} }]` as a noop if you don't need event forwarding. |
| `options.autoRefreshIntervalSeconds` | `number` | Deprecated. Use `autoRefreshIntervalSeconds` in `InitOptions` instead. Auto-refresh interval in seconds. When enabled, the SDK automatically refreshes (re-fetches targeting data and reloads configuration) at this interval. Must be 60 seconds or greater. If not specified, 0, or negative, the SDK disables auto-refresh. If you set both init and boot values, the boot-time value takes precedence. |
#### EndUser type
The `EndUser` type includes these properties:
| Property | Type | Description |
| --- | --- | --- |
| `user_id` | `string` | User identifier |
| `device_id` | `string` | Device identifier |
| `user_properties` | `UserProperties` | Custom user properties |
| `country` | `string` | Country location data |
| `region` | `string` | Region location data |
| `platform` | `string` | Platform identifier |
**Required fields:** You must provide at least `user_id` or `device_id`. If you provide neither field, the method logs an error and returns early.
#### Integration type
The `Integration` type includes one property:
| Property | Type | Description |
| --- | --- | --- |
| `track` | `(event: Event) => void` | Optional. Function to track events to your analytics provider |
#### Boot examples
**Example 1: Basic usage with user object**
```js
await window.engagement.boot({
user: {
user_id: "user123",
user_properties: {
name: "John Doe",
plan: "premium",
signupDate: "2023-01-15",
},
},
integrations: [
{
track: (event) => {
amplitude.track(event.event_type, event.event_properties);
},
},
],
});
```
**Example 2: With analytics integration**
```js
await window.engagement.boot({
user: {
user_id: "user123",
device_id: "device456",
user_properties: {
plan: "premium",
},
},
integrations: [
{
track: (event) => {
amplitude.track(event.event_type, event.event_properties);
},
},
],
});
```
**Example 3: With function provider for dynamic user data**
```js
await window.engagement.boot({
user: () => {
return {
user_id: getCurrentUserId(),
device_id: getDeviceId(),
user_properties: getUserProperties(),
};
},
integrations: [
{
track: (event) => {
amplitude.track(event.event_type, event.event_properties);
},
},
],
});
```
**Example 4: Simple user ID**
```js
await window.engagement.boot({
user: "user123",
integrations: [],
});
```
#### Boot usage requirements
- **Async method:** `boot` is an async method. Always use `await` or handle it as a Promise.
- **Required:** You must call `boot` before any guides or surveys show.
- **Queue processing:** Boot calls process first in the SDK's method queue.
- **Single call per session:** Typically call `boot` once per user session.
### Shutdown
Shut down the Guides and Surveys SDK. This method closes all active guides and surveys and stops guides and surveys from triggering. Use this method when you need to clean up the SDK completely, such as when a user logs out.
```js
engagement.shutdown(): void
```
After calling `shutdown()`, the SDK no longer functions. To use Guides and Surveys again, call `boot()` again.
### Refresh targeting
Re-fetch targeting evaluation from the backend by making a new request to the decide endpoint. Use this method to refresh which guides and surveys are eligible to show based on the latest targeting rules and user state. The SDK automatically refreshes targeting when the user or user properties change. Manually refreshing targeting is useful when you update user properties server-side or need the latest cohort membership states.
```js
engagement.decide(): Promise
```
### Set auto-refresh interval
Configure automatic periodic refresh of targeting data. When enabled, the SDK automatically re-fetches decide data, refreshes the end user store, and reloads configuration at the specified interval. Auto-refresh is useful for long-running sessions where user state or targeting rules may change. A common use case is desktop applications, where pages reload less frequently than in browser environments.
```js
engagement.setAutoRefreshInterval(intervalSeconds?: number): void
```
| Parameter | Type | Description |
| --- | --- | --- |
| `intervalSeconds` | `number` | Optional. The interval in seconds for auto-refresh. Must be 60 seconds or greater when enabled. If you don't specify a value, or specify `0` or a negative value, the SDK disables auto-refresh. |
```js
// Set auto-refresh to every hour
window.engagement.setAutoRefreshInterval(3600);
// Set auto-refresh to every 30 minutes
window.engagement.setAutoRefreshInterval(1800);
// Disable auto-refresh
window.engagement.setAutoRefreshInterval(0);
```
You can also enable auto-refresh during boot by setting the `autoRefreshIntervalSeconds` option:
```js
await window.engagement.boot({
user: {
user_id: "user123",
device_id: "device456",
},
autoRefreshIntervalSeconds: 3600,
});
```
> **Note:** Minimum interval
>
> The auto-refresh interval must be 60 seconds or greater. If you specify a value less than 60 seconds, the SDK disables auto-refresh and logs a warning.
## Styling SDK methods
### Manage themes
Configure the visual theme mode if your app supports light and dark modes.
```js
engagement.setThemeMode(mode: ThemeMode): void
```
| Parameter | Type | Description |
| --- | --- | --- |
| `mode` | `lightMode`, `darkMode`, `auto` | Required. Select the theme to apply. |
```js
// Automatically detect user's system preferences
window.engagement.setThemeMode("auto");
// Set dark mode explicitly
window.engagement.setThemeMode("darkMode");
// Set light mode explicitly
window.engagement.setThemeMode("lightMode");
```
## Instrumentation SDK methods
### 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](https://amplitude.com/docs/guides-and-surveys/setup-and-target#triggers).
```js
engagement.forwardEvent(event: Event): void
```
| Parameter | Type | Description |
| --- | --- | --- |
| `event` | Event | Required. An [event](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#track-an-event) object. It triggers a guide or survey if its `event_type` matches. |
### Register a callback
Register a callback with the Guides and Surveys SDK. Set the Run callback action on a guide or survey button to execute the callback.
```js
engagement.addCallback(name: string, callback: () => void): void
```
| Parameter | Type | Description |
| --- | --- | --- |
| `name` | `string` | Required. Refer to this callback by name when setting a callback action on a guide or survey. |
| `callback` | `() => void` | Required. The callback to execute. |
```js
window.engagement.addCallback("toggle_dark_mode", () => {
setTheme("darkMode");
window.engagement.setThemeMode("darkMode");
});
```
### Router configuration
Configure how Guides and Surveys handles URLs in a single page application (SPA). Doing so enables reload-less URL updates.
```js
engagement.setRouter(routerFn: (url: string) => void): void
```
| Parameter | Type | Description |
| --- | --- | --- |
| `routerFn` | `(url: string) => void` | Required. A function that handles changes to the URL. |
```js
// React Router v6 implementation
import { useNavigate } from "react-router-dom";
const MyComponent = () => {
const navigate = useNavigate();
React.useEffect(() => {
window.engagement.setRouter((newUrl) => navigate(newUrl));
}, []);
};
```
```typescript
// Angular implementation
import { Component } from "@angular/core";
import { Router } from "@angular/router";
@Component({
/* ... */
})
export class AppComponent {
constructor(private router: Router) {
window.engagement.setRouter((url: string) => {
this.router.navigateByUrl(url);
});
}
}
```
For Angular apps, use the `Router` service with `navigateByUrl` in your root `AppComponent` (or an initializer). This method accepts a full URL string, which matches the `(url: string) => void` signature that `setRouter` expects.
> **Note:** Update URL behavior
>
> After you configure the router with `setRouter()`, update the URL behavior setting in the Guides and Surveys interface. For any link actions in your guides or surveys, change the URL behavior to **Use router**. The **Same tab** and **New tab** URL behaviors don't use the configured router - only **Use router** triggers your custom router function.
### Set user properties
Set user properties for the current session. Use these properties as variables inside guides and surveys content with the `@{{ property.propertyName }}` syntax.
If you use `amplitude.identify()` to share user properties, you don't need to use `_setUserProperties()`.
> **Tip:**
>
> Ensure that user properties load during the current client-side session and before the guide or survey displays. Properties shared from prior sessions aren't available.
```js
engagement._setUserProperties(userProperties: Record): void
```
| Parameter | Type | Description |
| --- | --- | --- |
| `userProperties` | `Record` | Required. An object that contains user properties as key-value pairs. Reference these properties in guides and surveys content. |
#### Example
```js
// Supply user properties manually through engagement SDK
const userProperties = { firstName: "john" };
engagement._setUserProperties(userProperties);
// For testing, view the current user properties
engagement._.user.user_properties;
```
### Set session properties
Set session properties for the current session. Session properties provide an additional way to restrict when guides and surveys trigger. At trigger time, the guide or survey displays only when the configured session property conditions match.
When a session property changes, the SDK checks for guides or surveys that can display. Session properties work with the "immediately" trigger and display content as soon as the session property conditions become true.
```js
engagement.setSessionProperty(key: string, value: any): void
```
| Parameter | Type | Description |
| --- | --- | --- |
| `key` | `string` | Required. The session property key to set. |
| `value` | `any` | Required. The value to set for the session property. |
> **Note:** Feature availability
>
> Session properties are a feature-flagged capability. Contact Amplitude support if you want to use this feature in your implementation.
#### Example
```js
// Various session properties to control guide/survey targeting
window.engagement.setSessionProperty("subscriptionTier", "premium");
window.engagement.setSessionProperty("isFeatureXEnabled", true);
window.engagement.setSessionProperty("userScore", 85);
```
## Guide and survey management SDK methods
### Show
Display a specific guide or survey. The SDK ignores any targeting rules and limits except for page targeting. Use `show` to surface a guide or survey on demand, such as from a button's `onclick` handler.
```js
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. |
#### Example: Show from a button onclick
Set the guide or survey trigger to **None** in the builder, then call `show` from your button's `onclick` handler to open the experience when the user selects it.
```html
```
### Close all
Close all active guides and surveys.
```js
engagement.gs.closeAll(): void
```
### Reset
Reset a guide or survey to a specific step.
```js
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.
```js
engagement.gs.list(): Array
```
```js
interface GuideOrSuvey {
id: number;
status: "visible" | "active";
step: number;
title: string
}
```
## Resource Center SDK methods
Control the [Resource Center](https://amplitude.com/docs/assistant/resource-center) widget from your application code. These methods work only on the default SDK instance (`window.engagement`).
### Open the Resource Center
Open the Resource Center widget. Optionally, open it directly on a specific article.
```js
engagement.rc.open(options?: { url?: string }): void
```
| Parameter | Type | Description |
| --- | --- | --- |
| `options.url` | `string` | Optional. Opens the Resource Center directly on the article (content item) with this URL. |
```js
// Open the Resource Center
window.engagement.rc.open();
// Open the Resource Center directly on a specific article
window.engagement.rc.open({
url: "https://help.example.com/articles/getting-started",
});
```
### Close the Resource Center
Close the Resource Center widget.
```js
engagement.rc.close(): void
```
### Toggle the Resource Center
Toggle the Resource Center widget between open and closed.
```js
engagement.rc.toggle(): void
```
### Clear persisted state
The Resource Center saves state like its open or minimized status, search query, and last-viewed page in the browser. Call `clearState` to remove this saved state so the Resource Center starts fresh on the next page load.
```js
engagement.rc.clearState(): void
```
### Filter content by tags
Set a filter to restrict Resource Center content by tags. The filter applies to Resource Center search results and Autopilot recommendations.
```js
engagement.setResourceCenterFilter(filter: TagFilter | null): void
```
| Parameter | Type | Description |
| --- | --- | --- |
| `filter` | `TagFilter` or `null` | Required. The tag filter to apply. Pass `null` to remove the filter. |
The `TagFilter` type supports nested AND/OR logic:
```ts
type TagFilter =
| { tags: string[] }
| { and: TagFilter[] }
| { or: TagFilter[] };
```
```js
// Filter to content tagged "billing" or "payments"
window.engagement.setResourceCenterFilter({
tags: ["billing", "payments"],
});
// Complex filter with AND/OR logic
window.engagement.setResourceCenterFilter({
and: [{ tags: ["billing", "payments"] }, { tags: ["enterprise"] }],
});
// Clear the filter
window.engagement.setResourceCenterFilter(null);
```
## Multiple SDK instances
Run multiple isolated Guides and Surveys SDK instances on the same page. Use this when a single page needs to load content from more than one Amplitude project. For example, a host application that embeds a tenant-specific experience alongside its own guides and surveys.
Each named instance has its own API key, configuration, targeting data, end-user state, and analytics routing. The default instance, `window.engagement`, continues to work unchanged and remains backward compatible.
> **Note:** Separate from iframe support
>
> Multiple SDK instances run in the same browser window. For applications that use iframes, review [iframe support and limitations](#iframe-support-and-limitations). Each iframe still needs its own SDK installation because iframes have separate `window` objects.
### How isolation works
Each named instance maintains its own:
- Configuration and targeting (decide) data, fetched with the instance's API key.
- Valtio store and end-user store.
- DOM container for rendering guides and surveys.
- Analytics integration routing, so events don't leak across instances.
- Styling and theme variables.
- `localStorage` keys, scoped by API key.
All instances share a single `#engagement-wrapper` element on the page. The default instance renders into `#engagement-container`. Each named instance renders into `#engagement-container-{instanceName}`.
### Limitations
- **Standalone installation required**: Create named instances with `createInstance` after the SDK bundle loads. The [Amplitude Browser SDK 2 plugin](#amplitude-browser-sdk-2) and [Amplitude Browser Unified SDK](#amplitude-browser-unified-sdk) paths only manage the default instance.
- **Default instance required first**: Create and boot the default instance (`window.engagement`) before you call `createInstance`. The default instance exposes `createInstance`.
- **Guides and Surveys only**: Named instances support guides (including checklists) and surveys. Resource Center and Assistant are supported only on the default instance.
- **Unique instance names**: Each named instance must have a unique `instanceName`. Creating an instance with an existing name overwrites the previous one and logs a warning.
- **Independent targeting**: Each instance fetches its own targeting data and evaluates triggers independently. Multi-step tours can't coordinate across instances.
- **Independent user identity**: Each instance manages its own end-user state. If you want instances to share a user, pass the same `user_id` or `device_id` to each `boot` call.
### Create an instance
Call `createInstance` on the default SDK to create an additional named instance. The method returns a `Promise` that resolves to the new instance. Call `boot` on the returned instance to identify the user and activate the instance.
```js
window.engagement.createInstance(instanceName: string, apiKey: string, options?: InitOptions): Promise
```
| Parameter | Type | Description |
| --- | --- | --- |
| `instanceName` | `string` | Required. A unique name for this instance. Don't use `$default`, which is reserved for the default instance. |
| `apiKey` | `string` | Required. The API key of the Amplitude project this instance sends data to. |
| `options` | `InitOptions` | Optional. The same options accepted by [`init`](#initialize-the-sdk), except `instanceName`, which is set from the first argument. Each instance can use its own proxy URLs, locale, log level, and other init options. |
#### Example: Create and boot a second instance
```js
const tenantB = await window.engagement.createInstance(
"tenant-b",
"API_KEY_FOR_TENANT_B",
{
serverZone: "US",
locale: "fr",
},
);
await tenantB.boot({
user: {
user_id: "user-456",
},
integrations: [
{
track: (event) => {
amplitude.track(event.event_type, event.event_properties);
},
},
],
});
```
After booting, call SDK methods on the returned instance just like on the default instance:
```js
tenantB.gs.show("tenant-b-onboarding");
tenantB.gs.closeAll();
tenantB.setThemeMode("darkMode");
```
### Get an existing instance
Call `getInstance` on the default SDK to retrieve a previously created instance by name. Returns `undefined` if the instance doesn't exist.
```js
window.engagement.getInstance(instanceName?: string): EngagementSDK | undefined
```
| Parameter | Type | Description |
| --- | --- | --- |
| `instanceName` | `string` | Optional. The name of the instance to retrieve. Omit this argument or pass `$default` to get the default instance. |
```js
const tenantB = window.engagement.getInstance("tenant-b");
if (tenantB) {
tenantB.gs.show("tenant-b-welcome");
}
```
### List active instances
Call `listInstances` on the default SDK to get the names of all active instances, including the default.
```js
window.engagement.listInstances(): string[]
```
```js
// Returns something like ['$default', 'tenant-b']
const instanceNames = window.engagement.listInstances();
```
### Shut down a named instance
Call `shutdown` on a named instance to stop it and remove it from the registry. After shutdown, `getInstance` no longer returns the instance. Calling `shutdown` on the default instance doesn't remove it from the registry.
```js
const tenantB = window.engagement.getInstance("tenant-b");
tenantB?.shutdown();
```
================================================================================
# Get Started
URL: https://amplitude.com/docs/guides-and-surveys/get-started
================================================================================
# Get Started
Guides and Surveys displays in-product guides and surveys to users on web, iOS, Android, and React Native apps. To get started, install one of the available SDKs based on where you want to display guides and surveys.
To open Guides and Surveys, select **Guides and Surveys** in the left navigation in Amplitude.
## Overview tab
The Overview tab shows how your guides and surveys perform. It provides insights into engagement, interactions, and user behavior, so you can track in-product guidance performance in one place.
### Filter card
The Filter card narrows the scope of your analysis to a specific date range, segment, or property condition. For example, view users on a specific account tier, or find users who performed a specific action.
### Views and completions over time
This section displays line charts for surveys viewed, surveys completed, guides viewed, and guides completed over the time range defined in the filter card.
Use [Microscope](https://amplitude.com/docs/analytics/microscope) on this chart to investigate with session replays and user streams. You can also target users in a data point with follow-up guides or surveys, create a cohort, or download the users for export to another system.
### Total guide views
This section shows the total number of non-unique views for guides over the last 30 days. Use this number to track engagement across all live guides.
### Recent guides performance
This section displays individual guides and their view counts over the last 30 days. Use this section to compare how different guides perform.
### Total survey responses
This section shows the total number of survey responses from all active surveys over the last 30 days.
### Recent survey performance
This section displays individual surveys and their response counts over the last 30 days. Use this section to analyze user response rates and identify trends.
### Rage closes
This section measures the percentage of users who rage closed a guide or survey. A high rage close rate can indicate poor timing or intrusive placement.
> **Tip:** Rage closes
>
> Amplitude treats a guide or survey that a user rapidly dismisses or exits as "rage closed". This behavior indicates user dissatisfaction.
### Guides and Surveys interactions
This section provides a real-time feed of how users interact with your guides and surveys. Use this feed to track engagement patterns and optimize your content.
## Supported apps
Guides and Surveys supports web, iOS, Android, and React Native apps. Select the target app or environment when you create a new guide or survey.
### Enable or disable apps
Guides and Surveys has a project-level setting that enables or disables different environments, called "apps". When you enable an app, it appears as an option when you create a new guide or survey.
================================================================================
# Overview
URL: https://amplitude.com/docs/guides-and-surveys/overview
================================================================================
# Overview
Amplitude Guides and Surveys offers an alternative to popup components in your application.
As part of the Amplitude platform, Guides and Surveys helps users learn your product, share feedback in context, and improve retention, activation, and engagement.
## Who uses Guides and Surveys
Anyone responsible for the user journey in a digital product can use Guides and Surveys:
- Product teams: shape onboarding and the overall user journey.
- Growth teams: use the product to drive improvements across the user funnel.
- Product marketing teams: own customer communication, including the in-product channel.
================================================================================
# Overview
URL: https://amplitude.com/docs/guides-and-surveys/guide-overview
================================================================================
# Overview
Guides are in-product messages that prompt users to complete tasks, explore features, or learn about your product. Guides use behavioral triggers, strike detection, and rate-limiting to avoid disrupting users.
Guides support [conditional logic](https://amplitude.com/docs/guides-and-surveys/conditional-logic) on buttons, so you can create personalized experiences that adapt based on user properties.
## Guide templates
When you create a guide, start with a blank guide or select a template:
| Template | Use case |
| --- | --- |
| Tour | Guide users through your product. |
| Announcement | Share product changes, company updates, or new features. |
| Checklists | Show step-by-step instructions for completing tasks. |
| Carousel | Highlight key features in a swipeable onboarding flow. |
| Banners | Display important messages or alerts. |
| Tooltips | Provide tips or context for a specific element on screen. |
| Card embed | Embed a card-format guide or survey in your page layout. |
================================================================================
# Overview
URL: https://amplitude.com/docs/guides-and-surveys/survey-overview
================================================================================
# Overview
Surveys collect user feedback. Like [guides](https://amplitude.com/docs/guides-and-surveys/guides), surveys target specific users to increase response rates.
Surveys support [conditional logic](https://amplitude.com/docs/guides-and-surveys/conditional-logic) based on survey responses and user properties. Conditional logic lets you branch survey paths and create personalized follow-up questions.
## Survey templates
Surveys offer different templates than [guides](https://amplitude.com/docs/guides-and-surveys/guide-overview#guide-templates). When you create a new survey, start with a blank survey or choose a template:
| Template | Use case |
| --- | --- |
| NPS | Measure customer satisfaction and loyalty by asking how likely a user is to recommend your product. |
| User feedback | Define your own questions to collect detailed input from users. |
| Rating | Gather initial reactions to evaluate product experiences. |
| Banner Survey | Build a custom survey using the Banner form factor. |
| Tooltip Survey | Build a custom survey using the Tooltip form factor. |
================================================================================
# Proxy requests to Guides and Surveys
URL: https://amplitude.com/docs/guides-and-surveys/proxy
================================================================================
# Proxy requests to Guides and Surveys
Set up a single AWS CloudFront distribution to reverse proxy both static assets and Guides and Surveys API traffic. A reverse proxy can help circumvent domain blocking in certain regions or by specific extensions and DNS servers. Guides and Surveys APIs and static assets are latency-sensitive, so Amplitude recommends using edge-hosted solutions to minimize round-trip time.
## Create a unified CloudFront distribution
This setup uses one CloudFront distribution with three origins and three cache behaviors:
- The **default origin** proxies `cdn.amplitude.com` or `cdn.eu.amplitude.com` for static SDK assets.
- A **secondary origin** proxies `gs.amplitude.com` or `gs.eu.amplitude.com` for API requests prefixed with `/sdk/`.
- A **third origin** proxies `engagement-static.amplitude.com` or `engagement-static.eu.amplitude.com` for nudge images using a wildcard pattern.
If your implementation uses the AI assistant, add a fourth origin and behavior for the assistant chat host. Go to [Proxy the AI assistant](#proxy-the-ai-assistant) for details.
### Step-by-step configuration
1. In AWS, open **CloudFront** and click **Create CloudFront distribution**.
2. Configure the first origin:
- **Origin domain**: `cdn.amplitude.com` for the US data center, or `cdn.eu.amplitude.com` for the EU data center
- **Allowed HTTP methods**: `GET, HEAD, OPTIONS`
- **Cache HTTP methods**: `OPTIONS`
- **Cache policy**: Choose a suitable caching policy for static assets (for example, `CachingOptimized`)
- **Origin request policy**: `AllViewerExceptHostHeader`
- **Response headers policy**: `CORS-with-preflight-and-SecurityHeadersPolicy`
- **Web Application Firewall (WAF)**: Don't enable security protections.
Click **Create distribution**
3. Add a second origin for the Guides and Surveys API. Navigate to the _Origins_ tab and click **Create origin**:
- **Origin domain**:
- `gs.amplitude.com` for the US data center, or
- `gs.eu.amplitude.com` for the EU data center
4. Navigate to the 'Behaviors' tab and click **Create behavior**:
- **Path pattern**: `/sdk/*`
- **Origin**: Select `gs.amplitude.com` or `gs.eu.amplitude.com`
- **Allowed HTTP methods**: `GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE`
- **Cache HTTP methods**: `OPTIONS`
- **Cache policy**: `CachingDisabled`
- **Origin request policy**: `AllViewerExceptHostHeader`
- **Response headers policy**: `CORS-with-preflight-and-SecurityHeadersPolicy`
> **Warning:**
>
> Use the wildcard pattern `/sdk/*` exactly as shown. Don't hard code a list of specific paths like `/sdk/config`. The Guides and Surveys SDK makes requests to multiple endpoints under the `/sdk/` path, including `/sdk/admin/config` for preview mode functionality. Using specific paths instead of the wildcard pattern causes some features to fail.
5. Add a third origin for nudge images. Navigate to the _Origins_ tab and click **Create origin**:
- **Origin domain**:
- `engagement-static.amplitude.com` for the US data center
- `engagement-static.eu.amplitude.com` for the EU data center
6. Navigate to the 'Behaviors' tab and click **Create behavior**:
- **Path pattern**: `*`
- **Origin**: Select `engagement-static.amplitude.com` or `engagement-static.eu.amplitude.com`
- **Allowed HTTP methods**: `GET, HEAD, OPTIONS`
- **Cache HTTP methods**: `OPTIONS`
- **Cache policy**: Choose a suitable caching policy for static assets (for example, `CachingOptimized`)
- **Origin request policy**: `AllViewerExceptHostHeader`
- **Response headers policy**: `CORS-with-preflight-and-SecurityHeadersPolicy`
## Proxy the AI assistant
If your implementation uses the AI assistant, add a fourth origin and behavior to the same CloudFront distribution. The assistant doesn't send its chat traffic to the Guides and Surveys API host. It calls a separate host under the `/api/` path:
- `assistant-api.amplitude.com` for the US data center.
- `assistant-api.eu.amplitude.com` for the EU data center.
> **Note:**
>
> Skip this section if your implementation doesn't use the AI Assistant.
Before you start, your browser's network tab may show assistant requests going to a region-specific hostname such as `houston-chat.prod.us-west-2.amplitude.com`. Use `assistant-api.amplitude.com` or `assistant-api.eu.amplitude.com` as the origin anyway. Both hostnames reach the same service.
To add the assistant origin and behavior:
1. Add an origin for the AI assistant. Navigate to the _Origins_ tab and click **Create origin**:
- **Origin domain**:
- `assistant-api.amplitude.com` for the US data center
- `assistant-api.eu.amplitude.com` for the EU data center
2. Add a behavior for the AI assistant. Navigate to the _Behaviors_ tab and click **Create behavior**:
- **Path pattern**: `/api/*`
- **Origin**: Select `assistant-api.amplitude.com` or `assistant-api.eu.amplitude.com`
- **Allowed HTTP methods**: `GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE`
- **Cache HTTP methods**: `OPTIONS`
- **Cache policy**: `CachingDisabled`
- **Origin request policy**: `AllViewerExceptHostHeader`
- **Response headers policy**: `CORS-with-preflight-and-SecurityHeadersPolicy`
- **Compress objects automatically**: `No`
> **Warning:**
>
> Turn off **Compress objects automatically** on the `/api/*` behavior. The assistant streams each answer as server-sent events over a long-lived `POST` request. When CloudFront compresses the response, it buffers the whole stream, so the answer arrives in one block after the agent finishes, or the request times out before anything renders.
Use the wildcard pattern `/api/*` exactly as shown. The assistant calls several endpoints under `/api/chat/` and `/api/v2/chat/`, including session creation, history, attachments, tool approval, and streaming. A behavior that lists individual paths breaks the endpoints it omits.
## Test the proxy
After AWS deploys the distribution, test each path to confirm that requests route to the correct origins.
### Test the Guides and Surveys API
Replace `SUBDOMAIN` with the CloudFront domain name and `APIKEY` with your project’s API key.
```bash
curl -i 'https://SUBDOMAIN.cloudfront.net/sdk/v1/decide' -H 'Authorization: Api-Key APIKEY'
```
A successful response returns HTTP status `200 OK`.
### Test the CDN
```bash
curl -I 'https://SUBDOMAIN.cloudfront.net/engagement-browser/prod/index.min.js.gz'
```
A successful response returns HTTP status `200 OK`.
### Test the AI assistant API
```bash
curl -i 'https://SUBDOMAIN.cloudfront.net/api/chat/settings' -H 'Authorization: Api-Key APIKEY'
```
A successful response returns HTTP status `200 OK`. A `403` error from CloudFront means the `/api/*` behavior doesn't route to the assistant origin.
## Initialize the SDK with the proxy
Point `serverUrl`, `cdnUrl`, `mediaUrl`, and `chatUrl` to the same CloudFront domain:
```js
engagement.init("API_KEY", {
serverUrl: "https://SUBDOMAIN.cloudfront.net",
cdnUrl: "https://SUBDOMAIN.cloudfront.net",
mediaUrl: "https://SUBDOMAIN.cloudfront.net",
chatUrl: "https://SUBDOMAIN.cloudfront.net",
});
```
The `mediaUrl` parameter ensures that images used in nudges are also proxied through your CloudFront distribution. The `mediaUrl` parameter prevents images from failing to load when customer domains block requests to `engagement-static.amplitude.com`.
The `chatUrl` parameter routes AI assistant traffic through your CloudFront distribution. Omit `chatUrl` if your implementation doesn't use the AI assistant. Without it, the SDK calls the assistant host directly, and the assistant fails wherever that host is blocked.
## Troubleshooting common proxy issues
- **Preview mode doesn't work**
- **Symptoms**: Preview mode fails to load or display guides properly
- **Cause**: Path pattern configured with specific paths instead of wildcard pattern `/sdk/*` (for example, using `/sdk/config`)
- **Solution**: Set the path pattern to `/sdk/*` exactly as specified in step 4. Preview mode makes requests to `/sdk/admin/config`, which won't be proxied with specific paths.
- **Guides don't persist dismissal or completion state**
- **Symptoms**: Guides reappear on the next session even after the user dismisses or completes them.
- **Cause**:
- Cause 1: Allowed HTTP methods don't include `POST`, which Guides and Surveys requires for state updates.
- Cause 2: the origin request policy isn't `AllViewerExceptHostHeader`
- **Solution**:
- Solution 1: Verify that allowed HTTP methods in step 4 include `POST` along with other required methods: `GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE`. Without `POST`, the SDK can't send requests to the `/state` endpoint to update user interaction state.
- Solution 2: Confirm the origin request policy is `AllViewerExceptHostHeader`. `POST` requests fail if the host header is overridden with an invalid value.
- **Images don't load in nudges**
- **Symptoms**: Images in guides appear as broken or missing, showing placeholder icons instead
- **Cause**:
- Cause 1: `mediaUrl` parameter not configured in SDK initialization.
- Cause 2: Missing wildcard `*` cache behavior for image origin.
- Cause 3: Image origin not configured correctly.
- **Solution**:
- Solution 1: Add `mediaUrl: "https://SUBDOMAIN.cloudfront.net"` to your SDK initialization.
- Solution 2: Confirm you have created a wildcard `*` cache behavior pointing to the `engagement-static.amplitude.com` or `engagement-static.eu.amplitude.com` origin.
- Solution 3: Verify the image origin domain matches your data center (US or EU).
- **The AI assistant doesn't answer, or the answer appears in one block**
- **Symptoms**: The chat window shows an error, stays empty, or displays the full answer after a long pause instead of streaming it word by word.
- **Cause**:
- Cause 1: `chatUrl` isn't configured, so the SDK calls the assistant host directly and a blocked domain drops the request.
- Cause 2: The `/api/*` behavior is missing, so assistant requests fall through to the wildcard `*` behavior and reach the image origin.
- Cause 3: The `/api/*` behavior compresses objects automatically, which buffers the streamed response.
- **Solution**:
- Solution 1: Add `chatUrl: "https://SUBDOMAIN.cloudfront.net"` to your SDK initialization.
- Solution 2: Create the `/api/*` behavior pointing to the assistant origin. CloudFront matches the most specific path pattern, so `/api/*` takes precedence over `*`.
- Solution 3: Set **Compress objects automatically** to `No` on the `/api/*` behavior and keep its cache policy set to `CachingDisabled`.
### General debugging steps
1. **Check CloudFront logs**: Enable logging on your CloudFront distribution to see which requests are being made and their response codes.
2. **Verify all origins are configured**: Confirm that you have the CDN origin (`cdn.amplitude.com` or `cdn.eu.amplitude.com`), the API origin (`gs.amplitude.com` or `gs.eu.amplitude.com`), and the image origin (`engagement-static.amplitude.com` or `engagement-static.eu.amplitude.com`). If you use the AI assistant, confirm the assistant origin (`assistant-api.amplitude.com` or `assistant-api.eu.amplitude.com`) as well.
3. **Test each endpoint**: Use the curl commands in the "Test the proxy" section to verify that the API, CDN, and assistant paths work correctly.
4. **Check browser network tab**: Look for failed requests in your browser's developer tools network tab, particularly 404 or 403 errors that may indicate routing issues.
================================================================================
# Build a Survey
URL: https://amplitude.com/docs/guides-and-surveys/build-a-survey
================================================================================
# Build a Survey
The survey build experience contains many of the same features at the guide builder, and uses a subset of the available [form factors](https://amplitude.com/docs/guides-and-surveys/form-factors#form-factors) (modal, popover, pin) and [properties](https://amplitude.com/docs/guides-and-surveys/form-factors#properties).
## Survey blocks
Surveys offer four unique block types, each suitable for capturing a different kind of user feedback.
### Rating
The Rating block lets users provide structured feedback using a scale you define. Surveys provide the following rating types:
| Rating type | Description |
| --- | --- |
| Stars | A three or five point scale that displays star icons to the user. |
| Numbers | A three, five, seven, or ten point scale that displays numbers to the user. |
| Emojis | A two, three, or five point scale that displays emojis that you choose for each value. |
| NPS | A 0 - 10 point [Net Promoter Score](https://en.wikipedia.org/wiki/Net_promoter_score). |
Select the gear icon in the rating block to access more settings.
| Setting | Description |
| --- | --- |
| Required | Enable to require the user to enter a rating. |
| Rating labels | Enter text labels that appear on the low and high ends of the scale. |
| Stars / Numbers / Emojis | Select the number of options available in the rating. Not applicable to NPS. |
#### Conditional logic
Conditional logic lets you create dynamic survey experiences based on user responses and user properties. On each survey step, add one or more conditions that trigger different actions based on user answers or user characteristics. Conditions can reference responses from any prior step in the survey, not just the current one.
Use conditional logic to:
- **Trigger actions based on responses**: Change what happens next based on how a user answers.
- **Branch survey paths**: Users who give a low rating might get a follow-up question asking why, while high ratings advance to a different step.
- **Branch based on earlier responses**: Reference answers from any previous step to create multi-layered survey paths. For example, use a rating from step 1 to determine what happens after step 3.
- **Personalized experiences**: Show different questions or steps based on previous responses or user properties.
- **Combine conditions**: Use both survey responses and user properties together to create branching logic.
For example, on a question with a five point scale, use the following logic:
- If `rating < 4` then `Go to step to ask what went wrong`
- If `rating > 3` then `Go to step with a 'thank you' message`
You can also reference responses from earlier steps. For example, in a multi-step survey:
- Step 1 asks for a feature rating.
- Step 2 asks a follow-up question.
- Step 3 uses conditional logic based on the step 1 rating: if `step 1 rating < 3` then `Go to a detailed feedback step`, otherwise `Go to a thank-you step`.
You can also combine survey responses with user properties. For example:
- If `rating > 8` AND `subscription_tier = premium` then `Show survey asking for app store review`
- If `rating < 5` AND `country = US` then `Show survey with US support contact information`
For details about conditional logic, including how to use it with buttons and guides, go to [Conditional Logic](https://amplitude.com/docs/guides-and-surveys/conditional-logic).
### Long answer
The Long answer block provides users space to provide unstructured feedback.
Select the gear icon in the Long answer block to access more settings.
| Setting | Description |
| --- | --- |
| Required | Enable to require the user to enter a rating. |
### Short answer
The Short answer block provides users space to provide unstructured feedback.
Select the gear icon in the Short answer block to access more settings.
| Setting | Description |
| --- | --- |
| Required | Enable to require the user to enter a rating. |
| Pre-fill key | Populate the input with a user property that you specify, using the ingested property name, for example `device_type`. If the user property isn't found for a specific user, nothing populates in the field. User properties must be available client-side during the current session. Go to [Set user properties](https://amplitude.com/docs/sdks/guides-and-surveys/sdk#set-user-properties) for implementation details. |
> **Note:** Mobile pin limitations
>
> Short answer and long answer blocks aren't available for mobile pins.
### List
Lists provide a multiple choice input, letting users choose a response from a list that you define.
Select the gear icon in the List block to access more settings.
| Setting | Description |
| --- | --- |
| Required | Enable to require the user to select an option. |
| Display as dropdown | Lets users select one option. Changes the block's form elements from radio buttons to a dropdown. |
| Multi-select | Lets users select more than one option. Changes the block's form elements from radio buttons to checkboxes. |
| Randomize order | Randomizes the item order in the list each time it displays to a user. |
| "Other" option | Provides users the option to select `Other` as a result, and optionally supply a written answer. |
## Setup and target your survey
Survey setup and targeting works the same as for [guides](https://amplitude.com/docs/guides-and-surveys/setup-and-target). Follow the guide instructions to set up your survey.
================================================================================
# Analyze a Survey
URL: https://amplitude.com/docs/guides-and-surveys/analyze-a-survey
================================================================================
# Analyze a Survey
Amplitude provides two levels of survey analysis: aggregate data on survey use and engagement, and response-level data on individual responses and the users who submitted them. Both views are available in the survey itself.
## Insights tab
The Insights tab shows how a survey is performing. The Insights tab tracks responses, identifies trends, and filters data to support decisions based on user feedback.
### Type-specific insights
Some survey types offer insights that are specific to the type of data they capture.
#### NPS
Net Promoter Score (NPS) survey questions provide a breakdown of promoters (score: 8 - 10), passives (score: 6 - 7), and detractors (score: 0 - 5). To calculate the NPS, subtract `% detractors` from `% promoters`.
#### List
Understand the breakdown of responses by option.
### Filter card
The Filter card narrows the scope of analysis to a specific date range, segment, or property condition. For example, view users on a specific account tier, or find users who performed a specific action.
Use the **Ignore test/preview data** toggle to filter out data from test users and preview mode. When you enable this toggle, Amplitude shows only production data in both the Insights tab and the Responses tab, so test activity does not skew your results.
### Views and completions over time
View line charts for surveys viewed and surveys completed over the time range defined in the filter card.
Use [Microscope](https://amplitude.com/docs/analytics/microscope) on this chart to investigate further with session replays and user streams. You can also target the users in a data point with follow-up guides or surveys, create a cohort, or export the user list to another system.
#### Time-based analysis
Track guide and survey engagement trends over predefined time periods.
- Hourly
- Daily
- Weekly
- Monthly
- Quarterly
Use these presets to review when users are most likely to engage with the guide or survey, and to check whether engagement changes after events such as a new product release.
#### Date range selection
Select a predefined range based on the unit of time, or select the calendar icon to define a custom range. Choose from:
- Rolling window (`Last # complete days and today`)
- Since date
- Between dates
Use the advanced settings to:
- Add a date offset to a rolling window
- Exclude Today
- Enable Time Range
## Responses tab
The Insights tab shows aggregate trends. The Responses tab shows the who, what, and when of survey data, with user-level detail tied to specific users and timestamps.
On the Responses tab, you can:
- **View individual responses**: Review what each user submitted.
- **Export responses**: Export a CSV of survey responses.
- **Sort and filter**: Organize responses by date, user ID, or specific answers.
- **Pin important columns**: Keep key data points visible while scrolling.
- **Adjust date ranges**: View responses over the past 7, 30, 60, or 90 days.
Use the **Ignore test/preview data** toggle to filter out data from test users and preview mode.
================================================================================
# Hosted Surveys
URL: https://amplitude.com/docs/guides-and-surveys/hosted-surveys
================================================================================
# Hosted Surveys
A hosted survey collects feedback through a standalone, Amplitude-hosted page that you share by link, instead of showing the survey inside your product. Share the link in an email, a support ticket, or a chat message, and recipients answer on a dedicated page without opening your app. Use a hosted survey to reach people who aren't in your product, such as churned or prospective users. To collect feedback from users while they're in your app, use an in-app survey instead.
## How hosted surveys work
A hosted survey has a unique URL that points to a dedicated page for that survey. Anyone who opens the link sees the survey on its own page and submits a response directly. Hosted surveys use a standardized layout, so the step type (for example, modal, pin, or popover) doesn't affect how the questions and inputs display.
## Get a survey link
1. In Amplitude, open the survey you want to share.
2. Open the survey's hosted link options using the globe icon in the upper right, near the Save and Publish buttons.
3. Copy the generated link from the modal.
4. Share the link through email, chat, a support tool, or any other channel.
## Identify respondents
By default, Amplitude records each response under a randomized user ID (for example, anonymous-hosted-survey-user-8db2f3c13af5). To attribute responses to known users, update the link to include identification parameters with the user's or device's unique ID:
- `userId`: associates the response with a specific user ID.
- `deviceId`: associates the response with a specific device ID.
For example, append a user ID to the link:
```text
https://?userId=user42
```
## Analyze hosted survey responses
Hosted surveys emit the same lifecycle events as in-app surveys, so you can analyze responses in Amplitude:
- Survey Viewed
- Step Completed
- Survey Completed
- Survey Submitted
Amplitude tags events and responses from a hosted survey with a distinct `App Type` property, so you can separate them from in-app responses in your analysis.
> **Note:**
>
> Amplitude doesn't capture Survey Abandoned events for hosted surveys.
## Limitations
During Early Access, hosted surveys have the following limitations:
- You can't configure the survey buttons. Amplitude sets them based on your survey options.
- Hosted surveys don't have dedicated themes. You can control their styling with your existing themes.
- Hosted surveys don't respect targeting, triggers, or limits.
- Hosted surveys require Amplitude Analytics. They don't support third-party analytics tools, such as Segment.
================================================================================
# Setup and Targeting
URL: https://amplitude.com/docs/guides-and-surveys/setup-and-target
================================================================================
# Setup and Targeting
Targeting controls which users receive your guide or survey. Triggering controls when and where it appears. Both settings live in the _Setup_ tab in the builder.
## Targeting
Not every message is for every user. Targeting lets you define which users receive your guide or survey, and when. You can target either **All Users** or **Targeted Users**.
**All Users** targets every user who visits your site with this guide or survey.
**Targeted Users** lets you create segments of users to receive your guide or survey.
Each segment can filter by property or cohort, and can have multiple filters. For example, target your guide or survey to users from outside the United States who are new users within the last 30 days.
The property picker includes transformed user properties defined in [Amplitude Data](https://amplitude.com/docs/data/transformations) alongside standard user properties. Targeting on transformed properties ensures the users your guide or survey reaches match the same population you see in Analytics charts and cohorts, because both use the same transformation rules.
> **Note:** Array user properties
>
> Guides and Surveys evaluates targeting rules during remote evaluation. The user property store that powers this evaluation flattens nested objects, but it doesn't flatten array-valued properties.
>
> If you send a property as an array of objects (for example, `subscription: [{plan, state, length}]`), dotted paths like `subscription.plan` aren't available at evaluation time, even if those paths appear on user profiles in Analytics. Cart Analysis creates those dotted properties for Analytics, but they don't sync to the user property store that Guides and Surveys reads.
>
> To target on array-derived values, set a flat scalar user property (for example, `subscription_plan: "enterprise"`) and target that property instead.
You can set both rollout percentage and bucketing unit for your user segments. For example, target 10% of a segment when you first publish a guide, then increase it to 100% after you confirm the engagement data.
> **Note:** Using more than one segment
>
> When you add more than one segment to your targeting, Amplitude `OR`s each segment. This means that if a user belongs to _any_ segment, Amplitude shows them the guide or survey.
### First Seen timestamp
The targeting property picker includes a built-in **First Seen** property. Guides and Surveys pulls this timestamp from the Amplitude ID table during remote evaluation, so it's available even on a user's very first session.
Use First Seen instead of cohorts when targeting new users. Cohort membership updates with a delay, which means a cohort-based new-user filter doesn't match users on their first visit. First Seen evaluates in real time.
**Example: Target users who signed up today**
In your targeting segment, add a filter where **First Seen** is greater than or equal to today's date. Only users whose First Seen timestamp is today or later are eligible.
> **Note:** Missed first login
>
> If a user doesn't visit a page where the guide appears on their first login, they remain eligible on future logins. Their First Seen timestamp doesn't change, so they continue to match the targeting condition.
### Bucketing units
The bucketing unit determines how Amplitude assigns users to receive your guide or survey when you use rollout percentages. Bucketing keeps the experience consistent across devices and sessions for the same entity.
#### Available bucketing units
| Bucketing unit | Behavior |
| --- | --- |
| **User ID** | Buckets users by user ID. When a user logs in from different devices, they remain in the same bucket and receive a consistent experience. This is the default. |
| **Device ID** | Buckets users by device identifier. Each device receives an independent assignment, so the same user on different devices might have different experiences. |
| **Account ID** or **Organization ID** | Buckets users by a custom property like account ID or organization ID. Use this when all users in the same organization need the same experience. For example, if you test a feature with 50% of accounts, all users in a selected account see the feature, and all users in excluded accounts don't. |
#### Bucketing examples
**Example 1: User ID bucketing** You set a 50% rollout with User ID bucketing. A user logs in on a laptop and receives the guide. After the user later logs in on a phone with the same user ID, the user continues to see the guide because Amplitude bases bucketing on user ID.
**Example 2: Account ID bucketing** You set a 50% rollout with Account ID bucketing (using a custom `account_id` property). Account "Acme Corp" with 10 users falls into the selected 50%. All 10 users from Acme Corp see the guide, regardless of device. All users from "Beta Inc" in the other 50% don't see the guide.
**Example 3: Device ID bucketing** You set a 50% rollout with Device ID bucketing. A user's laptop falls into the selected 50% and receives the guide. The same user's phone falls into the other 50%, so the guide doesn't appear on the phone, even though both devices belong to the same user.
#### When to use each bucketing unit
- **User ID**: Use when you want consistent experiences for logged-in users across their devices.
- **Device ID**: Use for anonymous users or when device-specific targeting matters.
- **Account/Organization ID**: Use when all users in an organization need the same experience. This is useful for B2B products or organizational rollouts.
### Exclude a group of users
You may want to exclude a group of users from a specific guide or survey. For example, you might run a survey but exclude customers in the United States, or exclude internal users to receive responses only from actual customers.
You can exclude users at the cohort or segment level. The process is similar for both. This section focuses on excluding at the cohort level. Refer to [Cohorts](https://amplitude.com/docs/analytics/behavioral-cohorts) for more information about cohorts.
To exclude a cohort of users, set the `where` statement to `does not equal` the cohort you want to exclude.
### Send a link to a guide
Send users a link to your guide or survey to target them more directly. From the guide or survey builder, expand the menu next to the Save button, and select **Share link**.
In the modal:
- For web, copy the query parameter and append it to a page on your site that's instrumented with Guides and Surveys. When the recipient selects the link with the query parameter attached, the guide displays.
- For mobile, scan the QR code or open the share link URL on a device with your app installed. The guide displays in the app.
> **Note:** User and page targeting
>
> When you send a direct link to a guide or survey, Amplitude overrides any audience or user targeting you set on the guide.
>
> Amplitude doesn't override page targeting. To ensure the link works as expected, confirm the page you send can display the guide.
## Triggers
Triggers control when and where the experience appears.
Within the targeting card, select what events or interactions launch the experience, gate the experience to specific pages, and adjust the priority.
### When
Amplitude provides the following options to trigger an experience.
| Trigger | Description |
| --- | --- |
| **None** | The experience doesn't appear by default. Select this option to launch the experience through the SDK, through a call to action (CTA) in another guide or survey, or through any other external trigger. |
| **Immediately** | The experience appears after the page loads. |
| **When element appears** | Launches the experience when a specified element appears on screen. Enter a CSS Selector or XPath path expression, or select **Test and Preview** to launch the visual selector. This trigger fires once per page load. Amplitude can't detect whether the element has reappeared or is still present, so the experience doesn't re-trigger if the element scrolls out of view and back in. |
| **When element clicked/tapped** | Launches the experience when the user interacts with the specified element. Enter a CSS Selector or XPath path expression, or select **Test and Preview** to launch the visual selector. |
| **After time on page/screen** | Specify a delay (in minutes or seconds) that a user must spend on the page before they receive the experience. |
| **Smart delay** | Shows the experience after the user completes their current task. |
| **Rage click/tap** | Shows the experience after a rage click by the user. Amplitude considers a rage click to be rapid successive clicking or tapping in the same location. |
| **User confusion** | Shows the experience when Amplitude detects user confusion, as signaled by the user's mouse movement. |
| **On event tracked** | Shows the experience after the user triggers an event that you define. The event must fire client-side so the Guides and Surveys SDK can observe it. Guides and Surveys doesn't support [Labeled Events](https://amplitude.com/docs/data/visual-labeling) or [Custom events](https://amplitude.com/docs/data/custom-events) as triggers. |
| **After N events in session** | Shows the experience after the user triggers a specific event at least N times in the current session. Configure the event name and minimum count in the guide or survey builder. **Minimum SDK version required:** iOS/Android v3.7.0+, React Native v3.7.0+, Web (all versions). This is a breaking feature. Guides and surveys with this trigger type don't reach users on older mobile SDK versions. Go to the [changelog](https://amplitude.com/docs/guides-and-surveys/guides-and-surveys-mobile-sdk-changelog). |
> **Tip:** Show on element click: use the SDK
>
> To show a guide or survey when a user clicks a button or other element, the recommended approach is to set the trigger to **None** and call the [`.show` SDK method](https://amplitude.com/docs/sdks/guides-and-surveys/sdk#show) from the element's `onclick` handler. This gives you precise control over which experience appears and when.
#### Trigger delay
For any trigger option besides **Immediately**, you can configure a delay (in seconds) before the guide or survey fires. Use a delay to make timing less intrusive. For example, show a survey five seconds after a user selects **Checkout** rather than the instant they click.
Previously, only the **After time on page/screen** trigger supported a wait. Trigger delay extends that capability to event-based, element-based, and other non-immediate triggers.
##### How to configure
In the nudge editor, open the **Trigger** section. After you select a non-immediate trigger, a **Delay** field appears. Enter the number of seconds Amplitude waits before firing the guide or survey.
##### Behavior
- The delay countdown starts when the trigger condition first matches. If the user navigates away before the delay elapses, the guide or survey doesn't fire on the original page.
- Delay is per-trigger. Different triggers on the same nudge can use different delays.
- When you combine a delay with [conditional logic](https://amplitude.com/docs/guides-and-surveys/conditional-logic) (for example, "fire only when element X is visible"), Amplitude re-evaluates the condition at firing time, after the delay, rather than at trigger time.
##### Example
To show an NPS survey ten seconds after a `purchase_completed` event, set the trigger to **On event tracked** with the event `purchase_completed`, and set **Delay** to `10`.
> **Note:** SDK requirement
>
> Trigger delay requires a recent version of the Engagement Browser SDK. Update to the latest SDK release to use this feature.
#### Session properties
Session properties add a layer of trigger targeting restrictions for guides and surveys. When a guide or survey triggers and has session property conditions, all configured session property conditions must match for the experience to display.
The SDK sets session properties dynamically using the `setSessionProperty` method, and they can change throughout a user's session. When a session property value changes, the SDK automatically evaluates whether any guides or surveys can now display, making session properties effective with the "Immediately" trigger.
Common use cases for session properties include:
- **User belongs to multiple orgs**: Control guide or survey visibility based on features of the user's current organization (`isFeatureEnabled: true`).
- **Progress tracking**: Show guides and surveys based on user progression (`onboardingStep: 3`).
- **Dynamic state that shouldn't persist as a user property**: React to real-time user behavior or application state.
> **Note:** Feature availability
>
> Session properties are a feature-flagged capability. Contact Amplitude support to use this feature in your implementation.
### Where
Control whether your guide or survey displays on all pages, only specific pages, or excludes specific pages.
When you include or exclude specific pages, Amplitude accepts the following match types:
- URL matches
- URL/screen matches exactly
- URL/screen matches pattern
- URL/screen contains
- URL/screen starts with
- URL/screen ends with
- URL/screen matches regex
- Element CSS selector on page
#### Element CSS selector on page
Configure your guide or survey to display only when a specific DOM element appears on the page. Enter a CSS selector that identifies the target element. This match type evaluates when the trigger event fires.
You can use this rule for exclusion. For example: exclude pages where an element with the CSS selector `.class-foo` is on the page.
#### Combining page targeting rules
You can combine URL and element conditions using AND/OR logic. For example, you can display a guide when (a) URL contains `/checkout` AND (b) there's an element with `.payment-success` visible.
#### Project-wide default page exclusions
Set default page exclusions at the project level to apply them to every experience automatically. Configure defaults under _Project Settings > Guides and Surveys > Default page exclusions_. Individual experiences can extend the project-wide default rules by specifying their own include or exclude rules in the **Where** section of the builder.
The same URL match types listed above (`URL matches`, `URL contains`, `URL starts with`, and others) apply to project-wide default exclusion rules.
Use project-wide exclusions when your app has pages where experiences should never appear, such as checkout flows, password reset flows, or error pages. Configuring exclusions once at the project level avoids repeating the same rules on every experience and prevents experiences added later from appearing on those pages.
### Priority
Use priority to rank the importance of a guide or survey relative to others the user might encounter.
- Urgent
- High
- Medium
- Low
#### Tiebreakers when multiple guides are eligible for display
When more than one guide or survey is eligible for display at the same time, Amplitude uses these tiebreakers to decide which experience to show:
1. **Active before inactive**: Amplitude shows active guides or surveys before inactive ones.
2. **Priority**: Higher-priority experiences display first (Urgent > High > Medium > Low).
3. **Most recently seen**: If the user has seen one or more of the tied experiences before, Amplitude shows the experience the user saw most recently.
4. **Most recently created**: If the user hasn't seen either experience, or saw both at the same time, Amplitude shows the most recently created experience.
#### Prioritization table
The new **Prioritization** table lets you order guides and surveys _within_ a specific priority, so you can set a distinct order for every guide and survey. Sub-priority replaces rules 3 and 4 in the tiebreakers above.
Sub-priority is specific to each platform. Use the platform filter at the top of the prioritization view to switch to a specific platform (for example, **Web**, **iOS**, or **Android**) and set priorities and sub-priorities independently for each.
Sub-priority is also specific to form factor. These are the form factor groupings:
- Modals, pins, and popovers
- Checklists
- Banners
> **Note:**
>
> Priority is irrelevant for tooltips and embeds. Tooltips and embeds always render if the targeting, trigger, and limits criteria are all met. Amplitude can render multiple tooltips and embeds simultaneously.
## Limits
Limits prevent users from receiving too much messaging.
| Limit | Description |
| --- | --- |
| Unpublish when X responses received | Surveys only. When you enable this, Amplitude automatically unpublishes the survey after it receives the configured number of responses. The response count is cumulative and doesn't reset when you unpublish or republish the survey. If you re-publish a survey that has already reached the cap, Amplitude unpublishes it again when the next response is submitted. Raise the cap before you re-publish if you need more responses. |
| Stop showing when completed | Enabled by default. When you disable this, the experience is eligible to trigger again through its [trigger](#triggers) for the [targeted users](#targeting) after the user completes it. To disable this option, you must also disable `Stop showing when dismissed`. |
| Stop showing when dismissed | Enabled by default. When you disable this, the experience is eligible to trigger again through its [trigger](#triggers) for the [targeted users](#targeting) after the user dismisses it. |
| Cooldown | When you enable this, it limits how often the experience can trigger for a user. Amplitude ignores cooldowns when (a) the experience is [active](#active-state) or (b) the SDK, a button action, or a share link force-triggers it. To enable this option, disable `Stop showing when dismissed` first. |
## Localization
Localization lets you serve guides and surveys in different languages without creating a new guide or survey for each language. Refer to [Localization](https://amplitude.com/docs/guides-and-surveys/localization) for more details.
## Status
Statuses let you manage when your guide or survey displays.
| Status | Description |
| --- | --- |
| Draft | Lets you make changes to and test the experience, but the experience doesn't appear to users. |
| Testing | The guide or survey can display to [test users](https://amplitude.com/docs/guides-and-surveys/testing#testing-status-function). |
| Published | The guide or survey is live. Any changes you make to a published experience appear to users after you save the guide or survey. |
| Scheduled | Define start and end dates during which your experience appears. Start and end times use the timezone set on your project. |
If your project requires a reviewer to sign off before publishing, see [Approval workflows](https://amplitude.com/docs/guides-and-surveys/approval-workflows) to configure approvers and request a review.
### Bulk unpublish
To unpublish multiple guides or surveys at once, go to the Guides and Surveys list page, select the items you want to unpublish, and click **Unpublish**.
Common use cases include:
- Unpublishing all active experiences before a demo or test run.
- Unpublishing multiple versions of the same guide across different platforms at once.
## Settings
Access guide or survey settings through the gear icon at the top of the builder.
| Setting | Description |
| --- | --- |
| **Dismissable** | Gives users an option to dismiss the experience. |
| **Snoozable** | Lets the user snooze the experience for the specified duration. |
| **Label** | The snooze button's text. Only visible when you enable Snoozable. |
| **Duration** | How long the snooze lasts. The experience doesn't re-appear for the user until at least that much time has passed. Only visible when you enable Snoozable. |
| **Snoozable on all steps** | If you disable this, the guide or survey's first step is the only step with a snooze option. Only visible when you enable Snoozable. |
| **Show step counter** | Adds a step counter to each step in the guide or survey. For example, on a guide with five steps, the indicator `2/5` appears on the second step. |
## Active state
When a user first views a guide or survey, the guide or survey becomes "active". The guide or survey remains active until the user completes or dismisses it. For example:
- A user sees a guide or survey on your homepage.
- The user navigates to the contact page.
- The guide or survey remains active even though the trigger condition didn't fire. The guide or survey follows the user to the contact page.
When Amplitude temporarily hides a guide or survey, it doesn't show it to the user, but the guide or survey remains active. After the `temporarily hide if` conditions no longer apply, the active guide or survey is eligible for display again.
================================================================================
# Experiments
URL: https://amplitude.com/docs/guides-and-surveys/experiments
================================================================================
# Experiments
Run A/B and multi-armed bandit experiments on your guides and surveys with Amplitude Experiment so you can compare variants and ship the version that performs best. Install the [Guides and Surveys SDK](https://amplitude.com/docs/guides-and-surveys/sdk) before you run an experiment.
> **Note:** Manager or Administrator role required
>
> Running an experiment on your guide or survey requires the Manager role at a minimum. For more information about how roles impact who can use Guides and Surveys, go to [Role-based Access Controls](https://amplitude.com/docs/admin/account-management/role-based-access-controls-rbac).
## How experiments work in Guides and Surveys
Guides and Surveys experiments test whether showing a guide or survey affects user behavior:
- **Control**: Users in the control group don't see the guide or survey.
- **Variants**: Users in variant groups see the guide or survey you create.
For example, to run a 50-50 test on whether a guide improves feature adoption:
- Set the control to 50% (these users don't see the guide).
- Set variant A to 50% (these users see the guide).
This split lets you measure the impact of your guide or survey against a baseline of users who don't see it.
## Run an experiment
To add experimentation to your guide or survey, select **Add experiment**.
After you add an experiment, Guides and Surveys controls the experience, and Experiment controls user targeting and variant distribution based on the experiment type you choose.
### Choose an experiment type
Guides and Surveys offers two experiment types.
#### A/B test
Choose an A/B test to create two variants of the same guide. Amplitude decides the winner based on the data it receives. Access results the same way as any other Amplitude experiment.
#### Multi-armed bandit test
Choose a [Multi-armed Bandit](https://amplitude.com/docs/feature-experiment/workflow/multi-armed-bandit-experiments) test for a more dynamic approach. The system allocates more traffic to the higher-performing variant in real time, which helps you optimize faster.
### Configure variants
After you select an experiment type, Guides and Surveys adds a control and two variants with autogenerated keys. The control serves as your baseline for measuring impact, and you can create multiple variants to test different versions of content or design.
To rename a variant, select it and click _More options_. From this menu, update the name, duplicate, or delete the variant.
> **Warning:** Complete experiment setup
>
> Adding variants is only the first part of experimentation in Guides and Surveys. To ensure users experience variants as they should:
>
> 1. Make sure the experiment is running. Define a goal, review targeting, and click _Start Experiment_. For more information, go to [Manage the experiment](#manage-the-experiment).
> 2. If a specific user doesn't experience a variant, ensure the user is part of the experiment's target audience.
> 3. If a user sees one variant, they should continue to receive that variant. Navigate to _Users > User Profiles_. Search for the user and open their profile. Go to the _Guide_ and _Survey_ tabs to view which experiences the user has seen.
### Manage the experiment
Click _Manage Experiment_ to open the experiment editor in a new tab. The experiment takes the name of your guide or survey, and contains any variants you added.
> **Note:** Updating variants
>
> Variant names stay in sync between your guide or survey and the experiment when you save the guide or survey.
For more information about working with experiments, go to [Feature Experiment](https://amplitude.com/docs/feature-experiment/overview)
> **Tip:** Exposures and assignments
>
> Exposure events in Guides and Surveys experiments work similarly to a standard experiment. However, some cases can cause an uneven split between control and variant exposures. The targets and limits you set affect how often treatment exposures occur.
>
> Consider the following example:
>
> Amplitude assigns User A to the control, and User B to the treatment.
>
> - If Amplitude serves **User B** another guide or survey that blocks the display of the treatment, no exposure event fires. The exposure event fires only when User B sees the treatment.
> - If the same scenario occurs for **User A** in the control group, the exposure event fires because User A doesn't receive the relevant guide, which is expected for the control group.
### End the experiment
To end the experiment, navigate to the experiment's configuration page, click _Stop Experiment_, and choose one of the following options:
- **Complete experiment**: Declare a winner. If one of the variants is the winner, Amplitude archives the losing variant and publishes the winning variant. If you select the control as the winner, the experiment returns to its initial state and sets the control rollout to 100%, which means no users see the guide or survey.
- **Continue running experiment**: The experiment remains live so you can collect more data.
## Insights
The Insights tab is the dashboard where you track how users engage with your guide or survey. Monitor trends in views and completions over time, and track how different variants perform relative to one another.
### Time-based analysis
Track guide and survey engagement trends over predefined time periods:
- Hourly
- Daily
- Weekly
- Monthly
- Quarterly
Use these presets to find when users are most likely to engage with the guide or survey, and whether engagement changes after a new product release.
#### Date range selection
Select a predefined range based on the unit of time, or click the calendar icon to define your own range. Choose from:
- Rolling window (`Last # complete days and today`)
- Since date
- Between dates
Use the advanced settings to:
- Add a date offset to a rolling window
- Exclude Today
- Enable Time Range
### Performance overview
The top chart on the Insights tab is the Performance Overview. Amplitude displays high-level metrics that track how your guide or survey is performing:
| Metric | Description |
| --- | --- |
| Guides / Surveys viewed | The number of times the guide or survey was shown to users. |
| Guides / Surveys completed | The number of times the guide or survey was completed by users. |
| Trend graph | Tracks the view or completion count over the time range specified in the date range selector. |
================================================================================
# Testing and Publishing
URL: https://amplitude.com/docs/guides-and-surveys/testing
================================================================================
# Testing and Publishing
Amplitude lets you test your guides and surveys before publishing them. Testing confirms the setup and the behavior match your expectations.
There are two ways to test your guides and surveys:
- Preview mode: a quick first check to see how your guide or survey looks and confirm your setup.
- Testing status: a live test with specific users before launch.
## Preview mode
Preview mode confirms that your guides and surveys behave as expected. To check only the look of a guide or survey, open it in Amplitude. To confirm runtime behavior, test it in preview mode.
Amplitude recommends a thorough test before launch to confirm:
- Button actions behave as you intend.
- Multi-step guides and surveys have the right pace.
- Pins and tooltips appear where they should.
> **Note:** Multi-page displays
>
> A known issue in Preview mode causes multi-page guides or surveys to display incorrectly in multi-page apps. This issue affects Preview mode only, not the published guide or survey.
To open Preview mode from the builder:
1. Open a guide or survey.
2. Click **Preview**.
3. For web, enter the URL of the page with the [Guides and Surveys SDK](https://amplitude.com/docs/guides-and-surveys/sdk) installed. For mobile, scan the QR code or open the preview URL.
4. Amplitude verifies that the SDK is available. For web, the URL opens in a new tab with the preview bar visible. For mobile, the preview opens in the app with the preview bar displayed.
By default, the preview window stays open until you close it. Disable **Don't automatically close the preview window** if you want the window to close after 10 seconds of waiting for app.amplitude.com to communicate with the G&S SDK in your application.
### Edit a guide or survey in Preview mode
You can change a guide or survey while you preview it, without switching back to the builder. Edits apply to both the dashboard and the preview as soon as you save, which speeds up position-heavy work like card embeds.
1. Open a guide or survey in Preview mode.
2. In the preview bar, click **Edit**.
3. Change the form factor, position, or other [properties](https://amplitude.com/docs/guides-and-surveys/form-factors#properties).
4. Click **Save**.
Amplitude applies your changes to the dashboard and the preview right away. This works for both anchored guides, such as pins, and non-anchored form factors, such as banners, modals, checklists, and popovers.
### Test User mode
> **Info:** Mobile only
>
> Available on mobile only.
Test User mode lets you preview and debug guides and surveys on a real device without affecting your production analytics. The SDK treats users in Test User mode differently from regular users, so guides and surveys don't render the same way they do for everyone else.
Use Test User mode when you're doing one of the following:
- Installing the Amplitude SDK.
- Reproducing a reported issue.
- Verifying that a guide or survey triggers correctly.
Navigate to _Project Settings > Guides and Surveys_ to configure Test User mode.
Turn it off after you finish debugging. Leaving devices or accounts in Test User mode long-term can create confusion about expected rendering behavior.
### Conditions checked in preview mode
The preview bar shows the status of the three conditions Amplitude uses to decide whether to show the guide or survey:
- Trigger
- Limit
- Throttle
### Condition status
Each condition has three possible statuses:
| Status | Description |
| --- | --- |
| Green | The condition is passed, and ready to display the guide or survey. |
| Yellow | The condition isn't passed, and the guide or survey doesn't display. |
| Blue | The condition is pending or bypassed. |
### How preview mode works
Preview mode uses browser messaging to communicate between the Amplitude dashboard and your application. When you start a preview:
1. The Amplitude dashboard opens your application URL in a new tab.
2. The dashboard waits about 10 seconds for a message from the Guides and Surveys SDK running on your page.
3. If the SDK sends a message, the dashboard responds with preview information, including the guide or survey ID.
4. The SDK receives the preview information and displays the preview.
This communication relies on the browser's `window.postMessage` API to pass messages between the dashboard and your application.
### Troubleshooting preview mode
Sometimes the guide or survey doesn't appear in preview. If the instrumentation is correct, check the following:
> **Tip:**
>
> On web, use the [Amplitude Chrome extension](https://amplitude.com/docs/data/chrome-extension-debug) to debug Guides & Surveys setup and troubleshoot why guides or surveys aren't showing. The extension's Guides & Surveys tab shows SDK setup status, trigger conditions, and lets you test event-based triggers. On mobile, use Preview mode and the Super Debugger instead. Go to [Mobile: preview doesn't open the app](#mobile-preview-doesnt-open-the-app) if the QR code or preview URL never launches your app.
- Confirm the preview user hasn't already seen the guide or survey. If the user has seen it, the preview bar shows a yellow (warning) status for the **Limit** condition. Hover over the condition and click **Reset User History**.
- Confirm the throttle limit isn't reached. If the limit is reached, the Throttle condition shows yellow (warning) status. Hover over the condition and toggle **Ignore Throttle Limits**.
- If the trigger condition is **On event tracked**, confirm the event fires. If the event hasn't fired, the Trigger condition shows blue status. Hover over the Trigger condition and click **Manually trigger event**.
#### No error message but preview doesn't appear
If the Amplitude dashboard shows no error but the preview doesn't appear:
- The dashboard received the initial message from your SDK.
- The SDK isn't receiving the response message from the dashboard.
To troubleshoot:
- Check your browser console for errors related to message passing.
- Verify that no browser extensions or security settings block cross-window messaging.
- Confirm the **Don't automatically close the preview window** option in the preview modal is enabled (default) to keep the window open for debugging.
#### Error message and preview doesn't appear
If the Amplitude dashboard displays an error after about 10 seconds, the dashboard didn't receive a message from the SDK. The cause is one of:
- The SDK isn't loading on your page.
- The SDK can't communicate with the dashboard.
To troubleshoot:
- Verify the SDK is installed correctly using `window.engagement` in your browser console.
- Confirm the **Don't automatically close the preview window** option is enabled (default) to extend the waiting time beyond 10 seconds.
- Confirm your application URL is correct and accessible.
#### Known issue: Cross-Origin-Opener-Policy header
If your application sets the `Cross-Origin-Opener-Policy` (COOP) header to `same-origin`, the COOP header prevents message passing between the Amplitude dashboard and your application, which blocks preview mode.
To resolve, either:
- Set the COOP header to `same-origin-allow-popups` instead of `same-origin`.
- Temporarily disable the COOP header for testing.
For more information about the COOP header, refer to the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy).
#### Mobile: preview doesn't open the app
The Chrome extension, `window.postMessage`, and COOP checks apply to web only. On mobile, Preview mode uses a QR code and a custom URL scheme.
- **iOS shows `No usable data found`**: the device has no app that handles the preview URL. The app isn't installed on that iOS device, or the installed build doesn't register the project's URL scheme. Install a build that includes the Guides and Surveys SDK and the URL scheme, then scan the QR code with that device's camera. Go to [iOS preview setup](https://amplitude.com/docs/sdks/guides-and-surveys/guides-and-surveys-ios-sdk#set-up-and-verify-preview-mode).
- **Android's action sheet lists no app**: the same cause. Nothing appears on the share or open-with sheet because the OS has no app registered for the preview URL. Install a build that includes the SDK and the intent filter for the URL scheme. Go to [Android preview setup](https://amplitude.com/docs/sdks/guides-and-surveys/guides-and-surveys-android-sdk#set-up-and-verify-preview-mode).
- The preview opens in a browser instead of the app: you didn't register the URL scheme, or the app doesn't forward the inbound link to `handleUrl` (iOS) or `handleLinkIntent` (Android).
If the app opens but the guide doesn't appear, tap the Amplitude logo at the bottom of the screen and use the Super Debugger **Details** tab to inspect trigger, limit, and throttle conditions.
> **Note:** Clear user history
>
> Amplitude keeps a record of the guides and surveys your users encounter. To remove a guide or survey from a user's history:
>
> 1. Open the user's profile in Amplitude.
> 2. Navigate to the Guides or Surveys tab.
> 3. Find the guide or survey to remove.
> 4. In the corresponding row, click the ellipsis menu and select **Clear history**.
## Testing status function
Preview mode approximates how your guide or survey appears to users. To test in a live environment, use the [**Testing** status](https://amplitude.com/docs/guides-and-surveys/setup-and-target#status) to test your guide or survey with specific users without affecting your broader audience.
When you set a guide or survey to Testing status:
- All specified test users (device IDs, user IDs, or cohorts) are eligible to see the guide or survey.
- Amplitude ignores global throttles (such as "Show max of 1 guide per day") but still enforces per-user limits like completion and dismissal history. To reset a test user's limit history, use **Clear history** on their profile.
- The guide or survey remains hidden from your production users.
> **Note:** Test users in production
>
> Test users continue to receive the guide or survey when you update its status to **Published** or **Scheduled**. This allows for smooth transitions from testing to production.
##### To use the Testing status:
1. Open your guide or survey.
2. In the **Test users** section, specify your test users using device IDs, user IDs, or cohorts.
3. Change status to **Testing**.
## Publishing
After you finish editing and testing your guide or survey, click **Publish** in the builder to release the guide or survey to your users. If your project requires a reviewer to sign off before publishing, see [Approval workflows](https://amplitude.com/docs/guides-and-surveys/approval-workflows).
After you publish a guide, you can still make changes. Amplitude saves the changes as "unpublished" until you click **Publish** to explicitly publish them.
The dashboard's preview pane and Preview mode both show your guide or survey, including any unpublished changes. Use [version history](#version-history) to see how many changes you made since you last published.
## Version history
Every save creates a version. Open **Version history** from the guide or survey editor to see each change, who made it, and when.
To revert to a previous version, click **Restore** on a version entry. Restore overlays the default-language fields of that version onto your draft. It doesn't publish, so review and publish when you're ready.
- Any user who can edit the guide or survey can restore a version. Users with view-only access don't see **Restore**.
- **Restore** isn't available when you're viewing a non-default locale, because it only overlays default-language fields. Switch to the default language to restore. For more information, refer to [Localization](https://amplitude.com/docs/guides-and-surveys/localization).
================================================================================
# Approval workflows
URL: https://amplitude.com/docs/guides-and-surveys/approval-workflows
================================================================================
# Approval workflows
Approvals adds an extra validation step before users can publish changes to a guide or survey, ensuring every change for your users has been reviewed. The typical flow: save your edits, request review (optionally notifying reviewers), continue making changes while the review is open, and once approved, click **Publish** to go live. A banner at the top of the guide or survey page shows the current approval status—pending, denied, or approved.
## Turn on approvals
Enabling approvals is a one-time admin action per project. Once turned on, all editors must request approval before publishing.
1. Go to _Settings > Projects_, select your project, then click **Guides & Surveys**.
2. Expand the **Approvals** card.
3. Turn on **Require approval**.
When Require approval is on, choose who can approve:
- **All project members**: Anyone in the project can approve, subject to self-approval rules.
- **Project managers and org admins**: Managers and org admins can approve. Org admins can always approve.
- **Specific users**: Add at least one approver.
Then set the Allow self-approval permission. When enabled, approvers can approve requests they submitted.
> **Note:** Org admins and self-approval
>
> Org admins can still approve their own requests when the Allow self-approval permission is off.
## Request approval
Save unpublished changes first.
1. Open the guide or survey in the builder.
2. Click **Request approval**.
3. Optionally select people to notify. You can submit without notifying anyone.
4. Click **Request approval**.
The live guide or survey stays as it is until someone publishes the approved draft. The builder shows a Pending approval banner while the request is open.
You can click **Cancel request** at any time, if you no longer need wish to publish the changes.
## Approve or deny a request
An approver opens the guide or survey and sees the Pending approval banner in the builder.
To approve:
1. Review the draft changes.
2. Click **Approve**.
Amplitude notifies the requester. Anyone with publish permission can then click **Publish** to make the approved draft live.
To deny:
1. Optionally add a comment explaining what needs to change.
2. Click **Deny**.
Amplitude notifies the requester and clears the pending request. The requester can revise the draft and submit a new approval request.
> **Note:** Approval doesn't publish automatically
>
> Approving a request doesn't publish the guide or survey. Someone with publish permission must click **Publish** after an approval for the draft to go live.
## Publish after approval
1. Confirm the builder shows the approved banner and that you have no unsaved changes.
2. Click **Publish**.
If you save more edits after an Approved approval, the approval will be cancelled, and you'll need to request a new approval.
Unpublishing doesn't require an approval. This way the guide or survey can always be quickly removed whenever needed.
For testing before you request approval, go to [Testing and Publishing](https://amplitude.com/docs/guides-and-surveys/testing).
================================================================================
# Throttling
URL: https://amplitude.com/docs/guides-and-surveys/throttling
================================================================================
# Throttling
Throttling limits how often Amplitude shows guides and surveys to the same user. Set a global cap on how many appear in a day, week, month, or session, add a delay between sequential guides, and layer per-tag advanced throttles for finer control.
Use throttling to slow message frequency over time. If you need to make sure a user sees only one message from a specific set (for example, a cross-app announcement), configure [mutual exclusivity](#mutual-exclusivity) instead.
Throttling works identically for guides and surveys, but the settings for each are separate. Separate settings give you more flexibility over how guides and surveys appear. To exclude specific pages from all guides and surveys, set [project-wide default page exclusions](https://amplitude.com/docs/guides-and-surveys/setup-and-target#project-wide-default-page-exclusions).
> **Tip:**
>
> Your throttling settings apply globally to all guides or surveys in the list. You can further specify how and when your guides or surveys appear by modifying the Limits section for each guide or survey.
## Built-in display limits
Amplitude has built-in limits that control how many guides and surveys display at the same time. These limits prevent users from seeing too many messages at once:
- **Tooltips**
- **Display Limit**: Unlimited
- **Behavior**: Multiple tooltips can display at the same time.
- **Pins, Popovers, Modals**
- **Display Limit**: One at a time
- **Behavior**: Only one pin, popover, or modal displays at a time. When one of these form factors is already showing and another triggers, the first continues to show and the second doesn't display.
- **Checklists**
- **Display Limit**: One at a time
- **Behavior**: When a checklist is already showing and another triggers, the first continues to show and the second doesn't display.
- **Banners**
- **Display Limit**: One at a time
- **Behavior**: When a banner is already showing and another triggers, the first continues to show and the second doesn't display.
> **Note:** Checklists can display with other form factors
>
> Checklists can display at the same time as pins, popovers, or modals. Priority doesn't affect this behavior. For example, when a high-priority modal is already showing and a low-priority checklist triggers, both display at the same time.
### Example scenarios
**Multiple checklists triggered:** When checklist B triggers while checklist A is already showing, checklist A continues to show and checklist B doesn't display.
**Pin and modal:** When a modal is showing and a pin triggers, the modal continues to show and the pin doesn't display. This rule applies to any combination of pins, popovers, and modals.
**Checklist and modal together:** When a modal is showing and a checklist triggers, both display at the same time, regardless of priority settings.
**Pin and tooltip together:** A pin can display while multiple tooltips are visible, because tooltips have no display limit.
### Set throttling for Guides or Surveys
1. Go to _Guides and Surveys_ and then select either _Guides_ or _Surveys_.
2. Click the **Settings** icon for the list of artifacts.
3. Turn throttling **On**.
4. Set the throttling. You can set:
- **Limit**: The number of guides or surveys that appear.
- **Period**: The rate of time in which the maximum limit of guides or surveys can appear. Time periods can be:
- Day
- Week
- Month
- Session
5. Click **Save Changes**.
## Time between guides
Control the delay between sequential guides for the same user. A delay prevents users from seeing multiple guides in quick succession.
### Set the time between sequential guides
1. Go to _Guides and Surveys_ and then select either _Guides_ or _Surveys_.
2. Click the **Settings** icon for the list of artifacts.
3. In the Time Between section, enter the delay period.
4. Select the time unit from the dropdown:
- Minute
- Hour
- Day
5. Click **Save Changes**.
> **Tip:**
>
> This setting applies to sequential guides for the same user. For example, a setting of "10 minutes" ensures that after a user sees one guide, they don't see another guide for at least 10 minutes.
## Advanced throttles
Advanced throttles set additional rate limits for guides or surveys grouped by tags. Tag-based throttles give you granular control over how different categories of content appear to users.
> **Tip:** Apply tags before you use advanced throttles
>
> Advanced throttling groups guides and surveys by [tags](https://amplitude.com/docs/guides-and-surveys/tags) to create rate limits for different types of guides. Tags aren't required, but Amplitude recommends adding them first for more precise control.
### Configure advanced throttles
1. Go to _Guides and Surveys_ and then select either _Guides_ or _Surveys_.
2. Click the **Settings** icon for the list of artifacts.
3. In the Advanced Throttles section, click **Add throttle**.
4. Configure your advanced throttle:
- **Limit**: The maximum number of guides/surveys for this tag group.
- **Tags**: Select one or more tags to group guides/surveys.
- **Period**: Choose the time period (Day/Week/Month/Session).
5. Click **Save Changes**.
### Advanced throttle examples
- **Campaign throttling**: Limit `product-launch` tagged guides to three (3) for each day.
- **Feature throttling**: Limit `onboarding` tagged content to five (5) for each session.
- **Team coordination**: Limit `growth-team` guides to two (2) for each week.
> **Tip:**
>
> Advanced throttles work alongside your global throttling settings. The most restrictive limit applies. For example, when global throttling allows 10 guides each day but an advanced throttle limits `onboarding` guides to two (2) each day, users receive at most two (2) onboarding guides each day.
### Multiple advanced throttles
Create multiple advanced throttles for different tag combinations to support detailed throttling strategies:
- **Urgent announcements**: `urgent` + `announcement` tags - 1 each day
- **Onboarding flow**: `onboarding` tag - 3 each session
- **Feature updates**: `feature-update` tag - 2 each week
## Mutual exclusivity
Mutual exclusivity groups guides and surveys so that each user sees only one item from the group. Use mutual exclusivity for multi-app announcements where users should see a message only once, regardless of which app they use.
### Multi-app use case
When you release a feature across multiple apps (web, iOS, and Android), announce the feature to users on whichever app they use first, without showing the same announcement again on other apps. Mutual exclusivity solves this by linking app-specific guides together.
For example, when you create:
- A web guide announcing a new feature.
- An iOS guide with the same announcement.
- An Android guide with the same announcement.
Add all three guides to a mutual exclusivity group. After a user sees the web guide, they don't see the iOS or Android versions later, even if they switch apps.
### Prevent popup fatigue
Mutual exclusivity also helps prevent popup fatigue for users who qualify for multiple similar guides. When you have several guides targeting overlapping audiences, group them so users see only the most relevant one.
### Create a mutual exclusivity group
1. Go to _Guides and Surveys_ and then select either _Guides_ or _Surveys_.
2. Click the **Settings** icon for the list of artifacts.
3. Expand the **Mutual exclusivity** section.
4. Click **Add group** to create a new mutual exclusivity group.
5. Give the group a name (for example, "Feature X Announcement").
6. Select the guides or surveys to include in the group.
7. Click **Save Changes**.
> **Note:**
>
> Mutual exclusivity works across apps. After a user sees any guide or survey from the group on one app, they don't see other items from that group on any app.
### Mutual exclusivity and throttling
Mutual exclusivity and throttling serve different purposes but work together:
- **Throttling** limits how many guides or surveys a user sees over time.
- **Mutual exclusivity** ensures a user sees only one item from a specific group.
Apply both settings to the same guide. For example, a guide can belong to a mutual exclusivity group and also follow global throttling limits.
================================================================================
# Tags
URL: https://amplitude.com/docs/guides-and-surveys/tags
================================================================================
# Tags
Tags are custom labels that help you organize, search, and coordinate guides and surveys across teams.
## Key benefits
- **Better organization**: Group related guides and surveys together.
- **Improved searchability**: Find specific content using tag filters.
- **Team coordination**: Help teams manage their guides and surveys.
- **Bulk management**: Apply changes to multiple guides or surveys at once.
- **Event tracking**: Tags are automatically included as a property on all guide and survey events.
## Adding tags
##### Add tags to an individual guide or survey
1. In the guide or survey editor, click the Tags control under the title.
2. Select an existing tag, or enter a new one.
##### Add existing tags to multiple guides or surveys
1. From the list view, select the guides or surveys to which you want to apply a tag.
2. Click **Assign Tags** in the table header.
3. Select the tags you want to apply.
### Tag naming best practices
- Use descriptive, consistent names (for example, `onboarding`, `feature-announcement`, `user-feedback`)
- Keep tags concise but meaningful
- Use lowercase with hyphens for multi-word tags
- Establish naming conventions across your team
### Renaming tags and editing description
To rename a tag or update its description:
1. Go to the guides list view or surveys list view.
2. Enable the Tags column in table settings.
3. Hover over a cell in the Tags column and click edit.
4. Click the edit icon and update the name, description, or both.
5. Save.
The tag updates across all guides and surveys where it's used.
### Tag best practices for organization
Define a tag system that fits your team. For example:
- **Campaign tags**: Use tags like `spring-campaign`, `product-launch` for time-bound initiatives.
- **Feature tags**: Tag content related to specific features (for example, `analytics`, `billing`, `onboarding`).
- **Team tags**: Identify ownership with tags like `growth-team`, `product-team`.
## Searching and filtering by tags
1. Go to the Guides or Surveys list view.
2. Make sure the Tags column is visible.
3. Click **Add Filter** and select **Tags**.
4. Choose one or more tags from the available options.
The list updates to show only guides with the selected tags.
### Advanced filtering
Combine tag filters with other filters. For example, apply a team tag and a feature tag together to narrow results to a specific guide.
## Bulk operations with tags
From the guides list view or surveys list view, you can select multiple rows and bulk-apply tag updates.
## Tags and throttling
Tags drive [advanced throttling](https://amplitude.com/docs/guides-and-surveys/throttling#advanced-throttles). Use tags to define rate-limiting strategies for different categories of guides and surveys.
### Throttling use cases with tags
- **Campaign management**: Use campaign tags like `spring-launch` to limit promotional guides.
- **User journey stages**: Use tags like `onboarding`, `activation`, `retention` to control flow progression.
- **Content priority**: Use priority tags like `critical`, `important`, `optional` with different throttle limits.
> **Tip:**
>
> Plan your tag strategy with throttling in mind. Consistent, meaningful tags make advanced throttling more effective and easier to manage.
For detailed setup instructions, refer to [Advanced Throttles](https://amplitude.com/docs/guides-and-surveys/throttling#advanced-throttles).
================================================================================
# Notifications
URL: https://amplitude.com/docs/guides-and-surveys/notifications
================================================================================
# Notifications
Set up notification alerts for your surveys in Guides and Surveys. When someone submits a survey response, Amplitude can send a notification to a Slack channel, email, or a webhook so your team stays informed in real time.
This page covers creating and managing notification alerts through the Guides and Surveys project settings. To connect your Slack workspace to Amplitude, refer to [Integrate Slack](https://amplitude.com/docs/analytics/integrate-slack).
For Microsoft Teams, send notifications to a [Teams webhook](https://support.microsoft.com/en-us/office/create-incoming-webhooks-with-workflows-for-microsoft-teams-8ae491c7-0394-4861-ba59-055e33f75498). For Google Chat, send notifications through a [webhook](https://docs.cloud.google.com/workflows/docs/notify-google-chat).
> **Note:** Guides and Surveys permissions\*
>
> You must have Guides and Surveys project settings permissions to create, edit, or delete notification alerts. To receive notifications, you only need to be a member of the Slack channel, on the email list, or the webhook endpoint. Contact your Admin if you need different permissions.
## Connect a Slack workspace
Connect your Slack workspace to Amplitude before you send alerts to a Slack channel.
##### To connect a Slack workspace to your survey notifications
1. Go to _Settings > Projects_, select your project, then click **Guides & Surveys**.
2. Expand the **Alerts** card.
3. Click **Connect To Slack**.
4. Click **Allow** to confirm that you want to connect Amplitude to Slack.
> **Note:**
>
> If a Slack channel ID appears instead of the channel name, confirm that Amplitude is connected to your Slack workspace. If the workspace is connected, confirm that you are a member of the Slack channel. Contact the person who created the alert to add you to the channel.
## What triggers an alert
You receive an alert when a customer submits a response to any active survey that matches the alert's scope.
## Set up an alert
Create an alert to send notifications to Slack, email, or a webhook when someone submits a survey response.
##### To set up an alert
1. Go to _Settings > Projects_, select your project, then click **Guides & Surveys**. You can also click the bell icon on the _Guides & Surveys_ list page and choose **Add Alert**.
2. Expand the **Alerts** card and click **Add Alert**.
3. Set the scope. Select one of:
- **All in Project**: Receive notifications for all survey responses in the project.
- **By Tag**: Receive notifications only for surveys with a specific tag.
- **By Survey**: Receive notifications for a single survey.
4. Choose how you want to receive your notifications:
- For Slack, click the dropdown to choose the channel for your alerts.
- For email, enter the email addresses you want to receive notifications.
- For a webhook, enter the URL and your signing key.
5. Name your alert.
6. Click **Create Alert**.
================================================================================
# Duplicating Across Projects and Platforms
URL: https://amplitude.com/docs/guides-and-surveys/duplicating-guides-and-surveys-across-projects
================================================================================
# Duplicating Across Projects and Platforms
Your organization may have multiple projects for different reasons. For example, you may use separate projects to differentiate between environments (such as staging and production) or between geolocations. Duplicating a guide, survey, or theme across projects or platforms saves you from recreating the same content for each environment or app, which saves time and encourages consistency.
> **Note:** Duplication in Experiments
>
> You can't duplicate a guide or survey across your projects if it's part of an experiment. If you want the same guide or survey in experiments in multiple projects, you must manually recreate it.
When you duplicate a guide, survey, or theme to a new project, the new project treats the duplicated content as a new entity. Amplitude doesn't copy previous analytics to the new project. To move a guide, survey, or theme from one project to another, copy it to the destination project, then archive it from the originating project.
## Duplicate across projects
### Duplicate a guide or survey across projects
1. Navigate to _Guides and Surveys > Guides_ or _Guides and Surveys > Surveys_.
2. Click the **three-dot** menu for the guide or survey you want to duplicate.
3. Click **Duplicate across projects**.
4. Click the **Destination** dropdown and select the target project or projects.
5. Select which of the following elements to duplicate:
- Targeting setup
- Trigger setup
- Limits setup
- Theme
- Translations
6. Click **Duplicate**.
### Duplicate a theme across projects
1. Navigate to _Guides and Surveys > Themes_.
2. Click the **three-dot** menu for the theme you want to duplicate.
3. Click **Duplicate across projects**.
4. Click the **Destination** dropdown and select the target project or projects.
5. Click **Duplicate**.
### Re-duplicate a guide, survey, or theme
If you duplicate a guide, survey, or theme to a project that already contains the duplicated content, Amplitude overwrites the content in the target project.
For example, you create a guide (Guide-1) in Project A and duplicate it to Project B. You then make changes to Guide-1 in Project A and want to re-duplicate it to Project B. Amplitude overwrites the original Guide-1 in Project B with the newest version. Amplitude doesn't keep both versions of Guide-1.
When you select the target project, Amplitude applies a badge to show whether the content you're duplicating is new for that project or already exists there. Click into the **Preview changes** section for more information.
## Duplicate across platforms
When you want the same guide or survey on multiple apps (for example, web, iOS, and Android), duplicate it to another platform instead of rebuilding it. When you select **Duplicate** and have multiple platforms configured, Amplitude shows a platform selection modal.
### Duplicate a guide or survey across platforms
1. Navigate to _Guides and Surveys > Guides_ or _Guides and Surveys > Surveys_.
2. Click the **three-dot** menu for the guide or survey you want to duplicate.
3. Click **Duplicate**.
4. In the platform selection modal, select the destination platform or platforms.
5. Click **Duplicate**.
> **Note:**
>
> The platform selection modal only appears if you have multiple platforms configured. If you have a single platform, Amplitude duplicates the guide or survey without a platform selection step.
================================================================================
# Themes
URL: https://amplitude.com/docs/guides-and-surveys/themes
================================================================================
# Themes
Guides and Surveys should match your branding and feel like part of your product. Themes give you control over the appearance of your guides and surveys.
Themes ensure that every in-product message matches your colors, typography, and aesthetic. A subtle guide or a full-page survey should look and feel like an extension of your product, not a random popup.
You control how users view guides and surveys, from buttons to borders and animations to background colors.
> **Note:** Themes differ by platform
>
> Guides and surveys on web and mobile have different themes. Themes aren't compatible across platforms.
## Create a new theme
To create a new Guides and Surveys theme:
1. In Amplitude, go to _Guides and Surveys > Theme_.
2. Click **Create Theme**. The Theme editor appears.
3. Customize your theme with the [Brand](#brand-controls) and [Component](#component-editor) controls.
4. Click **Save** at any time to save your progress.
5. Click **Publish** to enable your theme for selection by a guide or survey.
> **Note:** Updating a theme
>
> When you publish an update to an existing theme, the updates apply to any guide or survey that uses that theme.
> **Tip:** Customize a specific guide or survey
>
> To customize the theme for a single guide or survey without affecting others, use the **Customize only this guide** or **Customize only this survey** option in the guide or survey editor. This option creates a unique theme version for that specific experience, so you can make one-off customizations without changing the base theme.
## Create a theme with Global Agent
Amplitude's [Global Agent](https://amplitude.com/docs/amplitude-ai/global-agent-overview) can generate a Guides and Surveys theme from a natural-language description, a reference image, or both. The result is a fully editable theme you can refine in the theme editor.
Global Agent generates both brand-level and component-level theme settings, including colors, typography, spacing, button styles, form controls, cards, widget dimensions, and component-level overrides. You can adjust any generated setting in the theme editor after creation.
> **Note:** Availability
>
> This feature isn't available in the EU data center.
### Generate a theme
1. Open Global Agent from anywhere in the Amplitude dashboard, or click **Create Theme** on the _Guides and Surveys > Theme_ page.
2. Describe the theme you want. For example: "Use our marketing site palette: navy primary, coral accent, rounded corners on buttons and inputs." You can also attach a screenshot or Figma export as a visual reference.
3. Global Agent generates the theme and returns a link to it. Click the link to open the theme in the theme editor.
4. Review the generated settings. Adjust any brand or component values, then click **Publish** to make the theme available.
> **Tip:** Tips for better results
>
> Include specific details in your description — brand colors (hex values), corner radius preferences, font names, and spacing guidelines produce more accurate themes. Attaching a screenshot of your product or a Figma mockup helps Global Agent match your visual style.
### What Global Agent doesn't generate
Global Agent doesn't generate animations or custom CSS. Configure animations in the [theme editor](#animations) and add custom CSS through [Custom CSS](https://amplitude.com/docs/guides-and-surveys/custom-css).
## Manage themes
The _Guides and Surveys > Theme_ page lists every theme in your project. Filter the list with the tabs at the top of the page to manage a large set of themes:
- **Active**: themes that a guide or survey uses.
- **Inactive**: themes that no guide or survey uses.
- **Archived**: themes you've archived.
- **All**: every theme, regardless of status.
To find a specific theme, use the **Search themes** box.
### Archive a theme
Archive a theme you no longer need to remove it from your **Active** and **Inactive** lists. Archiving doesn't change the guides or surveys that already use the theme.
1. In Amplitude, go to _Guides and Surveys > Theme_.
2. Find the theme you want to archive.
3. Open the theme's context menu, then select **Archive**.
### Restore a theme
Themes work the same as guides and surveys: archiving a theme isn't permanent, so you can restore it later. Restore an archived theme to make it available to guides and surveys again.
1. In Amplitude, go to _Guides and Surveys > Theme_.
2. Select the **Archived** or **All** tab.
3. Open the archived theme's context menu, then select **Restore**.
## Theme viewer
The Theme Viewer shows how the theme appears when applied to a guide or survey. When editing a theme, choose the specific guide or survey you want to preview to see how changes affect your real-world content.
Theme previews look different depending on where you preview them. When you build a guide or survey, theme previews show the published version. When editing themes, previews display draft changes and let you choose a guide or survey to preview against. This behavior helps ensure consistency between what you see when building guides and what your users experience in your product.
At the top of the viewer, toggle between the [brand](#brand-controls) and [component](#component-editor) editors, toggle between light and dark mode, and cancel, save, or publish your changes.
## Brand controls
Use the Theme Editor to customize elements of your brand and style.
> **Tip:** CSS properties
>
>  Configure your branding using the same values you defined in your site's CSS. For example, specify font size in px, em, rem, or percent values.
### Accent
Accent represents your brand's primary color. This color appears on primary buttons and selected options.
In this example, the primary color is `#48705C`.
### Typography
Set the default typeface of your theme. Choose from the [Google font library](https://fonts.google.com/), or specify a custom typeface you've already defined on your site.
To use a font natively in your mobile Guides and Surveys, include the full font family in your app project and use a consistent file name for the font.
#### Android
- Place font files in the `/res/font` directory of your project.
- Use a clear and consistent naming convention:
- `[fontNameWithoutSpaces]_[style].[fileExtension]`
- For example: `adventpro_italic.ttf`
- Supported formats: **TTF**, **TTC**, **OTF**, and **XML**.
- After you add the font, you can reference it directly in your theme setup.
For more information, go to Android's [Font resources](https://developer.android.com/guide/topics/resources/font-resource).
#### iOS
- Add font files to your Xcode project.
- Use a clear and consistent naming convention:
- `[FontName]-[Style].[fileExtension]`
- For example: `Lora-Italic.ttf`
- Register the fonts in your app's `.plist` file.
- Alternatively, register fonts programmatically with Core Text using [`CTFontManagerRegisterFontsForURL`](https://developer.apple.com/documentation/coretext/ctfontmanagerregisterfontsforurl(_:_:_:)). In your theme setup, use the font's PostScript name (for example, `Lora-Italic`).
- Supported formats: **TTF**, **OTF**.
For more information, go to Apple's [Adding a custom font to your app](https://developer.apple.com/documentation/uikit/adding-a-custom-font-to-your-app).
> **Note:** Font previews
>
> Custom fonts that aren't part of Google Fonts don't appear in the theme preview.
### Content
Define the supplementary colors that complete your brand's palette.
- Primary color
- Secondary color
- Disabled color
- Link color
- Link hover color
- Link visited color
- Highlight color
### Border
Specify the color of element borders in each of the following states:
- Primary color
- Primary hover color
- Disabled color
### Background
Update the background color of elements in the specified state.
Set each of the following background variants:
- Primary color
- Primary hover color
- Secondary color
- Secondary hover color
- Disabled color
### Form controls
Customize the appearance of the interactive elements in your guides or surveys.
Adjust the following, which apply to all form elements:
- Height
- Corner radius
- Padding
- Gaps
- Shadow
- Shadow color
- Background
- Active background
- Focus ring color
- Focus ring width
### Cards
Specify how individual cards display on screen. Adjust the following settings, which apply to all cards:
- Corner radius
- Padding
- Gaps
- Shadow
- Shadow color
### Widget dimensions
Specify the maximum dimensions for each type of widget.
| Widget | Available dimension |
| --- | --- |
| Modal | Max content width for modals and mobile carousels on tablets |
| Popover / pin | Max content width for pins |
| Tooltip | Max width for tooltips |
| Checklist | Max width and max height for checklists |
### Animations
Select the animation that each widget type uses to appear on screen, along with duration (in milliseconds) where applicable.
## Component editor
Components are reusable elements that you use across your guides and surveys. With components, you specify the contents one time, then apply them anywhere in the theme.
Each component includes states, such as default, hover, or focus, that you can customize.
## Theme component usage
Theme components appear throughout guides and surveys. This section describes where each component type appears in the application.
### Buttons
Buttons appear in the following locations:
- **Primary buttons**: The main call-to-action (CTA) buttons in guides and surveys. These buttons use the accent color you define in your theme.
- **Secondary buttons**: Alternative actions or less prominent CTAs. These buttons use the secondary color settings.
- **Button states**: All buttons support default, hover, active, and disabled states that you can customize in the component editor.
Buttons appear in:
- Guide steps with action buttons
- Survey submission buttons
- Modal dialogs
- Banner actions
- Form submissions
### Cards
Cards group and display content in guides and surveys. Card styling applies to:
- Guide step containers
- Survey question containers
- Content blocks within guides
- Information panels
- Result displays in surveys
Card properties (corner radius, padding, gaps, shadow) apply uniformly to all card elements in your guides and surveys.
### Form controls
Form controls are interactive elements in surveys and forms. These controls appear in:
- **Text inputs**: Short and long text input fields for survey responses.
- **Select dropdowns**: Dropdown menus for selecting from multiple options.
- **Checkboxes**: Multiple choice options where users can select more than one answer.
- **Radio buttons**: Single choice options where users can select only one answer.
- **Rating components**: Star ratings, emoji ratings, and numeric ratings for feedback.
- **List elements**: Ordered and unordered lists in survey questions.
All form controls share the same styling properties (height, corner radius, padding, gaps, shadow, focus ring) that you configure in the Form controls section.
### Widgets
Widgets are container elements that display guides and surveys. Each widget type has specific dimension settings:
- **Modals**: Full-screen or centered dialog boxes that appear over your application. Used for multi-step guides, surveys, and important announcements.
- **Popovers / Pins**: Small, contextual elements that appear near specific UI elements. Used for tooltips, hints, and inline guidance.
- **Tooltips**: Small informational boxes that appear when users hover over or interact with elements. Used for contextual help and explanations.
- **Checklists**: Interactive lists that users can check off as they complete tasks. Used for onboarding flows and task completion guides.
### Borders
Border colors apply to:
- Form control outlines
- Card edges
- Button borders
- Input field borders
- Separator lines between content sections
Border colors support primary, primary hover, and disabled states that you can customize.
### Backgrounds
Background colors apply to:
- Card backgrounds
- Form control backgrounds
- Button backgrounds (primary, secondary, and their hover states)
- Disabled element backgrounds
- Widget container backgrounds
Background settings support primary, primary hover, secondary, secondary hover, and disabled states.
### Typography
Typography settings apply to all text elements in guides and surveys, including:
- Guide step titles and descriptions
- Survey questions and instructions
- Button labels
- Form control labels
- Card content text
- Widget headers and body text
The typography you set becomes the default font for all text in guides and surveys that use your theme.
### Animations
Animations control how widgets appear on screen. Each widget type can have its own animation:
- **Modal animations**: Control how modals enter and exit the screen.
- **Popover / Pin animations**: Control how contextual elements appear.
- **Tooltip animations**: Control how tooltips fade in and out.
- **Checklist animations**: Control how checklist items appear.
Animation duration settings (in milliseconds) control the speed of these transitions.
### Content colors
Content colors apply to text and link elements:
- **Primary color**: Used for main text content.
- **Secondary color**: Used for secondary text and labels.
- **Disabled color**: Used for disabled text and inactive elements.
- **Link color**: Used for clickable links in guide and survey content.
- **Link hover color**: Used when users hover over links.
- **Link visited color**: Used for links that users have already clicked.
- **Highlight color**: Used to emphasize important text or selections.
## Advanced customization with Custom CSS
[Custom CSS](https://amplitude.com/docs/guides-and-surveys/custom-css) gives you control over specific elements using CSS class selectors for styling beyond what themes provide. Custom CSS is available for web SDKs only.
Amplitude recommends using themes for most styling. Use Custom CSS when themes don't provide the control you need.
================================================================================
# Custom CSS
URL: https://amplitude.com/docs/guides-and-surveys/custom-css
================================================================================
# Custom CSS
Amplitude provides two options for customizing the appearance of your guides and surveys. [Themes](https://amplitude.com/docs/guides-and-surveys/themes) control the overall appearance of your guides and surveys. Custom CSS offers fine-grained control for specific styling needs that themes can't address. Amplitude recommends using themes for most customizations, because themes offer better flexibility and backward compatibility.
> **Note:** Web SDK only
>
> Custom CSS is available for the web SDK. Mobile SDKs (iOS, Android, React Native) don't support custom CSS.
## How custom CSS works
The Guides and Surveys SDK adds CSS classes to form factor elements so you can target the elements with CSS. These selectors:
- Provide stable targets for custom styling
- Focus on container and parent elements
- Work alongside existing theme settings
## Class selectors
Use CSS class selectors to target Guides and Surveys elements:
```css
/* Target banner container */
.amplitude-engagement-banner-container {
background-color: #f0f0f0;
}
/* Target modal overlay */
[data-amplitude-engagement-modal-overlay] {
background-color: rgba(0, 0, 0, 0.8);
}
```
### Form factor containers
| Form Factor | Selector |
| --- | --- |
| Banner | `.amplitude-engagement-banner-container` |
| Card | `.amplitude-engagement-card-container` |
| Modal | `.amplitude-engagement-modal-container` |
| Modal overlay | `[data-amplitude-engagement-modal-overlay]` |
| Popover | `.amplitude-engagement-popover-container` |
| Tooltip | `.amplitude-engagement-tooltip-content` |
| Pin | `.amplitude-engagement-pin` |
| Checklist | `.amplitude-engagement-checklist` |
### Common elements
| Element | Selector |
| --- | --- |
| Close button | `.amplitude-engagement-close` |
| Image | `.amplitude-engagement-image` |
| Video | `.amplitude-engagement-video` |
| Title | `.amplitude-engagement-title` |
| Content | `.amplitude-engagement-content` |
| Beacon | `.amplitude-engagement-beacon` |
### Banner-specific elements
| Element | Selector |
| --- | --- |
| Banner body | `.amplitude-engagement-banner-body` |
| Banner title | `.amplitude-engagement-banner-title` |
| Banner content | `.amplitude-engagement-banner-content` |
| Banner actions | `.amplitude-engagement-banner-actions` |
| Banner close button | `.amplitude-engagement-banner-close-button` |
### Tooltip-specific elements
| Element | Selector |
| --- | --- |
| Tooltip content | `.amplitude-engagement-tooltip-content` |
| Tooltip marker | `.amplitude-engagement-tooltip-marker` |
| Tooltip marker (image) | `.amplitude-engagement-tooltip-marker__image` |
| Tooltip marker (icon) | `.amplitude-engagement-tooltip-marker__icon` |
| Tooltip marker (beacon) | `.amplitude-engagement-tooltip-marker__beacon` |
> **Note:**
>
> When a tooltip uses the **Element is marker** setting (web only), Amplitude doesn't render a separate marker element, so the tooltip marker selectors in the table above don't match any elements. Go to [Tooltip](https://amplitude.com/docs/guides-and-surveys/form-factors#tooltip) in the form factors guide for details.
### Pin-specific elements
| Element | Selector |
| --- | --- |
| Pin | `.amplitude-engagement-pin` |
| Pin beacon | `.amplitude-engagement-pin-beacon` |
| Pin content | `.amplitude-engagement-pin-content` |
| Pin arrow | `.amplitude-engagement-pin-arrow` |
| Pin mask | `.amplitude-engagement-pin-mask` |
### Checklist-specific elements
| Element | Selector |
| --- | --- |
| Checklist | `.amplitude-engagement-checklist` |
| Checklist header | `.amplitude-engagement-checklist-header` |
| Checklist title | `.amplitude-engagement-checklist-title` |
| Checklist subtitle | `.amplitude-engagement-checklist-subtitle` |
| Checklist progress | `.amplitude-engagement-checklist-progress` |
| Checklist close button | `.amplitude-engagement-checklist-close-button` |
| Checklist item header (expanded) | `.amplitude-engagement-checklist-item-header__expanded` |
| Checklist item header (collapsed) | `.amplitude-engagement-checklist-item-header__collapsed` |
| Checklist item body | `.amplitude-engagement-checklist-item-body` |
| Checklist item content | `.amplitude-engagement-checklist-item-content` |
| Checklist item buttons | `.amplitude-engagement-checklist-item-buttons` |
| Checklist item button (primary) | `.amplitude-engagement-checklist-item-button__primary` |
| Checklist item button (secondary) | `.amplitude-engagement-checklist-item-button__secondary` |
### Card-specific elements
| Element | Selector |
| --- | --- |
| Card | `.amplitude-engagement-card` |
| Card content | `.amplitude-engagement-card-content` |
### Modal-specific elements
| Element | Selector |
| --- | --- |
| Modal body | `.amplitude-engagement-modal-body` |
### Actions bar elements
Use these selectors to target the action bar area of nudge footers. Each layout applies a base class and a layout-specific variant class, so you can style all layouts together or target a specific layout.
| Element | Selector |
| --- | --- |
| Actions bar container | `.amplitude-engagement-actions-bar-container` |
| Actions bar | `.amplitude-engagement-actions-bar` |
| Classic and split layout variants | `.actions-bar-layout-classic` |
| Stacked layout variant | `.actions-bar-layout-stacked` |
| Centered layout variant | `.actions-bar-layout-centered` |
For example, to add a border above CTAs in all nudge footer layouts, or to style only a specific layout:
```css
/* Add a border above CTAs in all guide/survey footer layouts */
.amplitude-engagement-actions-bar-container {
border-top: 1px solid #000000;
}
/* Style only Classic and Split layout footers */
.amplitude-engagement-actions-bar.actions-bar-layout-classic {
padding-top: 12px;
}
```
### Buttons and actions
| Element | Selector |
| --- | --- |
| CTA button | `.amplitude-engagement-cta-button` |
| CTA button (primary) | `.amplitude-engagement-cta-button__primary` |
| CTA button (secondary) | `.amplitude-engagement-cta-button__secondary` |
| Banner actions | `.amplitude-engagement-banner-actions` |
### Form elements (Survey elements)
| Element | Selector |
| --- | --- |
| Survey prompt | `.amplitude-engagement-survey-prompt` |
| List | `.amplitude-engagement-list` |
| List dropdown | `.amplitude-engagement-list-dropdown` |
| Rating | `.amplitude-engagement-rating` |
| Rating (emojis) | `.amplitude-engagement-rating__emojis` |
| Rating (numbers) | `.amplitude-engagement-rating__numbers` |
| Rating (stars) | `.amplitude-engagement-rating__stars` |
| Rating label | `.amplitude-engagement-rating-label` |
| Rating label (start) | `.amplitude-engagement-rating-label-start` |
| Rating label (end) | `.amplitude-engagement-rating-label-end` |
| Text input | `.amplitude-engagement-text-input` |
| Short text input | `.amplitude-engagement-short-text-input` |
| Input | `.amplitude-engagement-input` |
| Select | `.amplitude-engagement-select` |
| Select input | `.amplitude-engagement-select-input` |
| Checkbox option | `.amplitude-engagement-checkbox-option` |
| Radio option | `.amplitude-engagement-radio-option` |
The `.amplitude-engagement-survey-prompt` selector targets question prompt labels across rating, text, list, and dropdown survey blocks. The `.amplitude-engagement-rating-label-start` and `.amplitude-engagement-rating-label-end` selectors target the two scale-endpoint labels inside `.amplitude-engagement-rating-label`.
## Using class selectors
### Basic styling
```css
/* Style banner background */
.amplitude-engagement-banner-container {
background: linear-gradient(to right, #667eea, #764ba2);
}
/* Customize CTA button appearance */
.amplitude-engagement-cta-button {
border-radius: 8px;
text-transform: uppercase;
}
/* Style close button hover state */
.amplitude-engagement-close:hover {
opacity: 0.7;
}
```
### Target specific form factors
```css
/* Style banners with custom background */
.amplitude-engagement-banner-container {
background: linear-gradient(to right, #667eea, #764ba2);
}
/* Style primary CTA buttons in banners */
.amplitude-engagement-banner-container
.amplitude-engagement-cta-button__primary {
width: 100%;
}
/* Style checklist progress bars */
.amplitude-engagement-checklist-progress {
background-color: #f5f5f5;
}
```
## Important considerations
Note the following considerations when you implement custom CSS.
### Specificity
You may need to use `!important` to override default styles:
```css
.amplitude-engagement-banner-container {
background-color: #custom-color !important;
}
```
### Selector stability
Target the documented CSS classes rather than:
- Internal generated class names
- Element structure that may change
- Undocumented classes or attributes
================================================================================
# Personalize with Variables
URL: https://amplitude.com/docs/guides-and-surveys/personalize-with-variables
================================================================================
# Personalize with Variables
The Personalize with variables feature (also called interpolation) dynamically displays user properties to customize content in a guide or survey. Use this feature to customize content for each user, such as displaying their first name or `user_id`. You can add personalized variables to:
- Titles
- Content
- Button labels
- Button Action URLs
## Common examples
### Replacing parts of a URL
Use user property variables in CTA links to personalize URLs. For example, create a link like:
```plaintext
www.example.com/path?user_id=@{{property.user_id}}&country=@{{property.country}}
```
When a user clicks the CTA link, Amplitude replaces the user property variables with actual values:
```plaintext
www.example.com/path?user_id=12345&country=US
```
### Personalizing guides with a user's name
Create a user property that holds the user's first name, such as `firstName`. Place the `firstName` property in any guide or survey field where you want to address users by name.
## Providing fallback values
A user property isn't always available for every user or every session. Use a fallback value to display a default when the property is missing. For example, to display "Hey there" instead of "Hey {firstName}" when a user hasn't provided their name, use a fallback like `{{property.firstName | there}}`.
## User property requirements
Send user properties from the client during the active session, using either the Amplitude SDK or the Engagement SDK. Properties sent in prior sessions, and properties stored only on the server, aren't supported.
To set user properties, use the [`_setUserProperties`](https://amplitude.com/docs/sdks/guides-and-surveys/sdk#set-user-properties) method in the Engagement SDK, or `amplitude.identify()` in the Amplitude SDK.
> **Tip:**
>
> Amplitude autopopulates `user_id` and `device_id` for you. These variables are always available without additional setup.
> **Tip:** User properties in conditional logic
>
> User properties can also power [conditional logic](https://amplitude.com/docs/guides-and-surveys/conditional-logic). Use conditional logic to create different button actions or survey paths based on user characteristics. For example, direct premium users to different content than free users.
##### Add personalized variables to a guide or survey
1. Open an existing guide or survey, or create a new one.
2. Select the title, content block, button name, or other text field. The personalize variable icon appears on the right of the selected field.
3. Select the [user property](https://amplitude.com/docs/sdks/guides-and-surveys/sdk#set-user-properties) icon.
4. In the popup, enter the user property name.
5. (_Optional_) Enter a fallback value for the user property.
6. Select **Insert**.
7. Repeat for every field where you want to add property variables.
================================================================================
# Conditional Logic
URL: https://amplitude.com/docs/guides-and-surveys/conditional-logic
================================================================================
# Conditional Logic
Conditional logic creates dynamic, personalized experiences that adapt based on user properties and survey responses. Use conditional logic to branch survey paths, trigger different actions, or show different content to different users.
## Where you can use conditional logic
Conditional logic works with both guides and surveys. You can select it as an action for either primary or secondary buttons.
## Types of conditions
Create conditions based on two types of data:
### User properties
User properties are attributes about your users, such as location, subscription tier, or account type. User properties must be shared client-side during the session with either the Amplitude SDK or the Engagement SDK.
Common user property examples:
- `subscription_tier`
- `country`
- `account_type`
- `initial_referring_domain`
> **Note:** User property requirements
>
> Properties must be available client-side during the current session. Properties shared from prior sessions or properties stored only on the server aren't supported. Go to [Set user properties](https://amplitude.com/docs/sdks/guides-and-surveys/sdk#set-user-properties) for implementation details.
### Survey responses
Survey responses are the answers users provide to questions in your surveys. Use survey responses to branch your survey based on how users answer. Conditions can reference responses from any prior step in the survey, not just the current one. This lets you build multi-layered branching logic that considers the full context of a user's answers.
Survey response examples:
- NPS ratings
- Star ratings
- Single-select list selections
- Text input values
> **Note:** Multi-select list inputs aren't supported
>
> Conditional logic on multi-select list inputs isn't supported within the same step or in later steps. In the survey builder, multi-select list questions appear in the _Survey Responses_ dropdown but are disabled. A tooltip explains the limitation. Use a single-select list if you need to branch on the answer. Multi-select conditional logic support is a longer-term follow-up.
### Combining conditions
Combine multiple conditions to create more advanced logic. When you add multiple conditions, all conditions must be met for the action to execute.
For example: if `subscription_tier = premium` AND `country = US`, then visit link to premium US-specific content.
## Set up conditional logic
The setup process is similar whether you add conditional logic to buttons or to survey steps.
### Add conditional logic to buttons
1. In your guide or survey, add a primary or secondary button.
2. Click the **On button click** dropdown.
3. Select **Evaluate conditional logic**.
4. Navigate to the Conditional Logic section.
5. Under **When**, select either **User Property** or **Survey Response** from the dropdown.
6. Configure your condition:
- For **User Property**: Select the property, operator, and value.
- For **Survey Response**: Select the question, operator, and value. Multi-select list questions aren't supported; use a single-select list if you need to branch on the answer.
7. (_Optional_) Click **Add condition** to add more conditions.
8. Under **Do this**, select the action to execute when the condition is met.
9. Configure the action based on your selection.
> **Tip:** Multiple conditional actions
>
> Add multiple conditional actions to handle different scenarios. For example, one action for premium users and another for free users. Amplitude evaluates conditions in order and executes the first matching action.
## Examples and use cases
### Branch survey based on NPS score
Create a survey that asks different follow-up questions based on a user's NPS score:
1. Add an NPS rating block asking "How likely are you to recommend us?"
2. Add conditional logic:
- If `rating ≤ 6` (Detractors), then go to step asking "What can we improve?"
- If `rating ≥ 9` (Promoters), then go to step saying "Thank you! Would you leave us a review?"
### Redirect users based on subscription tier
Create a guide with a button that directs users to different pages based on their subscription level:
1. Add a primary button labeled "View Features".
2. Select **Evaluate conditional logic**.
3. Add conditions:
- If `subscription_tier = premium`, then visit link `www.example.com/premium-features`.
- If `subscription_tier = free`, then visit link `www.example.com/upgrade`.
### Show guide only to specific user segments
Launch a secondary guide based on both user property and survey response:
1. Add a primary button labeled "Next".
2. Select **Evaluate conditional logic**.
3. Add conditions:
- If `country = US` AND `rating > 8`, then show guide "US-specific-offer".
- If `country ≠ US` AND `rating > 8`, then show guide "international-offer".
### Branch based on a prior step's response
Create a survey that uses an earlier step's response to determine a later branch:
1. Step 1: Add a rating block asking "How satisfied are you with this feature?"
2. Step 2: Add a multiple choice question asking "Which area needs improvement?"
3. On step 2, add conditional logic that references the step 1 rating:
- If `step 1 rating ≤ 3`, then go to a step asking for detailed feedback about the issue.
- If `step 1 rating ≥ 4`, then go to a thank-you step.
This approach lets you combine context from multiple steps to personalize the survey path.
### Personalized CTA based on user properties
Create a button action that clicks different elements based on user characteristics:
1. Add a primary button labeled "Get Started".
2. Select **Evaluate conditional logic**.
3. Add conditions:
- If `user_type = new`, then click element `[data-testid="onboarding-flow"]`.
- If `user_type = returning`, then click element `[data-testid="dashboard"]`.
## Best practices
- **Test thoroughly**: Use [preview mode](https://amplitude.com/docs/guides-and-surveys/testing#preview-mode) to test all conditional paths before publishing.
- **Keep logic simple**: Complex nested conditions can be difficult to maintain and debug.
- **Monitor results**: Use [analytics](https://amplitude.com/docs/guides-and-surveys/analytics-glossary) to track how users flow through your conditional experiences.
================================================================================
# Content editor
URL: https://amplitude.com/docs/guides-and-surveys/content-editor
================================================================================
# Content editor
The content editor in Guides and Surveys supports rich content creation through Markdown and HTML, giving you control over how your content appears to users. The content editor works for the content field only. Other fields, such as titles or buttons, aren't supported.
## Markdown support
The description editor supports standard Markdown formatting, so you can create rich text content without writing HTML. Use Markdown for:
- \*\*Bold text\*\* and \*italic text\* or \_italic text\_
- Headers and subheaders
- Lists (bulleted and numbered)
- Links and images
- Code blocks and inline code
### Example Markdown content
```markdown
## Welcome to our *new* feature!
This **important update** includes:
1. Enhanced performance
2. New user interface
3. Better accessibility
> **Note:** This feature is available to all users.
For more information, visit our [help center](/help).
```
## HTML and inline CSS
For advanced customization, you can use HTML with inline CSS directly in the step description editor. HTML with inline CSS gives you control over styling and layout.
> **Info:** HTML is sanitized
>
> Anything outside of inline styling, such as an `onclick`, is ignored.
### Example HTML with inline CSS
```html
Special Announcement
We're excited to share this update with you!
```
## Custom CSS on themes
For more systematic use of custom CSS, you can write custom CSS directly in your [themes](https://amplitude.com/docs/guides-and-surveys/themes#advanced-customization-with-custom-css). Use the CSS selectors in the [Custom CSS documentation](https://amplitude.com/docs/guides-and-surveys/custom-css) to target specific elements and create cohesive designs across all your guides and surveys.
> **Tip:** Content preview
>
> Use the theme preview feature to see how your Markdown and HTML content will appear to users before publishing your guide or survey.
================================================================================
# Localization
URL: https://amplitude.com/docs/guides-and-surveys/localization
================================================================================
# Localization
Localization lets you serve guides and surveys in different languages without creating a new guide or survey for each language. Supported languages are configured per project.
To create localized versions of your guides and surveys, you must:
- Update the SDK to record the user's locale.
- Update your project settings to specify which languages to support.
- Specify how each supported language behaves.
- Create the translated versions of your guides and surveys.
## Update the Guides and Surveys SDK to record locale
Update the SDK to record each user's locale during the Guides and Surveys [SDK initialization](https://amplitude.com/docs/guides-and-surveys/sdk). With an accurate user locale, the SDK serves the correct translation of your guide or survey.
Make the following change in your SDK:
#### Amplitude SDK
```js
const currentLocale = getLocale(); // "en" or "en-US"
// Add the plugin before calling amplitude.init()
amplitude.add(window.engagement.plugin({ locale: currentLocale }));
amplitude.init("API_KEY");
```
#### Third-party analytics
```js
// replace with the function you need
const currentLocale = navigator.language; // for example: "en-US"
engagement.init(apiKey, { locale: currentLocale }); // for use with third-party Analytics SDKs
```
> **Note:** Locale code
>
> Amplitude considers the language of a locale code for certain languages. Refer to the supported locales list below for details.
## Update project settings to support multiple languages
Navigate to _Project Settings > Guides and Surveys_ to configure localization.
On this tab, you can:
- Enable or disable localization
- View the default language
- Define the languages available for your guides and surveys
- Set the fallback behavior when a translation file is unavailable or out of date
Guides & Surveys supports [ISO 639](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) language codes, and the following locales:
- English: `en-US`, `en-GB`, `en-AU`, `en-CA`, `en-IN`
- Spanish: `es-ES`, `es-MX`, `es-AR`, `es-CO`
- French: `fr-FR`, `fr-CA`
- Portuguese: `pt-BR`, `pt-PT`
- Chinese: `zh-CN (Simplified)`, `zh-TW (Traditional)`, `zh-HK (Hong Kong, Traditional)`
- German: `de-DE`, `de-AT`, `de-CH`
- Arabic: `ar-SA`, `ar-EG`, `ar-MA`
> **Note:**
>
> English is the default language for all projects. Only Amplitude Support staff can change this default. To update your default language, contact [Amplitude Support](https://gethelp.amplitude.com).
##### To add a supported language
1. In the Supported languages section, click **Add language**.
2. In the menu, search for or scroll to select the languages you need. You can select as many as you need.
3. Click **Apply**.
### Configure fallback behavior
Fallback behavior controls what appears when localized content isn't available. You can configure two types of fallback:
- **When translation is unavailable**: If a translation for a guide or survey isn't uploaded, choose whether the content appears in the default language or doesn't appear at all.
- **When translation is outdated**: If the default content changes but the translated content doesn't reflect the change, choose whether to show the default language, show the outdated translated version, or hide the content.
## Add localized content to a guide or survey
You can add localized versions to existing guides or surveys, or include localized content as you create new ones.
##### To add localized content to a guide or survey
1. Open an existing guide or survey, or click **Create Guide** or **Create Survey**.
2. For an existing guide or survey, click **Setup**.
3. For a new guide or survey, create and save the default content, then click **Setup**.
4. Scroll to the Localization section.
### Translatable strings
You can localize the following parts of guides and surveys:
#### Click for more information...
- Guide step title
- Guide step description
- Survey step title
- Survey step description
- Checklist title
- Checklist description
- Button text (primary and secondary)
- Checklist done button label
- Snooze label
- Survey text prompt
- Survey rating lower label
- Survey rating upper label
- Survey list required message
- Survey list "other" option label
- Survey list "other" option placeholder
- Survey list input options
- Video URL
### Translate content
You can add localized content to your guide or survey in several ways:
- Use the web interface to add or edit translations. Amplitude recommends this method.
- Use AI localization to translate your content automatically. Amplitude recommends this method for quick, automated translations.
- Use the .xliff file to add or edit translations. Amplitude recommends this method if you integrate with a custom translation workflow.
- Use the [localization API](https://amplitude.com/docs/apis/guides-and-surveys/guides-and-surveys-api-localization) to add or edit translations. Amplitude recommends this method for automated translation workflows. The API takes longer to set up, but suits larger teams or teams that support many languages.
#### Web interface
The web interface is the preferred method for adding localized content because it maps directly to each text string.
1. Click the **Build** tab of your guide or survey.
2. In the upper-right of the screen, click the language toggle. The default is **English**.
3. Select the language you need.
4. Update the individual strings with your translated content. Amplitude associates each string with the language shown in the language toggle.
#### AI localization
AI localization translates your guide or survey content automatically using [Claude](https://claude.ai/login?returnTo=%2F%3F). Amplitude takes the strings from the default language and attempts to:
- Maintain the original meaning and tone.
- Make the translations natural and user-friendly.
- Preserve HTML tags, formatting, and special characters.
Amplitude can't guarantee the accuracy of AI-translated strings, so review AI-translated content manually before publishing. You can edit AI translations through the web interface.
##### To use AI localization
1. Complete the guide or survey's steps in the default language.
2. In the Localization section of the Setup tab, select one of the following:
- **Translate All Languages**: Translate your content into all languages set in your project settings.
- **Translate Selected Language**: Translate your content for a single language.
#### XLIFF file upload
If you want to integrate with your own translation workflow, you can download an [.xliff](https://en.wikipedia.org/wiki/XLIFF) file for each language.
##### To upload an XLIFF file
1. Create the guide or survey in the default language.
2. Download the translation template. This template is a .xliff file that contains [translatable strings](#translatable-strings) from each step of your guide or survey.
> **Tip:** Adding translations to the xliff files
>
> Guides and Surveys template files put untranslated content inside `` tags in an .xliff file. Don't change the content in these tags. Add translations to the `` tags. For example:
>
> ```xml
>
> Finish
> Terminer
>
> ```
3. Create translations to your target languages with the template file and upload a translated .xliff file for each language. If you don't upload a file for a language, Guides and Surveys follows the specified fallback setting for a missing translation. To include HTML in your guide or survey content (for example, \`
`tags), escape the HTML in the`\` tag. For example:
```xml
First line<br>Second line
```
4. After you upload an .xliff file, review the content by toggling through the language picker.
> **Tip:** Update translations
>
> After you upload a translation .xliff file, you can still update localized content on the appropriate step of the guide or survey. Amplitude applies your updates to the uploaded .xliff file to keep it in sync.
### Preview a translation
When you preview a localized guide or survey, the preview bar displays translation-related issues that may prevent the guide or survey from showing.
================================================================================
# Guide or Survey not showing
URL: https://amplitude.com/docs/guides-and-surveys/troubleshooting/guide-or-survey-not-showing
================================================================================
# Guide or Survey not showing
A guide or survey that never appears usually fails one of five checks: the SDK isn't running on the page or in the app, the experience isn't published to the right project, the user doesn't match the targeting, the trigger never fires, or a limit or throttle blocks the display. Work through the checks in that order, because a broken SDK setup makes every other check impossible to evaluate.
This article assumes you know how to configure a guide or survey. If you need a refresher, review [Setup and Targeting](https://amplitude.com/docs/guides-and-surveys/setup-and-target) before proceeding. If the experience shows more often than you expect instead, go to [Guide or Survey seen too often](https://amplitude.com/docs/guides-and-surveys/troubleshooting/guide-or-survey-seen-too-often).
## Debug with Preview mode and platform tools
Before you change any settings, use the tools that report which condition fails. They save you from guessing.
### Web: Chrome extension and Preview mode
The [Amplitude Chrome extension](https://amplitude.com/docs/data/chrome-extension-debug) is the fastest way to diagnose a web guide or survey that doesn't show. Its **Guides & Surveys** tab reports:
- **SDK setup**: whether the SDK is installed, initialized, connected to an analytics SDK, and booted, plus the API key in **Show config** and the resolved user in **Show user info**.
- **Trigger conditions**: for every published guide and survey in the project, which conditions pass and which block the display, including built-in throttles, custom throttles, limits, page targeting, snooze, and user targeting.
- **Forwarded events**: every client-side event the SDK observes. Enter an event name and click **Test Event** to simulate it and confirm an event-based trigger fires.
The extension's **Guides & Surveys** tab doesn't update live, so wait for the page to finish loading before you read it.
[Preview mode](https://amplitude.com/docs/guides-and-surveys/testing#preview-mode) checks a single experience against a real page. The preview bar shows the **Trigger**, **Limit**, and **Throttle** conditions, where green means the condition passes and yellow means it blocks the display. From the preview bar you can also click **Reset User History**, toggle **Ignore Throttle Limits**, and manually trigger the event a trigger waits on. If the preview itself never appears, go to [Troubleshooting preview mode](https://amplitude.com/docs/guides-and-surveys/testing#troubleshooting-preview-mode), which covers `window.postMessage` failures and the `Cross-Origin-Opener-Policy` header.
### Mobile: Super Debugger and Preview mode
On mobile, [Preview mode](https://amplitude.com/docs/guides-and-surveys/testing#preview-mode) shows a QR code and a preview URL. Scan the code with a device that has your app installed, or open the URL on that device. After you configure the SDK and URL scheme, the app opens with a small Amplitude logo at the bottom of the screen. Tap the logo to open the Super Debugger.
The Super Debugger **Details** tab reports **Limits**, **Trigger** (including screen conditions and pin targets), and **Throttle**. Toggle **Ignore limits** to bypass throttles during the preview. The **Setup** tab reports SDK version, installation type, user ID, and whether events flow into and out of the Guides and Surveys SDK. Go to [Super Debugger](https://amplitude.com/docs/sdks/guides-and-surveys/guides-and-surveys-ios-sdk#super-debugger) for the full panel. The Android, React Native, and Flutter SDKs include the same debugger.
If Preview mode never reaches your app:
- **iOS shows `No usable data found`**: the device has no app that handles the preview URL. The app isn't installed on that iOS device, or the installed build doesn't register the project's [mobile URL scheme](https://amplitude.com/docs/sdks/guides-and-surveys/guides-and-surveys-ios-sdk#set-up-and-verify-preview-mode). Install a build that includes the Guides and Surveys SDK and the URL scheme, then scan the QR code with that device's camera.
- **Android's action sheet lists no app**: the same cause. The OS has no app that handles the preview URL, so nothing appears on the share or open-with sheet. Install a build that includes the SDK and the intent filter for the URL scheme. Go to [Android preview setup](https://amplitude.com/docs/sdks/guides-and-surveys/guides-and-surveys-android-sdk#set-up-and-verify-preview-mode).
- The preview opens in a browser instead of the app: you didn't register the URL scheme, or the app doesn't call `handleUrl` (iOS) or `handleLinkIntent` (Android) when it receives the link.
Preview mode confirms rendering and conditions, not real-world delivery. To test delivery with real users, use the [Testing status](https://amplitude.com/docs/guides-and-surveys/testing#testing-status-function).
## Troubleshooting checklist
Use these questions as a checklist. If you can answer "yes" to a question, that setting is unlikely to be the cause of your issue.
**Is the SDK installed and booted on the page or in the app?**
On web, open your browser console and enter `window.engagement`. A response of `undefined` means the [Guides and Surveys SDK](https://amplitude.com/docs/sdks/guides-and-surveys/sdk) isn't installed on that page. Then enter `window.engagement._debugStatus()` and confirm the `user` object exists, `apiKey` is set, `stateInitialized` and `decideSuccessful` are both `true`, and `num_guides_surveys` is greater than zero.
Common web installation problems include an SDK that loads on some pages but not others, a `boot` call that runs conditionally for certain environments or user types, a `boot` call that runs more than once, and a Guides and Surveys SDK that loads before the Amplitude Browser SDK. If you install through Google Tag Manager with a custom HTML tag, enable **Support document.write** in the tag's advanced settings. Go to [Troubleshoot your installation](https://amplitude.com/docs/sdks/guides-and-surveys/sdk#troubleshoot-your-installation) for the full list.
On mobile, use the Super Debugger **Setup** tab instead of the browser console. Confirm an SDK version appears, the user ID matches the user you expect, and events flow into the Guides and Surveys SDK. If Preview mode never shows the Amplitude logo, the SDK isn't handling the preview URL. Confirm you added the project's URL scheme and that the app forwards the inbound link to the SDK.
**Does the API key match the project that holds the experience?**
The SDK fetches guides and surveys for the project tied to its API key. If you initialize the SDK with a key from a different project, no experience loads even though the setup looks correct. Use the same API key for the core Amplitude SDK and the Guides and Surveys SDK, and confirm the key belongs to the project where you published the experience.
**Is the status Published, and is the schedule active?**
A **Draft** experience never appears to users, and a **Testing** experience appears only to the device IDs, user IDs, and cohorts in the **Test users** section. For a **Scheduled** experience, confirm the current time falls between the start and end dates, and remember that those times use the project's timezone. Also check whether a [bulk unpublish](https://amplitude.com/docs/guides-and-surveys/setup-and-target#bulk-unpublish) took the experience offline.
**Does the user match your targeting?**
Open the [targeting](https://amplitude.com/docs/guides-and-surveys/setup-and-target#targeting) segments and confirm the affected user matches at least one of them. Amplitude `OR`s multiple segments, so a user needs to match only one, but every filter within a segment must match.
Watch for these targeting causes:
- A rollout percentage below 100% excludes users outside the bucket. The bucketing unit decides whether that assignment stays consistent across a user's devices.
- Array user properties don't flatten at evaluation time, so dotted paths like `subscription.plan` don't resolve. Target a flat scalar property instead.
- Cohort membership syncs on a schedule, so a user who just qualified doesn't match yet. Go to [Cohort targeting](https://amplitude.com/docs/guides-and-surveys/troubleshooting/cohort-targeting) for the sync rules.
- The user property the filter reads might not exist on the user's profile at evaluation time.
- Group cohort targeting requires your instrumentation to call `setGroup` for each user. Attaching group properties to events creates event-level grouping, which supports analysis but doesn't qualify users for group cohort targeting. Go to [Group cohort targeting uses event-level groups](#group-cohort-targeting-uses-event-level-groups) for details.
**Does the trigger fire for this user?**
Confirm the [trigger](https://amplitude.com/docs/guides-and-surveys/setup-and-target#triggers) matches what the user actually does:
- The **None** trigger never fires on its own. It waits for the SDK, a call to action in another guide, or another external trigger.
- **On event tracked** needs a client-side event the SDK can observe. Server-side events, [Labeled Events](https://amplitude.com/docs/data/visual-labeling), and [Custom events](https://amplitude.com/docs/data/custom-events) don't work as triggers. On web, check the extension's Forwarded Events list to confirm the SDK sees the event. On mobile, check **Event Flow** on the Super Debugger **Setup** tab.
- **When element appears** fires once for each page or screen load, and it doesn't re-trigger when the element scrolls out of view and back in.
- **When element clicked/tapped** and element-based conditions depend on a selector that still matches. On web, that's a CSS selector or XPath against your current markup. A redesign that changes class names breaks the selector. On mobile, that's the unique identifier on the target view (`accessibilityIdentifier` on iOS; `tag`, `contentDescription`, or `resourceName` on Android; the `tag` passed to `.amplitudeView` or `AmplitudeView` in Jetpack Compose). If two views share an identifier, or the identifier is missing, the trigger doesn't fire.
- A [trigger delay](https://amplitude.com/docs/guides-and-surveys/setup-and-target#trigger-delay) cancels the display if the user navigates away before the delay elapses, and Amplitude re-evaluates conditional logic after the delay rather than at trigger time.
- If the experience uses [session properties](https://amplitude.com/docs/guides-and-surveys/setup-and-target#session-properties), every configured session property condition must match at display time.
**Does the current page or screen match the Where conditions?**
Review the [Where settings](https://amplitude.com/docs/guides-and-surveys/setup-and-target#where) and test the match type against what the SDK actually reports.
On web, compare the rule to the exact URL, including query parameters and trailing slashes. A regex or pattern that works on your staging URL can miss in production.
On mobile, Where conditions match **screen names**, not web URLs. In the Super Debugger **Details** tab, the **Screen** field shows the name the SDK reports. If that string doesn't match your include rule, the experience doesn't display. Check [project-wide default page exclusions](https://amplitude.com/docs/guides-and-surveys/setup-and-target#project-wide-default-page-exclusions) under _Project Settings > Guides and Surveys_ too. An exclusion set once at the project level applies to every experience, including ones you create later. Page and screen targeting also apply to [share links](https://amplitude.com/docs/guides-and-surveys/setup-and-target#send-a-link-to-a-guide): a link overrides audience targeting but not Where targeting.
**Has the user already seen it?**
Amplitude enables `Stop showing when completed` and `Stop showing when dismissed` by default, so a user who finished or closed the experience once doesn't get it again. A [cooldown](https://amplitude.com/docs/guides-and-surveys/setup-and-target#limits) blocks the display until it expires, and a user who snoozed the experience doesn't see it again until the snooze duration passes. To make a user eligible again, open their user profile, go to the Guides or Surveys tab, and select **Clear history** for that experience.
**Does a throttle block the display?**
[Throttling](https://amplitude.com/docs/guides-and-surveys/throttling) caps how many guides or surveys each user sees in a day, week, month, or session, and the settings for guides and surveys are separate. Check all four layers:
- The global limit and period.
- The **Time Between** delay, which blocks a second guide for a set duration after the user sees one.
- Advanced tag-based throttles, where the most restrictive limit wins.
- [Mutual exclusivity](https://amplitude.com/docs/guides-and-surveys/throttling#mutual-exclusivity) groups, where a user who saw one item from the group doesn't see the others.
**Is another experience already on screen?**
Amplitude displays only one pin, popover, or modal at a time, and only one banner and one checklist. When one of those form factors already shows and another triggers, the second doesn't display, and it doesn't queue for later. If several experiences are eligible at once, [priority and the tiebreaker rules](https://amplitude.com/docs/guides-and-surveys/setup-and-target#tiebreakers-when-multiple-guides-are-eligible-for-display) decide which one wins.
**Does the anchor element exist when the step renders?**
Pins, tooltips, and card embeds attach to an element. If that element isn't in the DOM (web) or the view hierarchy (mobile) at render time, the step doesn't display, and Guides and Surveys doesn't skip it or fall back to another position. On web, elements that render late, sit behind a lazy-loaded component, or live inside a [shadow DOM](https://amplitude.com/docs/guides-and-surveys/form-factors#target-elements-in-shadow-dom) are the usual causes. On mobile, confirm each target view carries its unique identifier and that no two card embeds on the same screen share one. Pins also can't target iOS tab bar items or views inside animated containers.
**Is the environment blocking the SDK?**
On web, a strict Content Security Policy blocks the requests and inline styles the SDK needs. Allow `https://*.amplitude.com` for the `script-src`, `connect-src`, `img-src`, `media-src`, and `style-src` directives, and pass a `nonce` at initialization if your policy blocks inline styles. Guides and Surveys also has [limited iframe support](https://amplitude.com/docs/sdks/guides-and-surveys/sdk#iframe-support-and-limitations): selectors can't cross an iframe boundary, so each iframe needs its own SDK instance to display anything.
On mobile, the SDK requires a network connection to fetch guides and surveys. If the device is offline when the app launches, nothing displays for that session. Retry on a network, then confirm events flow in the Super Debugger **Setup** tab.
**Does the user's SDK version support the feature?**
Mobile SDKs can't auto-update, so a device on an older version doesn't receive experiences that rely on newer capabilities. The **After N events in session** trigger, for example, requires iOS, Android, and React Native SDK v3.7.0 or later, and guides using it don't reach users on older versions at all. Go to the [mobile SDK changelog](https://amplitude.com/docs/guides-and-surveys/guides-and-surveys-mobile-sdk-changelog) to check version requirements.
## Situations that look like a failure to deliver
Some expected behaviors can feel like the experience is broken.
### It works in Preview mode but not in production
Preview mode and the **Testing** status both relax the rules that apply to real users. Amplitude ignores limits for test users, and Preview mode lets you bypass throttles and manually fire trigger events. An experience that displays under those conditions can still fail a limit, throttle, or targeting check in production. On web, use the Chrome extension on the production page to find which condition blocks it. On mobile, add the user to **Test users** and set the experience to **Testing** so you can reproduce with live delivery rules. Use Preview and the Super Debugger **Details** tab when you need to inspect trigger, limit, and throttle conditions.
### Only some users see it
A rollout percentage below 100% is the most common reason. With Device ID bucketing, the same user can qualify on one device and not on another, because each device receives an independent assignment. Switch to User ID bucketing when you need a consistent experience for a signed-in user across devices, or to Account ID when everyone in an organization needs the same result.
### The user reports it missing after they dismissed it
An [active](https://amplitude.com/docs/guides-and-surveys/setup-and-target#active-state) guide follows the user across pages or screens until they complete or dismiss it. After they dismiss it, the default limits keep it from returning, so a user who dismissed the experience by accident sees nothing on later visits. Clear the experience from their history to make them eligible again.
### A mobile device stays in Test User mode
Devices left in [Test User mode](https://amplitude.com/docs/guides-and-surveys/testing#test-user-mode) don't render guides and surveys the way regular users do. If a mobile tester reports inconsistent behavior, confirm the mode is off, then retest.
### Preview mode never opens the mobile app
Preview on mobile depends on a custom URL scheme, not on a new browser tab. If iOS shows `No usable data found`, or Android's action sheet lists no app, the OS has no app registered for the preview URL. Install the app on the device you scan from, confirm the URL scheme matches _Settings > Projects > General > URL scheme (mobile)_, and scan again. This isn't a targeting or trigger failure. The OS never handed the link to your app, so the SDK never ran.
### The experience is temporarily hidden
[Conditional logic](https://amplitude.com/docs/guides-and-surveys/conditional-logic) can hide an active guide while its `temporarily hide if` conditions apply. The guide stays active and becomes eligible for display again after those conditions stop matching. Check the conditions on each step when a guide disappears part way through a flow.
### Group cohort targeting uses event-level groups
When instrumentation attaches group properties to individual events, Amplitude creates an event-level grouping. Event-level groups work correctly for analysis: charts show accurate data, and users appear in the group profile's users tab. However, event-level groups don't make users eligible for group cohort targeting in guides, surveys, or experiments.
For group cohort targeting to work, instrumentation must call `setGroup` in the analytics SDK for each user. That call sets the group on the user's profile, and targeting evaluates profile-level group membership, not event-level group properties.
If charts and group profile data look correct but targeted users still don't receive the guide, confirm that your SDK implementation calls `setGroup`. Go to [User groups](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#user-groups) for implementation details.
================================================================================
# Guide or Survey seen too often
URL: https://amplitude.com/docs/guides-and-surveys/troubleshooting/guide-or-survey-seen-too-often
================================================================================
# Guide or Survey seen too often
Users sometimes report seeing the same guide or survey repeatedly, or receiving more guides and surveys than you intended. Most often, you notice the issue in your analytics first: a single user logs an unexpectedly high number of Guide Viewed events. This page describes the most common causes and how to fix them.
This article assumes you know how to configure a guide or survey. If you need a refresher, review [Setup and Targeting](https://amplitude.com/docs/guides-and-surveys/setup-and-target) and [Throttling](https://amplitude.com/docs/guides-and-surveys/throttling) before proceeding.
## Troubleshooting checklist
Use these questions as a quick checklist when a guide or survey appears too often. If you can answer "yes" to a question, that setting is unlikely to be the cause of your issue.
**Is "Stop showing when completed" enabled?**
The [Limits](https://amplitude.com/docs/guides-and-surveys/setup-and-target#limits) section of the builder controls whether an experience can repeat. Amplitude enables `Stop showing when completed` by default. When you disable it, the experience remains eligible to trigger again after the user completes it, so the same user can see it every time the trigger condition fires.
**Is "Stop showing when dismissed" enabled?**
Amplitude also enables `Stop showing when dismissed` by default. When you disable it, the experience can trigger again after the user dismisses it. If users close a guide and it reappears on their next page or screen load, check this setting first.
**Is a cooldown configured, and is it long enough?**
If you disabled `Stop showing when dismissed` on purpose, add a [cooldown](https://amplitude.com/docs/guides-and-surveys/setup-and-target#limits) to limit how often the experience can trigger for a user. Without a cooldown, the experience can fire every time its trigger condition matches. If a cooldown exists but users still see the experience too often, increase its duration.
**Is throttling turned on for your project?**
[Throttling](https://amplitude.com/docs/guides-and-surveys/throttling) sets a global limit on how many guides or surveys each user sees within a period (day, week, month, or session). Throttling settings for guides and surveys are separate, so confirm you configured the one that's causing complaints. Also check the **Time Between** setting, which enforces a delay between sequential guides for the same user.
**Is the trigger broader than you intended?**
A guide with the **Immediately** trigger and no page or screen targeting fires on every page load (web) or every matching screen (mobile) until a limit stops it. Review the [When and Where settings](https://amplitude.com/docs/guides-and-surveys/setup-and-target#triggers) to confirm the trigger and page or screen conditions match your intent. Narrow the **Where** condition to specific pages or screens if the experience should only appear in one part of your product.
**Does the user resolve to the same identity across sessions?**
Amplitude stores the guides and surveys a user has encountered as part of their user history. If a user's identity changes between visits, Amplitude treats them as a new user and shows the experience again.
On web, this happens when users don't always receive a user ID and their device ID changes frequently, for example when anonymous users clear cookies or browse in incognito mode.
On mobile, a new device ID appears when the user reinstalls the app, resets the device, or otherwise gets a fresh install. If you boot the SDK with only a device ID, that user looks new after every reinstall and sees the experience again.
A related symptom is a user profile with many [merged Amplitude IDs](https://amplitude.com/docs/data/sources/instrument-track-unique-users). When an existing user starts a new session with a new device ID and without a user ID, Amplitude treats them as a new user and shows the experience again. Later, the user signs in and receives a user ID, and Amplitude merges the two IDs into a single profile. That Amplitude profile then shows both _Viewed_ events, which is unintuitive when you configured the guide or survey to appear only once.
The most robust setup is to initialize the Guides and Surveys SDK only after the user signs in and has a proper user ID.
## Situations that look like over-delivery
Some expected behaviors can feel like a guide or survey appears too often.
### The reporting user is a test user
When a guide or survey uses the [Testing status](https://amplitude.com/docs/guides-and-surveys/testing#testing-status-function), Amplitude ignores limits for test users to make testing easier. Test users also continue to receive the guide or survey after you change its status to **Published** or **Scheduled**. If an internal user reports seeing an experience repeatedly, check whether their device ID, user ID, or cohort appears in the **Test users** section.
Similarly, devices left in [Test User mode](https://amplitude.com/docs/guides-and-surveys/testing#test-user-mode) (mobile only) don't render guides and surveys the way regular users do. Turn Test User mode off after you finish debugging.
### Something bypassed throttling
Throttling and cooldowns don't apply in every situation. Amplitude ignores them when:
- The guide or survey has **Urgent** [priority](https://amplitude.com/docs/guides-and-surveys/setup-and-target#priority).
- A force trigger displays the experience: the SDK, a call to action (CTA) in another guide, the Amplitude Assistant, or a [share link](https://amplitude.com/docs/guides-and-surveys/setup-and-target#send-a-link-to-a-guide). A share link also overrides audience targeting, so users who follow a link with the guide's query parameter attached see the guide regardless of their history.
- Someone reset the user's interactions with the guide through the [user profile](https://amplitude.com/docs/guides-and-surveys/testing#troubleshooting-preview-mode). Clearing a guide from a user's history makes that user eligible to see it again.
### The guide is active and follows the user
When a user first views a guide or survey, it becomes [active](https://amplitude.com/docs/guides-and-surveys/setup-and-target#active-state) and remains active until the user completes or dismisses it. An active guide shows up on every page load (web) or screen (mobile) and follows the user across pages and screens, even where the trigger condition didn't fire. This is expected behavior, not a repeat display. The guide stops following the user after they complete or dismiss it.
To confirm the active state is the cause, inspect the guide's display events in the Event Explorer. The `source.type` property shows whether the active state or a new trigger caused each display.
### The user snoozed the guide instead of dismissing it
If the experience is [snoozable](https://amplitude.com/docs/guides-and-surveys/setup-and-target#settings), a snoozed guide reappears after the snooze duration passes. Users who snooze rather than dismiss see the experience again by design. Increase the snooze duration if it reappears too quickly.
================================================================================
# Cohort targeting
URL: https://amplitude.com/docs/guides-and-surveys/troubleshooting/cohort-targeting
================================================================================
# Cohort targeting
Users sometimes don't see a guide or survey you expected them to receive, or they see it when you thought a cohort exclusion would block them. When your targeting includes a cohort filter, the cause is often cohort sync timing rather than a misconfigured trigger or limit.
Guides and Surveys audience targeting is a subset of [Feature Experiment](https://amplitude.com/docs/feature-experiment/overview) targeting. It supports [remote evaluation](https://amplitude.com/docs/feature-experiment/remote-evaluation) only and follows the same asynchronous cohort sync rules as Experiment. For a deeper explanation of how cohort targeting works in Experiment, go to [Cohort Targeting](https://amplitude.com/docs/feature-experiment/cohort-targeting).
This article assumes you know how to configure targeting in the builder. If you need a refresher, review [Setup and Targeting](https://amplitude.com/docs/guides-and-surveys/setup-and-target) before proceeding.
## How cohort targeting works in Guides and Surveys
When you add a cohort to a targeting segment, Guides and Surveys evaluates the user through remote evaluation. Amplitude syncs the cohort to the **Amplitude Experiment** destination and checks whether the user belongs to that cohort at evaluation time.
Guides and Surveys doesn't support [local evaluation](https://amplitude.com/docs/feature-experiment/local-evaluation) cohort targeting. You can't download cohort membership to the SDK for client-side evaluation the way server-side Experiment SDKs do.
Dynamic cohorts don't update in real time. Amplitude syncs them to the Experiment destination on an hourly schedule by default. If you target a cohort of users who performed a `Sign Up` event, a user who just signed up might not match the cohort until the next sync completes.
Large cohorts can also take longer on the initial sync or after a significant membership change. The first sync of a 10-million-user cohort takes longer than later incremental syncs.
Remote evaluation supports cohorts up to 10 million users. Mobile uses the same remote evaluation path, so the device needs a network connection at evaluation time. If the app launches offline, Guides and Surveys doesn't fetch cohort membership for that session.
## Troubleshooting checklist
Use these questions when a user doesn't match your cohort-based targeting as expected.
**Does the cohort use the Amplitude Experiment sync destination?**
For remote evaluation cohort targeting, the cohort must sync to the **Amplitude Experiment** destination. Open the cohort in Analytics and confirm the sync destination includes **Amplitude Experiment**. Without this destination, Guides and Surveys can't evaluate cohort membership during remote evaluation.
**Is the user in the cohort right now?**
Open the cohort in Analytics and confirm the user appears in the current membership. If the user isn't in the cohort yet, the guide or survey doesn't target them regardless of other settings.
**Did the user join the cohort after the last sync?**
Dynamic cohort membership updates asynchronously. If the user entered the cohort recently, check the cohort's sync history. The user might have been added in a sync that completed after the evaluation occurred. Wait for the next hourly sync and test again.
**Are you targeting new users with a cohort?**
Cohort membership updates with a delay, so a cohort-based new-user filter doesn't match users on their first visit. Use the built-in **First Seen** property instead when you need real-time new-user targeting. Go to [First Seen timestamp](https://amplitude.com/docs/guides-and-surveys/setup-and-target#first-seen-timestamp) for setup details.
**Is the user's identity consistent across sessions?**
If a user's identity changes between visits, Amplitude treats them as a different user for targeting purposes. This affects cohort membership the same way it affects limits and history.
On web, identity often changes when anonymous users clear cookies or browse in incognito mode. On mobile, identity often changes when the user reinstalls the app or you boot the SDK with a new device ID and no user ID.
To learn how Amplitude resolves user identity across devices and sessions, go to [Track unique users](https://amplitude.com/docs/data/sources/instrument-track-unique-users). For identity troubleshooting steps, go to [Guide or Survey seen too often](https://amplitude.com/docs/guides-and-surveys/troubleshooting/guide-or-survey-seen-too-often).
**Did a share link or force trigger bypass targeting?**
Direct [share links](https://amplitude.com/docs/guides-and-surveys/setup-and-target#send-a-link-to-a-guide) override audience targeting, including cohort filters. SDK triggers, CTAs, and urgent-priority experiences can also display a guide outside normal targeting rules.
On mobile, a share link or preview URL opens the app only if the app is installed and the URL scheme is registered. If iOS shows `No usable data found`, or Android's action sheet lists no app, the OS never opened your app. That isn't a cohort miss. Go to [Guide or Survey not showing](https://amplitude.com/docs/guides-and-surveys/troubleshooting/guide-or-survey-not-showing#preview-mode-never-opens-the-mobile-app).
## Situations that look like cohort targeting failures
Some expected behaviors can feel like cohort targeting isn't working.
### The user just qualified for the cohort
Behavioral cohorts update on a schedule, not at the moment the qualifying event fires. A user who completes the action that defines the cohort might not match the filter until the next sync. This is expected behavior for dynamic cohorts in remote evaluation.
If you need immediate targeting based on a user property or event, pass the property explicitly through remote evaluation or use a real-time property like **First Seen** instead of a cohort.
### The cohort membership changed significantly
Adding or removing a large number of users from a cohort can extend the next sync duration. Users at the edge of membership changes might evaluate against stale membership until the sync finishes.
### You're excluding a cohort
Excluding a cohort works the same way as including one, with the same sync delays. If a user recently left an excluded cohort, they might remain excluded until the next sync updates membership on the Experiment destination.
## Learn more in Feature Experiment
Guides and Surveys reuses Experiment's remote evaluation pipeline for cohort targeting. For full details on sync destinations, supported cohort sizes, and advanced troubleshooting, go to:
- [Cohort Targeting](https://amplitude.com/docs/feature-experiment/cohort-targeting)
- [Remote evaluation](https://amplitude.com/docs/feature-experiment/remote-evaluation)
================================================================================
# Guide form factors and properties
URL: https://amplitude.com/docs/guides-and-surveys/form-factors
================================================================================
# Guide form factors and properties
Guides and Surveys include a variety of form factors. Each form factor has a set of properties that control how it behaves for the end user.
## Form factors
Each form factor shares a similar set of [properties](#properties).
### Modal
Modals are a full-focus experience that takes center stage. Use modals to deliver important messages or guide users through a multi-step flow.
Customize your modal with the following:
- Pick a layout: classic, horizontal split, vertical split, or showcase.
- Add a button, and customize what happens when users click or tap it.
- Add an image or video. Amplitude places media elements depending on the selected layout.
- Animate the text. Text animation causes text to animate in when the guide appears.
Click the three dot menu to access format settings.
| Setting | Description |
| --- | --- |
| Content layout | Updates the visual ordering of the guide's content. |
| Title and content alignment | Changes the alignment of the title and body text. |
| Actions bar | Updates the placement and layout of the guide's buttons. |
| Click/Tap outside to close | Enables users to click or tap outside of the modal to dismiss it. |
| Text animation | Enables the modal's text to animate in with a typewriter effect. |
### Popover
A subtle nudge that appears near a contextually relevant element. Use popovers for quick tips or to direct users' attention without interrupting their flow.
Popovers offer many of the same customization options as modals.
Click the three dot menu to access format settings.
| Setting | Description |
| --- | --- |
| Content layout | Updates the visual ordering of the guide's content. |
| Title and content alignment | Changes the alignment of the title and body text. |
| Actions bar | Updates the placement and layout of the guide's buttons. |
| Z-index | Specify a custom z-index value for the popover. |
| Text animation | Enables the popover's text to animate in with a typewriter effect. |
### Pin
Pins are persistent markers that remain on screen until a user interacts with them. Use pins to highlight key features or provide contextual help users can refer to.
> **Note:** Pins can advance without CTA clicks
>
> By default, when a user clicks a pin's target element, the tour advances to the next step. You can disable this behavior with the **Disable auto-advance on target click** setting (web only). The **Advance trigger** setting in the [Pin](#pin) format settings lets you specify an additional element that also advances the tour when a user clicks it.
> **Note:** Analytics impact for pins not set to open by default
>
> For pin guides that aren't set to **Open by default**, clicking the target element marks the guide as complete without generating a Guide Viewed event. This can result in more Guide Completed events than Guide Viewed events when users interact with the target element without first opening the pin beacon.
Pins offer different customization options than modals or popovers. Toggle between opening them by default, or start them closed. Use **Show mask** to display a semi-transparent overlay that highlights the pinned element and dims the rest of the screen.
Pins can use the following position settings:
- Auto
- Top of target
- Bottom of target
- Left of target
- Right of target
The position setting specifies where the pin message renders relative to its target. If the target element's location is incompatible with the specified position, Amplitude tries a different location. For example, if the target is on the far-left side of the page, the pin can't render to the left. Amplitude then attempts to render the pin above, below, or to the right of the target. If the pin can't display in any of the four positions, Amplitude doesn't render the pin.
Click the three dot menu for the pin to access format settings.
| Setting | Description |
| --- | --- |
| Open by default | Enables the pin to open without user interaction. If disabled, users must click or tap the pin to open it. |
| Open on hover | Opens the pin when the user hovers over the hotspot. Disable **Open by default** to use this setting. When **Open by default** is disabled and the **Open on hover** setting is also disabled, users must click the hotspot to open the pin. |
| Show mask | Enables a background mask when the pin is open to help draw the user's focus. |
| Content layout | Updates the visual ordering of the guide's content. |
| Title and content alignment | Changes the alignment of the title and body text. |
| Actions bar | Updates the placement and layout of the guide's buttons. |
| Z-index | Specify a custom z-index value for the popover. |
| Text animation | Enables the pin's text to animate in with a typewriter effect. |
| Disable auto-advance on target click | When you enable this option, clicking on the target element doesn't advance the guide to the next step. |
| Skip if target not found | When you enable this option, the guide skips to the next step if it can't find the target element within `250ms` of the step becoming active. If the step is the last step and the guide skips it, the guide completes. |
| Advance trigger | Enables advancing the guide to another step when the user interacts with the element you specify. |
### Tooltip
> **Tip:**
>
> Tooltips are available in the Tooltip template, and contain one step.
Tooltips are like pins, but reveal only when a user clicks, taps, or hovers over them. Use tooltips to give inline details about a feature while saving UI space.
| Setting | Description |
| --- | --- |
| Content layout | Updates the visual ordering of the guide's content. |
| Title and content alignment | Changes the alignment of the title and body text. |
| Actions bar | Updates the placement and layout of the guide's buttons. |
| Z-index | Specify a custom z-index value for the popover. |
| Pointer | Select the style that relates the dialog to the marker. |
| Marker | Select the appearance of the marker that reveals the tooltip message. |
| Element is marker | The targeted element becomes the tooltip trigger. The tooltip displays when the user clicks or hovers the element, without a separate marker icon. Use this when the page element already has an obvious affordance, such as a button, link, or icon, and you don't want a second indicator overlaid on it. |
| Marker Width | Define the width of the tooltip's marker (icon/image) in pixels. |
| Text animation | Enables the tooltip's text to animate in with a typewriter effect. |
| Show on hover/click | Select the trigger that causes the tooltip message to appear. |
> **Note:**
>
> Tooltips bypass cooldowns and remain visible even after a user completes them. For tooltip surveys, users can fill out the survey again as a new submission.
### Banner
> **Tip:**
>
> Banners are available in the Banner template, and contain one step.
Banners are full-width blocks that show on either the top or bottom of the page. Use banners for longer-term announcements, status updates, or time-sensitive promotions.
> **Info:** Banner display limitations
>
> Banners can overlap existing content on your website even when using the **Inline** display style. Overlap happens when your site has conflicting CSS styles on the `body` element or other page elements. If changing the display style from **Overlay** to **Inline** doesn't resolve content overlap, conflicting CSS in the application prevents the banner from rendering in the intended position.
> **Tip:** Use card embeds as a workaround
>
> If banners aren't rendering as expected, try [card embeds](#card-embed). Card embeds render content directly into your page's DOM as native elements, which reduces the chance of CSS conflicts. For example, you can configure a card embed as **Prepend to children (first child)** on ``, which typically renders the card as the top element on the page.
| Setting | Description |
| --- | --- |
| Sticky | Keeps the banner visible while the user scrolls. |
| Display style | Controls the way in which the banner interacts with the page's content. Mobile banners support overlay only. |
| Z-index | Specify a custom z-index value for the popover. |
| Text animation | Enables the banner's text to animate in with a typewriter effect. |
### Checklist
Checklists provide a form that helps users track progress toward a goal. They contain one header and one or more checklist items. Use checklist items to trigger actions.
| Setting | Description |
| --- | --- |
| Z-index | Specify a custom z-index value for the checklist. |
#### Checklist items
Checklist items compose a checklist.
| Setting | Description |
| --- | --- |
| Skippable | If enabled, the user can complete the checklist item through a "Skip" button. |
### Carousel
Carousels present a multi-step guide as a single card that users swipe left or right to navigate, instead of relying on button taps. Use carousels for onboarding flows or feature tours you want users to browse at their own pace.
Carousels render full screen on phones and in a fixed-width card on tablets. Each step in a carousel uses the classic layout and supports the same [blocks](#blocks) and [properties](#properties) as other form factors.
| Setting | Description |
| --- | --- |
| Show step counter | Displays the guide's progress as users swipe between steps. |
| Step counter format | Choose **Numeric** (for example, `1/3`), **Verbose** (for example, `1 of 3`), or **Dots** to represent progress with indicator dots. |
### Card embed
Card embeds render guides and surveys as native elements within your UI. Use them for persistent content that should feel like part of your application rather than an overlay.
> **Note:** Unique identifier required
>
> Each card embed needs its own unique target identifier (mobile only). Use the same element tagging as pins and tooltips on most platforms (for example, `.amplitudeView` in SwiftUI). On Jetpack Compose, wrap the target in the `AmplitudeView` composable instead of the `.amplitudeView` modifier. Multiple card embeds can't share an identifier on the same screen. Sharing an identifier can cause cards not to render or to be positioned incorrectly.
Card embeds require a target element selector that specifies where to place the card. Go to [Element selector](#element-selector) for platform-specific targeting setup. Select from these position options to control how the card relates to the target element:
| Position | Description |
| --- | --- |
| Append to children (last child) | Inserts the card as the last child element within the target. |
| Prepend to children (first child) | Inserts the card as the first child element within the target. |
| Before element | Places the card immediately before the target element. |
| After element | Places the card immediately after the target element. |
| Replace element | Replaces the target element with the card. |
| Width | Choose **Auto** to let the card size to its content, **Fixed** to specify a pixel width, or **Full** to fill the container width. |
| Alignment | When width isn't **Full**, align the card to the **Left**, **Center**, or **Right** of its container. |
| Height | Choose **Auto** to let the card size to its content, **Fixed** to specify a pixel height, or **Full** to fill the container height. |
| Margin | Set the top, right, bottom, and left margin (in pixels) to control spacing between the card and surrounding UI elements. Margin differs from padding: margin controls external spacing around the card, while padding controls internal spacing within the card. |
Click the **three dot menu** to access format settings.
| Setting | Description |
| --- | --- |
| Content layout | Updates the visual ordering of the guide's content. |
| Actions bar | Updates the placement and layout of the guide's buttons. |
| Z-index | Specify a custom z-index value for the card. |
| Text animation | Enables the card's text to animate in with a typewriter effect. |
## Element selector
When you configure guides or surveys with pins, tooltips, card embeds, or element-based triggers, you must specify which element to target. How you specify the target depends on your platform.
### Web
The element selector helps you identify and target specific page elements using CSS selectors.
#### How the element selector works
Amplitude's visual element selector automatically identifies the most stable CSS selector for the element you choose, so your guide continues to work even if minor page changes occur.
To use the visual selector:
1. Click **Test and Preview** in the guide builder.
2. Navigate to the page containing your target element.
3. Click the element you want to target.
4. Amplitude automatically generates a CSS selector for that element.
##### Selecting nested elements
To select nested elements (elements inside other elements), use the Alt key (Option key on Mac) while hovering over elements:
1. Click **Test and Preview**.
2. Hover over the parent element.
3. Hold the Alt/Option key.
4. Continue hovering to drill down into nested child elements.
5. Click to select the nested element you want.
Use this method to target specific elements within complex page structures, such as buttons within cards or icons within menus.
#### Override or provide your own selector
To specify your own selector or get more control, manually enter a CSS or XPath selector:
1. In the element selector field, paste your CSS selector or XPath expression.
2. Choose your selection strategy:
- **CSS Selector**: Standard CSS selector syntax (for example, `#submit-button`, `.primary-cta`).
- **XPath**: XPath expression for more complex targeting (for example, `//button[@id='submit']`).
3. Optionally, add fallback text that Amplitude uses if the selector doesn't find a match.
4. Test your selector with **Test and Preview** to confirm it targets the correct element.
> **Tip:** Best practices for custom selectors
>
> - Use stable attributes like IDs or data attributes that are less likely to change.
> - Avoid selectors that depend on specific positioning (like `:nth-child`) unless necessary.
> - Test your selectors across different pages and screen sizes.
> - Add data attributes specifically for guide targeting to ensure reliability.
> - Use `:is()` to create flexible selectors that work across multiple similar elements.
**Examples of custom selectors:**
- CSS Selector: `.header-navigation > .menu-item:first-child`
- XPath: `//div[@class='container']//button[contains(text(), 'Submit')]`
- CSS with multiple elements: `:is([my-class="foo"],[my-class="bar"])`
> **Tip:**
>
> Amplitude supports most modern CSS selector features, including functional pseudo-classes like `:is()`, `:not()`, `:nth-of-type()`, and `:where()`, so you can create more expressive and flexible selectors.
#### Target elements in shadow DOM
The visual element selector can target elements inside open shadow DOMs directly. Select shadow DOM elements the same way as regular page elements — click the element during **Test and Preview**.
Keep these limitations in mind:
- **Open shadow DOMs only**: The shadow DOM must be in open mode. The element selector can't access closed shadow DOMs.
- **Card embeds not supported**: The card embed form factor doesn't work inside shadow DOMs. Use other form factors, such as popovers or pins, for content near shadow DOM elements.
> **Note:**
>
> If the target element doesn't exist in the DOM when the step renders, the pinned step doesn't display. Guides and Surveys doesn't support virtual targeting or auto-skipping for missing anchor elements.
### Mobile
Guides and surveys that use pins, tooltips, or card embeds require the SDK to target specific views on screen. Tag each target view with a unique identifier in your app, then use that string in the guide or survey builder's element selector field.
On Jetpack Compose, wrap card embed targets in the `AmplitudeView` composable. Pins and tooltips can use the `.amplitudeView` modifier.
Go to the element targeting section for your platform:
- [Guides and Surveys iOS SDK](https://amplitude.com/docs/sdks/guides-and-surveys/guides-and-surveys-ios-sdk#enable-element-targeting)
- [Guides and Surveys Android SDK](https://amplitude.com/docs/sdks/guides-and-surveys/guides-and-surveys-android-sdk#enable-element-targeting)
- [Guides and Surveys React Native SDK](https://amplitude.com/docs/sdks/guides-and-surveys/guides-and-surveys-rn-sdk#element-targeting)
- [Guides and Surveys Flutter SDK](https://amplitude.com/docs/sdks/guides-and-surveys/guides-and-surveys-flutter-sdk#element-targeting)
## Properties
These properties apply across form factors, so you can customize your guide components. Options available for each property may differ across form factors.
### Position
Position controls where the guide appears on screen.
| Form factor | Options |
| --- | --- |
| Modal | Top right, top center, top left, right center, bottom right, bottom center, bottom left, left center, center. |
| Popover | Top right, top center, top left, right center, bottom right, bottom center, bottom left, left center, center. |
| Pins | Controls position of the pin relative to the target element. Select the position and the alignment of the guide. For example, Position: `Bottom of target` and Alignment: `Left` places the guide below the target element, and aligns the guide's left side with the target's left side. |
| Tooltip | Specify the side of the target element where the info marker appears. Add vertical or horizontal offset as necessary. |
| Banner | Top or bottom of the page. Set the **Sticky** option to keep the banner visible while the user scrolls. Choose the Display style: **Inline** to display the banner within the contents of the page, or **Overlay** to float the banner on top of the page contents. |
| Card embed | Controls position relative to the target element. Select from **Append, Prepend, Before, After**, or **Replace**. Configure Width (**Auto, Fixed**, or **Full**), Alignment (**Left, Center**, or **Right**) when width isn't **Full**, Height (**Auto, Fixed**, or **Full**), and Margin (top, right, bottom, and left in pixels) to control spacing around the card. |
| Checklist header | Bottom left or Bottom right, in relation to the page. |
### Steps
Use steps to create multi-step guides. Break down processes into smaller, actionable steps that guide users from start to finish.
> **Tip:**
>
> Tooltips and Banners contain one step.
### Blocks
Blocks let you make your guide more engaging. Add a Button CTA, an image, or a video. Blocks align automatically based on the form factor and alignment you set.
#### Buttons
When you add a button, you can choose what happens when users click or tap it. Both primary and secondary buttons support all actions, including conditional logic.
| Action | Description |
| --- | --- |
| Visit link | Opens the specified website. For **web** guides and surveys, choose **Same tab** (opens in the current tab/screen), **New tab** (opens in a new browser tab), or **Use router**, which uses your configured router and requires [router configuration](https://amplitude.com/docs/sdks/guides-and-surveys/sdk#router-configuration). For **mobile** guides and surveys, choose **Open in In-App Browser** (opens the link within your app), **Open in Device Browser** (opens in the device's default browser), or **Use router**. |
| Click/Tap element | Specify an element on the page that receives a click event when the user clicks the button in the guide. |
| Show guide | Launch another guide. |
| Show survey | Launch a survey. |
| Go back | Go to the previous step in the guide. |
| Go forward | Advance to the next step in the guide. |
| Go to step | Go to the specified step in the guide. |
| Evaluate conditional logic | Execute different actions based on user properties or survey responses. Create conditions to personalize the button's behavior for different users. Go to [Conditional Logic](https://amplitude.com/docs/guides-and-surveys/conditional-logic) for more information. |
| Run callback | Trigger a callback function defined in your Guides and Surveys instrumentation. For more information, go to [Register a callback](https://amplitude.com/docs/sdks/guides-and-surveys/sdk#register-a-callback) |
| Submit app store rating request | Prompt the user to rate your app using the native in-app flow (App Store for iOS and Google Play for Android). The SDK calls the native rating API (StoreKit for iOS, Play In-App Review for Android). If the native API call itself returns an error (for example, no valid scene or activity) and you provide the app identifier in the survey configuration, the request falls back to the platform's app store page. If the call succeeds but the platform chooses not to show the rating dialog (due to rate limits, user opt-out, or other platform restrictions), the survey dismisses silently without opening the store page. |
| Open AI Assistant | Open the AI Assistant interface. |
| Open Resource Center | Open the Resource Center. |
| Open Document | Open a specified document. |
> **Note:**
>
> [Apple](https://developer.apple.com/documentation/storekit/requesting-app-store-reviews) and [Google](https://developer.android.com/guide/playcore/in-app-review) control their own native app review display and may override requests for review from your guide.
#### Mark step complete when
Only checklists have the **Mark step complete when** option. Amplitude marks a checklist step complete when one of the following activities occurs:
- `Button is clicked`
- `Page is visited`
- `Element is clicked`
- `Event is tracked`
For each option, the checklist step updates from "incomplete" to "complete" only if the action happens on the client while the checklist is visible. For example, if Amplitude tracks an event server side, or the event happens before the checklist is shown, the step isn't marked complete.
#### Image
Upload an image to include in your experience. The experience's layout determines the image's position.
#### Video
Paste the URL of a video (YouTube, Vimeo, Loom, Vidyard, or .MP4 file). Like images, layout determines the video's position.
================================================================================
# Templates
URL: https://amplitude.com/docs/guides-and-surveys/guide-templates
================================================================================
# Templates
When you create a new guide, start with a blank guide or use a template. Guides includes the following templates:
| Template | Use case |
| --- | --- |
| Tour | Guide users to explore your product. |
| Announcement | Share information with users, such as product changes, company updates, or new features. |
| Checklists | Help users complete tasks with step-by-step instructions. |
| Banners | Highlight important messages or alerts. |
| Tooltips | Provide quick tips or context for a specific element on screen. |
================================================================================
# Templates
URL: https://amplitude.com/docs/guides-and-surveys/templates
================================================================================
# Templates
Templates are reusable starting points for your team's guides and surveys. They include pre-configured designs, placeholder content, targeting, and themes to keep content consistent and reduce setup time.
## Key benefits
- Consistency: every team member follows the same design standards and messaging approach.
- Time-saving: skip repetitive setup work by starting with pre-built foundations.
- Standardization: branding, themes, and structure stay consistent across all guides and surveys.
- Team efficiency: team members get started with proven templates.
- Quality control: review and polish templates before releasing them to your team.
## Built-in Amplitude templates
Amplitude provides pre-built survey templates for common survey types. These templates appear in the _Create Survey_ menu:
- How did you hear about us: a two-step acquisition channel survey that identifies where new users discover your product. The first step asks users to select from common sources (social media, search engines, referrals, advertisements, or other). The second step collects more detail through an optional short-answer field.
- NPS (Net Promoter Score): measures how likely users are to recommend your product on a 0-10 scale. Track customer loyalty by identifying promoters (9-10), passives (7-8), and detractors (0-6), then calculate your overall NPS score. Use NPS for periodic health checks and benchmarking customer sentiment.
- User Feedback: a blank canvas for custom question sets. Use this template when you need tailored questions for specific research goals, qualitative insights, or exploratory feedback.
- Rating: quick reaction surveys using stars, numbers, or emojis. Use Rating to measure satisfaction at key moments (post-purchase, after feature use, support interactions) without disrupting the user experience.
- Banner Survey: surveys displayed as banners within your product. Use Banner Survey for broad reach without blocking the user flow, such as general announcements or low-priority feedback requests.
- Tooltip Survey: contextual surveys attached to specific UI elements. Use Tooltip Survey to gather feedback about particular features or flows where users interact with them.
You can customize built-in templates after creation to match your needs.
## Creating templates
##### Create a template from existing content
1. Open any existing guide or survey.
2. Click the three-dot menu next to the _Save_ button.
3. Click **Create a template** to copy the guide or survey as the base for your template.
New templates are hidden from non-admins by default, so you can polish them before releasing them to your team.
### Template visibility and management
When you edit a template, Amplitude displays a blue banner at the top of the page indicating that you're editing a template rather than a guide or survey.
## Building with templates
##### Using templates to create new content
1. Navigate to the _Create Guide_ or _Create Survey_ menu.
2. Your custom templates appear below the built-in Amplitude templates.
3. Select the template you want to use as your starting point.
4. Customize the content for your use case.
### Template best practices and tips
- Choose a theme before you release the template to your team. The template's theme applies to every new guide or survey created from it.
- Use clear naming. When you create a template, Amplitude appends "Template" to the name. When team members create guides or surveys from templates, Amplitude removes this suffix.
- Polish templates while they're hidden, before sharing them.
- Design templates with your team's common use cases in mind.
- Update templates as needed. Updates don't affect guides or surveys your team previously created from the template.
================================================================================
# Guides and Surveys iOS SDK
URL: https://amplitude.com/docs/sdks/guides-and-surveys/guides-and-surveys-ios-sdk
Updated: 2025-04-16
================================================================================
# Guides and Surveys iOS SDK
- **Package:** `AmplitudeEngagementSwift` ([cocoapods](https://cocoapods.org/pods/AmplitudeEngagementSwift))
- **Latest version:** 3.14.0
Amplitude's Guides and Surveys iOS SDK enables you to deploy [Guides and Surveys](https://amplitude.com/docs/guides-and-surveys) in your iOS applications.
## Install and verify
Follow these steps to install the SDK, connect your app to your Amplitude project, and confirm guides and surveys reach your app.
### Requirements
The Guides and Surveys iOS SDK requires:
- User devices on iOS 15 or higher.
- Swift 5.9+.
You can use Guides and Surveys independently of Amplitude Analytics.
### Install and initialize the SDK
Guides and Surveys supports different installation options to work best with your existing Amplitude implementation, if you have one.
#### Using Amplitude Analytics iOS SDK
If your app uses the [Amplitude Analytics iOS Swift SDK](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk), make sure you are using version 1.13.0 or later. Then install the Guides and Surveys iOS SDK with Swift Package Manager or CocoaPods.
#### Swift Package Manager
1. In Xcode, click _File > Add Package Dependencies..._
2. Enter the repository URL `https://github.com/amplitude/Amplitude-Engagement-Swift`
3. Select the `amplitude-engagement-swift` package.
4. Click **Add Package**.
#### CocoaPods
Add the following line to your Podfile, then run `pod install`.
```T
pod 'AmplitudeEngagementSwift', '~> 3.0.0'
```
> **Tip:** Amplitude recommends Swift Package Manager
>
> Use Swift Package Manager rather than CocoaPods for the most reliable installation experience. Swift Package Manager avoids potential issues with line endings and build configurations.
> **Note:**
>
> Find the latest release in the [Amplitude-Engagement-Swift](https://github.com/amplitude/Amplitude-Engagement-Swift) repository.
> **Warning:** Don't commit Pods directory to Git
>
> If you use CocoaPods, don't commit the `Pods/` directory to version control. Git applies line-ending normalization rules that can cause build errors. Add `Pods/` to your `.gitignore` file.
##### Initialize the SDK
Next, make sure to initialize the SDK.
```swift
import AmplitudeEngagementSwift
let API_KEY = "YOUR_API_KEY"
let configuration = Configuration(
apiKey: API_KEY
)
let amplitude = Amplitude(configuration: configuration)
amplitude.add(
plugin: AmplitudeEngagementPluginFactory.make(AmplitudeInitOptions())
)
// ----
// after calling `add`, the `engagement` SDK is available e.g. like this:
amplitude.engagement?.list()
```
This call uses the Amplitude Analytics iOS SDK's plugin system to integrate Guides and Surveys with your existing Analytics setup. Adding the plugin initializes Guides and Surveys alongside Analytics. Guides and Surveys shares the same API key and user identity, and communicates with Analytics directly. You don't need to call `boot` separately.
##### Configuration options
| 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 the EU data center. Default: `US`. |
| `initOptions.serverUrl` | `string` | Optional. Sets a custom server URL for API requests. Use this option for [proxy setups](https://amplitude.com/docs/guides-and-surveys/proxy). Default: `https://gs.amplitude.com` (US) or `https://gs.eu.amplitude.com` (EU). |
| `initOptions.cdnUrl` | `string` | Optional. Sets a custom CDN URL for static assets. Use this option for [proxy setups](https://amplitude.com/docs/guides-and-surveys/proxy). Default: `https://cdn.amplitude.com` (US) or `https://cdn.eu.amplitude.com` (EU). |
| `initOptions.mediaUrl` | `string` | Optional. Sets a custom URL for proxying nudge images. Use this option for [proxy setups](https://amplitude.com/docs/guides-and-surveys/proxy) when firewalls block images. Default: `https://engagement-static.amplitude.com` (US) or `https://engagement-static.eu.amplitude.com` (EU). |
| `initOptions.logLevel` | `LogLevel.None` or `LogLevel.Error` or `LogLevel.Warn` or `LogLevel.Verbose` or `LogLevel.Debug`. | Optional. Sets the log level. Default: `LogLevel.Warn`. |
| `initOptions.locale` | `string` | Optional. Sets the locale for [localization](#localization). Defaults to the device's system language (for example, `en`). Note that the default is a language code only, not a full locale identifier like `en-US`. |
> **Warning:** Use the same API key for Guides & Surveys and Analytics
>
> To avoid analytics mismatches and ensure accurate data collection, use the same API key for both Guides & Surveys and your Analytics SDK. Both should reference the same Amplitude project. Using different API keys can cause:
>
> - The SDK to fetch guides and surveys from the wrong project.
> - Analytics data to appear in different projects.
> - Insights and survey responses to be incomplete or mismatched.
>
> Make sure the API key you provide to Guides & Surveys matches the API key used to initialize your Amplitude Analytics SDK.
> **Note:**
>
> After you call `amplitude.add`, installation is complete. Continue to [Set up and verify preview mode](#set-up-and-verify-preview-mode) to confirm everything works.
#### Not using Amplitude Analytics Swift SDK 1.13.0+
If your app doesn't use the Amplitude Analytics iOS Swift SDK 1.13.0+, you can still install Guides and Surveys, but you need to call `.boot` directly instead of using the Analytics SDK plugin system.
> **Warning:** Required and recommended setup for this installation path
>
> - **Required**: Include `integrations` in your `boot` call to send Guides and Surveys events to your analytics provider. Without it, guide insights, survey insights, and survey responses won't appear.
> - **Strongly recommended**: Set up event forwarding using `forwardEvent` to enable the _On event tracked_ trigger. Without it, you can only trigger guides and surveys on screen load or other non-event conditions.
First, install the Guides and Surveys iOS SDK with Swift Package Manager or CocoaPods.
#### Swift Package Manager
1. In Xcode, click _File > Add Packages..._
2. Enter the repository URL `https://github.com/amplitude/Amplitude-Engagement-Swift`
3. Select the `Amplitude-Engagement-Swift` package, version `1.6.0`.
4. Click **Add Package**.
#### CocoaPods
Add the following line to your Podfile, then run `pod install`.
```T
pod 'AmplitudeEngagementSwift', '~> 1.6.0'
```
> **Tip:** Amplitude recommends Swift Package Manager
>
> Use Swift Package Manager rather than CocoaPods for the most reliable installation experience. Swift Package Manager avoids potential issues with line endings and build configurations.
> **Note:**
>
> Find the latest release in the [Amplitude-Engagement-Swift](https://github.com/amplitude/Amplitude-Engagement-Swift) repository.
> **Warning:** Don't commit Pods directory to Git
>
> If you use CocoaPods, don't commit the `Pods/` directory to version control. Git applies line-ending normalization rules that can cause build errors. Add `Pods/` to your `.gitignore` file.
##### Initialize the SDK
```swift
import AmplitudeEngagementSwift
let API_KEY = "YOUR_API_KEY"
let amplitudeEngagement = AmplitudeEngagementFactory.make(API_KEY)
```
##### Configuration options
| 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 the EU data center. Default: `US`. |
| `initOptions.serverUrl` | `string` | Optional. Sets a custom server URL for API requests. Use this option for [proxy setups](https://amplitude.com/docs/guides-and-surveys/proxy). Default: `https://gs.amplitude.com` (US) or `https://gs.eu.amplitude.com` (EU). |
| `initOptions.cdnUrl` | `string` | Optional. Sets a custom CDN URL for static assets. Use this option for [proxy setups](https://amplitude.com/docs/guides-and-surveys/proxy). Default: `https://cdn.amplitude.com` (US) or `https://cdn.eu.amplitude.com` (EU). |
| `initOptions.mediaUrl` | `string` | Optional. Sets a custom URL for proxying nudge images. Use this option for [proxy setups](https://amplitude.com/docs/guides-and-surveys/proxy) when firewalls block images. Default: `https://engagement-static.amplitude.com` (US) or `https://engagement-static.eu.amplitude.com` (EU). |
| `initOptions.logLevel` | `LogLevel.None` or `LogLevel.Error` or `LogLevel.Warn` or `LogLevel.Verbose` or `LogLevel.Debug`. | Optional. Sets the log level. Default: `LogLevel.Warn`. |
| `initOptions.locale` | `string` | Optional. Sets the locale for [localization](#localization). Defaults to the device's system language (for example, `en`). Note that the default is a language code only, not a full locale identifier like `en-US`. |
##### Boot the SDK
```swift
// Basic boot with user ID
amplitudeEngagement.boot("USER_ID")
// Advanced boot with options
let bootOptions = AmplitudeBootOptions(
user_id: "USER_ID",
device_id: "DEVICE_ID",
user_properties: ["key": "value"]
integrations: [
{ event, eventProperties in
// Custom event handler
}
]
)
amplitudeEngagement.boot(options: bootOptions)
```
> **Note:**
>
> After you call `amplitudeEngagement.boot`, installation is complete. Continue to [Set up and verify preview mode](#set-up-and-verify-preview-mode) to confirm everything works.
### Add your application to project settings
After installing the SDK, add your iOS application to your Amplitude project settings so it appears as a platform option when you create guides and surveys.
To add your application:
1. Navigate to _Settings > Projects_ in Amplitude.
2. Select your project.
3. Navigate to the **Guides and Surveys** tab.
4. In the **App Management** section, expand and click **+ Add App**.
5. Select **iOS** from the dropdown.
After you add your application, you can select it as a platform option when you create or edit guides and surveys for your iOS app users.
### Set up and verify preview mode
Preview guides and surveys directly in your application to view the same experience your users receive. Previewing makes it easier to iterate on copy, targeting rules, and trigger logic, and confirms your installation is working.
#### Locate the mobile URL scheme
To locate the URL scheme:
1. Navigate to _Settings > Projects_ in Amplitude.
2. Select your project.
3. Navigate to the **General** tab.
4. Find the **URL scheme (mobile)** field.
5. Copy its value, for example, `amp-abcdefgh12345678`.
#### Add the URL scheme in Xcode
1. Open your iOS project in Xcode.
2. In the Project navigator, select your app's target.
3. On the **Info** tab, locate or add the **URL Types** section.
4. Add a new URL type with the following values:
- **URL identifier**: Provide a descriptive name, like `AmplitudeURLScheme`.
- **URL Schemes**: Paste the value you copied from Amplitude, for example `amp-abc123`.
#### Configure URL handling for preview links
```swift
// In your AppDelegate or SceneDelegate
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
if amplitudeEngagement.handleUrl(url) {
return true
}
// Handle other URL schemes
return false
}
```
#### Verify your installation with a QR code scan
Confirm your installation works end to end:
1. In Amplitude, open a guide or survey and click **Preview**.
2. Scan the displayed QR code with your device's camera, or open the preview URL on a device that has your app installed.
3. Confirm the guide or survey opens inside your app.
4. Look for a small Amplitude logo at the bottom of the screen, and tap it to open the Super Debugger. Refer to [Super Debugger](#super-debugger) for what to check there.
If the preview doesn't open in your app, or the logo doesn't appear, review the URL scheme setup steps above before continuing.
## Reference
### Set a minimum SDK version (when needed)
SDK versions `3.0.0` and later support `Minimum SDK version`. Use this setting as a safety control when you identify a critical issue in an older SDK release.
To configure a minimum SDK version:
1. Navigate to _Settings > Projects_ in Amplitude.
2. Select your project.
3. Navigate to the **Guides and Surveys** tab.
4. In the **App Management** section, expand and click **+ Add App**.
5. Select **iOS** from the dropdown.
6. Enter a value in **Minimum SDK version**.
When you set this value, Guides and Surveys compares the configured minimum with the SDK version in each app build:
- If an app build uses an older SDK version, the SDK doesn't initialize in that build.
- If an app build uses the same or newer SDK version, the SDK initializes as expected.
Use this setting to stop guides and surveys on known problematic SDK versions without rolling back your application release.
#### Example usage of minimum SDK version
Suppose app version `120` uses Guides and Surveys SDK `3.0.2`, and app version `121` uses Guides and Surveys SDK `3.1.0` with a bug fix. If you set **Minimum SDK version** to `3.1.0`:
- App version `120` no longer loads Guides and Surveys.
- App version `121` continues to load Guides and Surveys.
### Troubleshoot installation
#### Troubleshoot version upgrade in Swift Package Manager
If you upgrade the SDK version but still see unexpected behavior, Xcode may be using cached build artifacts from the previous version. To clear the SPM cache:
1. In your command-line interface (for example, Terminal) or file management app (for example, Finder), navigate to `~/Library/Caches/org.swift.swiftpm/repositories`.
2. Delete the folder and lock file related to the Amplitude Engagement Swift package.
3. In Xcode, run _File > Swift Packages > Reset Package Caches_.
4. Then, run _File > Packages > Resolve Package Versions_.
If the issue persists, try the following to reset the entire cache:
```bash
rm -rf ~/Library/Caches/org.swift.swiftpm
rm -rf ~/Library/org.swift.swiftpm
rm -rf ~/Library/Developer/Xcode/DerivedData
```
#### Troubleshoot CocoaPods installation
If you see the error `Error extracting version from module interface` when importing `AmplitudeEngagementSwift` with CocoaPods, the issue is likely caused by incorrect line endings in `.swiftinterface` files. Git configurations such as `core.autocrlf` may rewrite these files from LF to CRLF line endings.
To fix this issue, add these lines to your `.gitattributes` file in your project root:
```text
*.swiftinterface text eol=lf
Pods/** -text
```
After adding these lines, clean your build folder and rebuild your project.
### Screen tracking and element targeting
Screen tracking and element targeting are optional, but they help make guides and surveys more targeted.
#### Enable screen tracking
Call `screen` for screen-based targeting and the Time on Screen trigger. Guides and Surveys compares the screen string (for example, "HomeScreen") with the string in the guide or survey page targeting section.
```swift
// Track screen views to trigger guides based on screens
amplitudeEngagement.screen("HomeScreen")
```
> **Warning:**
>
> `Screen Viewed` events from the Amplitude iOS Swift SDK's [Autocapture feature](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk#autocapture) are auto-forwarded to the Engagement SDK.
#### Enable element targeting
Pin, tooltip, and card embed guides require the SDK to target specific elements on screen. To enable element targeting in your app, give the element a unique identifier.
```swift
// Swift UI
MySwiftView {
// Content
}
.amplitudeView("MySwiftView", onTrigger: {
// Optional code to run with tap element action
})
// UIKit: set an accessibility identifier so the SDK can target the view
let myView = MyUIKitView(...)
myView.accessibilityIdentifier = "MyView"
let tapGesture = UITapGestureRecognizer(target: self, action: #selector(myButtonAction))
myView.addGestureRecognizer(tapGesture)
myView.isUserInteractionEnabled = true
// Note: To use the tap element action from a guide or survey on your UIKit view,
// explicitly add a target to the view in addition to any gesture recognizers you may have added.
myView.addTarget(self, action: #selector(myButtonAction), for: .touchUpInside)
@objc func myButtonAction() {
// Optional code to run on tap / tap element action
}
```
### Localization
Set the `locale` option during initialization to localize a guide or survey. If you don't set a language or locale, Amplitude uses the default language.
```swift
// Set locale during initialization
let configuration = Configuration(apiKey: API_KEY)
amplitude.add(
plugin: AmplitudeEngagementPluginFactory.make(
AmplitudeInitOptions(locale: "fr-FR")
)
)
```
To dynamically update the language after the SDK initializes, use the `updateLanguage` method. Calling `updateLanguage` re-fetches the configuration with the new locale.
| Parameter | Type | Description |
| --- | --- | --- |
| `locale` | `string` | Required. The locale identifier (for example, `en-US`, `fr-FR`, `es-ES`) used for localization. You can also use language codes like `en`, `es`, or `fr`. |
```swift
// Example: Update language to French with full locale
amplitudeEngagement.updateLanguage("fr-FR")
// Example: Update language to English with language code
amplitudeEngagement.updateLanguage("en")
```
### Other SDK methods
#### Enable and disable the SDK
Use `disable()` to temporarily prevent guides and surveys from appearing and hide any currently visible ones. Use `enable()` to resume normal operation.
```swift
// Temporarily disable the SDK
amplitudeEngagement.disable()
// Re-enable the SDK
amplitudeEngagement.enable()
```
#### Refresh targeting data
Use `refresh()` to re-fetch targeting evaluation from Amplitude after user property updates. The SDK skips the refresh if a guide or survey is visible.
```swift
amplitudeEngagement.refresh()
```
#### Set the auto-refresh interval
Enables periodic refresh of targeting data. You can call this after boot to change or disable the interval. The minimum interval is 60 seconds when enabled. Set to `0` or a negative value to disable.
```swift
amplitudeEngagement.setAutoRefreshInterval(seconds: 3600) // Every hour
amplitudeEngagement.setAutoRefreshInterval(seconds: 0) // Disable
```
| Parameter | Type | Description |
| --- | --- | --- |
| `seconds` | `Int` | Required. The interval in seconds. Must be `60` or greater if enabled. Set to `0` or a negative value to disable auto-refresh. |
#### Manage themes
Configure the visual theme mode if your app supports light and dark modes.
```swift
// Set the theme mode
amplitudeEngagement.setThemeMode(ThemeMode.DARK) // Options: AUTO, LIGHT, DARK
```
#### Register a callback
Set the Run callback action on a guide or survey button to execute the callback.
```swift
engagement.addCallback(_ key: String, _ function: () -> Void)
```
| Parameter | Type | Description |
| --- | --- | --- |
| `key` | `String` | Required. Refer to this callback by key when setting a callback action on a guide or survey. |
| `function` | `() -> Void` | Required. The callback to execute. |
```swift
engagement.addCallback("show-alert") {
DispatchQueue.main.async {
let alert = UIAlertController(
title: "Callback",
message: "Callback has been executed!",
preferredStyle: .alert
)
alert.addAction(UIAlertAction(title: "OK", style: .default))
viewController.present(alert, animated: true)
}
}
```
#### Router configuration
Configure how Guides and Surveys handles screen navigation.
```swift
engagement.setRouter { identifier in
// Your screen handling and navigation
}
```
| Parameter | Type | Description |
| --- | --- | --- |
| `identifier` | `String` | Required. A screen identifier (or route) that tells your app where to navigate. |
| `router` (closure) | `(String) -> Void` | Required. A function (closure) you implement to handle screen navigation when Guides or Surveys need to change screens. |
> **Note:** Update link behavior
>
> After you configure the router with `setRouter()`, update the link behavior setting in the Guides and Surveys interface. For any link actions in your guides or surveys, change the behavior to **Use router**. The guide or survey then uses the custom router function instead of the default browser navigation.
To remove the router, call `unsetRouter()`.
```swift
amplitudeEngagement.unsetRouter()
```
#### Reset
Reset a guide or survey to a specific step.
```swift
amplitudeEngagement.reset(key: "GUIDE_KEY", stepIndex: 0)
```
| 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.
```swift
let guidesAndSurveys = amplitudeEngagement.list()
```
#### Show
Display a specific guide or survey. Ignores any targeting rules and limits except for screen targeting.
```swift
amplitudeEngagement.show(key: "GUIDE_KEY")
```
| Parameter | Type | Description |
| --- | --- | --- |
| `key` | `string` | Required. The guide or survey's key. |
#### Forward event
If you don't use the Amplitude Analytics iOS SDK plugin (that is, you called `boot` directly), use `forwardEvent` to enable the _On event tracked_ trigger in Guides and Surveys. Forwarded events aren't sent to Amplitude servers. The SDK uses them only for local trigger evaluation.
> **Tip:** Strongly recommended for this installation path
>
> Amplitude strongly recommends setting up event forwarding when not using the Amplitude Analytics iOS SDK plugin. Without it, you can't use the _On event tracked_ trigger, which limits your ability to show guides and surveys based on user behavior in your app.
```swift
amplitudeEngagement.forwardEvent([
"event_type": "my event type",
"event_properties": [String: String]()
])
```
#### Reset smart interactions
Call `resetSmartInteractions()` to clear any cached state from smart interaction detectors, including rage-tap, user inactivity, and element-tap detection.
```swift
amplitudeEngagement.resetSmartInteractions()
```
#### Close all
Close all active guides and surveys.
```swift
amplitudeEngagement.closeAll()
```
### Super Debugger
When you scan a preview QR code from the Amplitude dashboard, a small Amplitude logo appears at the bottom of your screen. Tap it to open the Super Debugger panel.
The Super Debugger has two tabs: **Details** and **Setup**.
#### Details tab
The _Details_ tab shows information about the guide or survey you're previewing and lets you inspect and control the preview session.
**Guide / Survey**: The name of the active guide or survey. Tap it to switch to a different guide or survey.
**Details**:
- **Step**: The current step number out of the total (for example, "1 of 3"). Tap the copy icon to copy the value.
- **User**: The user ID for the preview session. Tap the copy icon to copy it.
- **Screen**: The screen name the SDK currently reports. Tap the copy icon to copy it.
**Debug**: Shows whether the guide or survey passes each condition check. Each row expands to show details:
- **Limits**: Whether the guide or survey reached its display limit. Expand to review the configured limit.
- **Trigger**: Whether the guide or survey meets the trigger condition. Expand to review the trigger type, screen conditions, and pin target element (if applicable).
- **Throttle**: Whether the guide or survey meets the throttle condition. Expand to review the throttle setting. Toggle **Ignore limits** to bypass throttle limits during your preview session.
**Advanced**:
- **Pin Debugging**: Expand to enable **Reposition pins every 5 seconds**. The debugger periodically re-evaluates pin positions to help debug pin placement on dynamic layouts.
At the bottom of the panel:
- **Restart Preview**: Resets the guide or survey to its first step and restarts the preview.
- **Close Preview**: Exits preview mode and dismisses the Super Debugger.
#### Setup tab
The _Setup_ tab shows SDK configuration and environment details for the current session.
**SDK Versions**: The version of the Engagement SDK installed in your app.
**Installation**:
- **Type**: The SDK installation method (for example, Plugin or standalone).
- **Configuration**: The number and type of custom configuration options applied.
**User**:
- **User ID**: The user ID passed to the SDK on boot.
- **Properties**: Any user properties set for the current session.
**Event Flow**: Confirms whether events are flowing correctly:
- **Events flowing into Guides and Surveys SDK**: Events from your analytics instance reach the Engagement SDK.
- **Events flowing out of Guides and Surveys SDK**: The Engagement SDK sends events to Amplitude.
#### Support
Tap the **?** button to open the _Support_ panel. From here you can:
- Open links to the SDK documentation and Guides and Surveys overview.
- **File Bug Report**: Submit a bug report directly from the debugger. Fill in steps to reproduce, expected results, and actual results, then tap **Send**.
### Known limitations
#### No offline support
The SDK requires an active internet connection to fetch and display guides and surveys. If a device is offline when the app first loads, guides and surveys don't display for that app session.
#### Tab bar element targeting
Pins and tooltips can't target tab bar items (for example, `UITabBar` elements). Tab bars use system-level components that exist outside the standard view hierarchy, which prevents the SDK from reliably locating and attaching guides to these elements.
> **Tip:** Workaround
>
> Use screen-based targeting or event-based triggers to show guides when users navigate to specific tabs. Do not pin directly to tab bar items.
#### Targeting animated elements and elements inside moving containers
Pins and tooltips can't target views or elements that are:
- Animated or in an animated container (they move around the screen).
- In a container that can move based on user interaction.
> **Note:** Note
>
> Scrollviews usually work.
> **Tip:** Workaround
>
> Use screen-based targeting or event-based triggers to show guides, perhaps with a delay to ensure any animations have completed. Don't pin directly to elements in animated containers or containers that can move through user interaction.
#### Card embeds anchored to a SwiftUI GridRow
When a card embed is active on an element that's a SwiftUI `GridRow`, the SDK wraps the row and the card together so the card can render inline. That wrapper prevents the parent `Grid` from recognizing the row, so the row's cells collapse into a single column while the card displays. Plain element targeting on a `GridRow`—for tooltips, pins, and tap actions—isn't affected.
> **Tip:** Workaround
>
> Anchor card embeds to a regular element rather than a `GridRow`. For example, tag a view inside the row, or a container outside the `Grid`.
### Changelog
Go to the [Mobile SDK changelog](https://amplitude.com/docs/sdks/guides-and-surveys/guides-and-surveys-mobile-sdk-changelog).
================================================================================
# Guides and Surveys Android SDK
URL: https://amplitude.com/docs/sdks/guides-and-surveys/guides-and-surveys-android-sdk
Updated: 2025-04-16
================================================================================
# Guides and Surveys Android SDK
- **Package:** `com.amplitude:amplitude-engagement-android` ([maven](https://search.maven.org/artifact/com.amplitude/amplitude-engagement-android))
- **Latest version:** 3.14.0
Amplitude's Guides and Surveys Android SDK enables you to deploy [Guides and Surveys](https://amplitude.com/docs/guides-and-surveys) in your Android applications.
## Install and verify
Follow these steps to install the SDK, connect your app to your Amplitude project, and confirm guides and surveys reach your app.
### Requirements
The Guides and Surveys Android SDK requires:
- Android API Level 24 (Android 7.0)+.
- Kotlin 1.8.22+.
You can use Guides and Surveys independently of Amplitude Analytics.
### Install and initialize the SDK
Guides and Surveys supports different installation options to work best with your existing Amplitude implementation, if you have one.
#### Using Amplitude Analytics Android-Kotlin SDK
If your app uses the [Amplitude Analytics Android-Kotlin SDK](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk), make sure you are using version 1.0 or later. Then add the following dependencies to your application's `build.gradle.kts` file:
```kotlin
dependencies {
// Amplitude Engagement SDK
implementation("com.amplitude:amplitude-engagement-android:3.+")
// Amplitude Analytics SDK (required dependency)
implementation("com.amplitude:analytics-android:1.+")
}
```
##### Initialize the SDK
```kotlin
import com.amplitude.android.engagement.AmplitudeEngagement
import com.amplitude.android.engagement.AmplitudeInitOptions
// Initialize the SDK
val amplitudeEngagement = AmplitudeEngagement(
context = applicationContext,
apiKey = "YOUR_API_KEY",
options = AmplitudeInitOptions()
)
// Add the plugin to your Amplitude instance
val amplitude = Amplitude(applicationContext)
amplitude.add(amplitudeEngagement.getPlugin())
```
This call uses the Amplitude Analytics Android SDK's plugin system to integrate Guides and Surveys with your existing Analytics setup. Adding the plugin initializes Guides and Surveys alongside Analytics. Guides and Surveys shares the same API key and user identity, and communicates with Analytics directly. You don't need to call `boot` separately.
##### Configuration options
| 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 the EU data center. Default: `US`. |
| `initOptions.serverUrl` | `string` | Optional. Sets a custom server URL for API requests. Use this option for [proxy setups](https://amplitude.com/docs/guides-and-surveys/proxy). Default: `https://gs.amplitude.com` (US) or `https://gs.eu.amplitude.com` (EU). |
| `initOptions.cdnUrl` | `string` | Optional. Sets a custom CDN URL for static assets. Use this option for [proxy setups](https://amplitude.com/docs/guides-and-surveys/proxy). Default: `https://cdn.amplitude.com` (US) or `https://cdn.eu.amplitude.com` (EU). |
| `initOptions.mediaUrl` | `string` | Optional. Sets a custom URL for proxying nudge images. Use this option for [proxy setups](https://amplitude.com/docs/guides-and-surveys/proxy) when firewalls block images. Default: `https://engagement-static.amplitude.com` (US) or `https://engagement-static.eu.amplitude.com` (EU). |
| `initOptions.logLevel` | `LogLevel.None` or `LogLevel.Error` or `LogLevel.Warn` or `LogLevel.Verbose` or `LogLevel.Debug`. | Optional. Sets the log level. Default: `LogLevel.Warn`. |
| `initOptions.locale` | `string` | Optional. Sets the locale for [localization](#localization). Defaults to the device's system language (for example, `en`). Note that the default is a language code only, not a full locale identifier like `en-US`. |
> **Warning:** Use the same API key for Guides & Surveys and Analytics
>
> To avoid analytics mismatches and ensure accurate data collection, use the same API key for both Guides & Surveys and your Analytics SDK. Both should reference the same Amplitude project. Using different API keys can cause:
>
> - The SDK to fetch guides and surveys from the wrong project.
> - Analytics data to appear in different projects.
> - Insights and survey responses to be incomplete or mismatched.
>
> Make sure the API key you provide to Guides & Surveys matches the API key used to initialize your Amplitude Analytics SDK.
> **Note:**
>
> After you call `amplitude.add`, installation is complete. Continue to [Set up and verify preview mode](#set-up-and-verify-preview-mode) to confirm everything works.
#### Not using Amplitude Analytics Android-Kotlin SDK 1.0+
If your app doesn't use the Amplitude Analytics Android-Kotlin SDK 1.0+, you can still install Guides and Surveys, but you need to call `.boot` directly instead of using the Analytics SDK plugin system.
> **Warning:** Required and recommended setup for this installation path
>
> - **Required**: Include `integrations` in your `boot` call to send Guides and Surveys events to your analytics provider. Without it, guide insights, survey insights, and survey responses won't appear.
> - **Strongly recommended**: Set up event forwarding using `forwardEvent` to enable the _On event tracked_ trigger. Without it, you can only trigger guides and surveys on screen load or other non-event conditions.
Add the following dependencies to your application's `build.gradle.kts` file:
```kotlin
dependencies {
// Amplitude Engagement SDK
implementation("com.amplitude:amplitude-engagement-android:2.+")
}
```
##### Initialize the SDK
```kotlin
import com.amplitude.android.engagement.AmplitudeEngagement
import com.amplitude.android.engagement.AmplitudeInitOptions
// Initialize the SDK
val amplitudeEngagement = AmplitudeEngagement(
context = applicationContext,
apiKey = "YOUR_API_KEY",
options = AmplitudeInitOptions()
)
```
##### Configuration options
| 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 the EU data center. Default: `US`. |
| `initOptions.serverUrl` | `string` | Optional. Sets a custom server URL for API requests. Use this option for [proxy setups](https://amplitude.com/docs/guides-and-surveys/proxy). Default: `https://gs.amplitude.com` (US) or `https://gs.eu.amplitude.com` (EU). |
| `initOptions.cdnUrl` | `string` | Optional. Sets a custom CDN URL for static assets. Use this option for [proxy setups](https://amplitude.com/docs/guides-and-surveys/proxy). Default: `https://cdn.amplitude.com` (US) or `https://cdn.eu.amplitude.com` (EU). |
| `initOptions.mediaUrl` | `string` | Optional. Sets a custom URL for proxying nudge images. Use this option for [proxy setups](https://amplitude.com/docs/guides-and-surveys/proxy) when firewalls block images. Default: `https://engagement-static.amplitude.com` (US) or `https://engagement-static.eu.amplitude.com` (EU). |
| `initOptions.logLevel` | `LogLevel.None` or `LogLevel.Error` or `LogLevel.Warn` or `LogLevel.Verbose` or `LogLevel.Debug`. | Optional. Sets the log level. Default: `LogLevel.Warn`. |
| `initOptions.locale` | `string` | Optional. Sets the locale for [localization](#localization). Defaults to the device's system language (for example, `en`). Note that the default is a language code only, not a full locale identifier like `en-US`. |
> **Warning:** Use the same API key for Guides & Surveys and Analytics
>
> To avoid analytics mismatches and ensure accurate data collection, use the same API key for both Guides & Surveys and your Analytics SDK. Both should reference the same Amplitude project. Using different API keys can cause:
>
> - The SDK to fetch guides and surveys from the wrong project.
> - Analytics data to appear in different projects.
> - Insights and survey responses to be incomplete or mismatched.
>
> Make sure the API key you provide to Guides & Surveys matches the API key used to initialize your Amplitude Analytics SDK.
##### Boot the SDK
```kotlin
// Basic boot with user ID
amplitudeEngagement.boot("USER_ID")
// Advanced boot with options
let bootOptions = AmplitudeBootOptions(
userId: "USER_ID",
deviceId: "DEVICE_ID",
userProperties: mapOf("key" to "value")
integrations = arrayOf({ event: BaseEvent ->
// Custom event handler
// Dummy example here:
println("event: ${event.eventType} properties: ${event.eventProperties}")
})
)
amplitudeEngagement.boot(options: bootOptions)
```
> **Note:**
>
> After you call `amplitude.boot`, installation is complete. Continue to [Set up and verify preview mode](#set-up-and-verify-preview-mode) to confirm everything works.
### Add your application to project settings
After installing the SDK, add your Android application to your Amplitude project settings so it appears as a platform option when you create guides and surveys.
To add your application:
1. Navigate to _Settings > Projects_ in Amplitude.
2. Select your project.
3. Navigate to the **Guides and Surveys** tab.
4. In the **App Management** section, expand and click **+ Add App**.
5. Select **Android** from the dropdown.
After you add your application, you can select it as a platform option when you create or edit guides and surveys for your Android app users.
### Set up and verify preview mode
Preview guides and surveys directly in your application to view the same experience your users receive. Previewing makes it easier to iterate on copy, targeting rules, and trigger logic, and confirms your installation is working.
#### Locate the mobile URL scheme
To locate the URL scheme:
1. Navigate to _Settings > Projects_ in Amplitude.
2. Select your project.
3. Navigate to the **General** tab.
4. Find the **URL scheme (mobile)** field.
5. Copy its value, for example, `amp-abcdefgh12345678`.
#### Add the URL scheme in Android Studio
Add the following intent filter to the main activity to your project's `AndroidManifest.xml` file:
```xml
```
#### URL handling for preview links
```kotlin
// In your Activity
override fun onNewIntent(intent: Intent?) {
super.onNewIntent(intent)
amplitudeEngagement.handleLinkIntent(intent)
}
```
#### Verify your installation with a QR code scan
Confirm your installation works end to end:
1. In Amplitude, open a guide or survey and click **Preview**.
2. Scan the displayed QR code with your device's camera, or open the preview URL on a device that has your app installed.
3. Confirm the guide or survey opens inside your app.
4. Look for a small Amplitude logo at the bottom of the screen, and tap it to open the Super Debugger. Refer to [Super Debugger](#super-debugger) for what to check there.
If the preview doesn't open in your app, or the logo doesn't appear, review the URL scheme setup steps above before continuing.
## Reference
### Set a minimum SDK version (when needed)
SDK versions `3.0.0` and later support `Minimum SDK version`. Use this setting as a safety control when you identify a critical issue in an older SDK release.
To configure a minimum SDK version:
1. Navigate to _Settings > Projects_ in Amplitude.
2. Select your project.
3. Navigate to the **Guides and Surveys** tab.
4. In the **App Management** section, expand and click **+ Add App**.
5. Select **Android** from the dropdown.
6. Enter a value in **Minimum SDK version**.
When you set this value, Guides and Surveys compares the configured minimum with the SDK version in each app build:
- If an app build uses an older SDK version, the SDK doesn't initialize in that build.
- If an app build uses the same or newer SDK version, the SDK initializes as expected.
Use this setting to stop guides and surveys on known problematic SDK versions without rolling back your application release.
#### Example usage of minimum SDK version
Suppose app version `120` uses Guides and Surveys SDK `3.0.2`, and app version `121` uses Guides and Surveys SDK `3.1.0` with a bug fix. If you set **Minimum SDK version** to `3.1.0`:
- App version `120` no longer loads Guides and Surveys.
- App version `121` continues to load Guides and Surveys.
### Screen tracking and element targeting
#### Enable screen tracking
Call `screen` for screen-based targeting and the Time on Screen trigger. Guides and Surveys compares the screen string (for example, "HomeScreen") with the string in the guide or survey page targeting section.
```kotlin
// Track screen views to trigger guides based on screens
amplitudeEngagement.screen("HomeScreen")
```
> **Warning:**
>
> `Screen Viewed` events from the Amplitude Android-Kotlin SDK's [Autocapture feature](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk#autocapture) are auto-forwarded to the Engagement SDK.
#### Enable element targeting
Pin, tooltip, and card embed guides require the SDK to target specific elements on screen.
##### Jetpack Compose pins and tooltips
Use Amplitude Engagement's `.amplitudeView` modifier to tag Jetpack Compose views for pins and tooltips. Pass your instance of `AmplitudeEngagement` as a parameter to `.amplitudeView`. Configure a `CompositionLocalProvider` and access it in your view hierarchy or pass your instance as a parameter to your composable views.
```kotlin
// Jetpack Compose tagging for pins and tooltips
@Composable
fun MyView() {
// Use your instance of Amplitude Engagement by creating a Composition context or passing as a param
val engagement = LocalEngagement.current
Box {
Button(
modifier = Modifier.amplitudeView(
engagement,
tag = "my-button",
onTrigger = {
// Optional code to run with tap element action
}
)
)
}
}
```
##### Jetpack Compose card embeds
Card embeds need the `AmplitudeView` composable, not the `.amplitudeView` modifier. `AmplitudeView` wraps your content so the SDK can insert the card before, after, or in place of the target. A modifier can't insert sibling content in the parent layout.
In the following example, use `welcome-banner` as the element targeting string in the Guides and Surveys dashboard.
```kotlin
import com.amplitude.android.engagement.ui.anchoring.AmplitudeView
@Composable
fun MyView() {
val engagement = LocalEngagement.current
AmplitudeView(
engagement = engagement,
tag = "welcome-banner",
) {
Text("Welcome")
}
}
```
##### ProGuard rules for Jetpack Compose
If you enable ProGuard or R8 code shrinking in release builds, add rules to your app's `proguard-rules.pro` file (or equivalent ProGuard configuration). Shrinking can remove Jetpack Compose metadata and annotations that the Guides and Surveys SDK uses to resolve element tags and place pins, tooltips, and card embeds on Compose elements.
Add the following to your ProGuard configuration:
```proguard
-keepclassmembers class androidx.compose.ui.platform.AndroidComposeView {
androidx.compose.ui.semantics.SemanticsOwner semanticsOwner;
}
# Keep Jetpack Compose runtime and compiler tags
# (This allows analytics tools to read composable structures)
-keep class androidx.compose.runtime.** { *; }
-keepclassmembers class * {
@androidx.compose.runtime.* ;
@androidx.compose.runtime.* ;
}
-keepnames class androidx.compose.ui.platform.** { *; }
# Keep attributes required for UI inspection and layout reflection
-keepattributes *Annotation*,Signature,InnerClasses,EnclosingMethod
-keepclassmembers class * {
@com.amplitude.** ;
@com.amplitude.** ;
}
```
Without these rules, pins, tooltips, and card embeds may not attach to the correct target elements in Jetpack Compose screens.
##### Non-Jetpack Compose
Guides and Surveys also supports non-Jetpack Compose views. The SDK uses the `tag`, `contentDescription`, or `resourceName` fields to check for a matching selector. You need to set only one of these.
Configure this in your existing layout XMLs or programmatically by setting the properties on the view instance.
```xml
```
```kotlin
// Non Jetpack Compose Programmatic Tagging
val button = Button(this)
// Set the contentDescription
button.contentDescription = "my-button"
// Or set the tag
button.tag = "my-button"
```
### Localization
Set the `locale` option during initialization to localize a guide or survey. If you don't set a language or locale, Amplitude uses the default language.
```kotlin
// Set locale during initialization
val amplitudeEngagement = AmplitudeEngagement(
context = applicationContext,
apiKey = "YOUR_API_KEY",
options = AmplitudeInitOptions(locale = "fr-FR")
)
```
To dynamically update the language after the SDK initializes, use the `updateLanguage` method. Calling `updateLanguage` re-fetches the configuration with the new locale.
```kotlin
amplitudeEngagement.updateLanguage(locale: String)
```
| Parameter | Type | Description |
| --- | --- | --- |
| `locale` | `string` | Required. The locale identifier (for example, `en-US`, `fr-FR`, `es-ES`) used for localization. You can also use language codes like `en`, `es`, or `fr`. |
```kotlin
// Example: Update language to French with full locale
amplitudeEngagement.updateLanguage("fr-FR")
// Example: Update language to English with language code
amplitudeEngagement.updateLanguage("en")
```
### Other SDK methods
The Android SDK for Amplitude Guides and Surveys includes these additional methods:
- **Lifecycle**: Use `enable()` and `disable()` to temporarily pause or resume guides and surveys.
- **Targeting refresh**: Use `refresh()` to manually refresh targeting data. Use `setAutoRefreshInterval()` to change or disable the auto-refresh interval after boot.
- **Managing themes**: Use `setThemeMode` to set the visual theme (light, dark, or auto) for guides and surveys.
- **Adding callbacks**: Register named callbacks and trigger them from guides or surveys using the Run callback action to execute custom app logic.
- **Router configuration**: Define a router callback with `setRouter` to customize how guides and surveys handle screen navigation in your app.
- **Resetting guides/surveys**: Use `reset` to move a guide or survey back to a specific step.
- **Listing guides/surveys**: Retrieve the full list of live guides and surveys and their current status using the `list()` method.
- **Smart interactions**: Use `resetSmartInteractions()` to clear cached rage-tap, inactivity, and element-tap state.
#### Enable and disable the SDK
Use `disable()` to temporarily prevent guides and surveys from appearing and hide any currently visible ones. Use `enable()` to resume normal operation.
```kotlin
// Temporarily disable the SDK
amplitudeEngagement.disable()
// Re-enable the SDK
amplitudeEngagement.enable()
```
#### Refresh targeting data
Use `refresh()` to re-fetch targeting evaluation from Amplitude after user property updates. The SDK skips the refresh if a guide or survey is visible.
```kotlin
amplitudeEngagement.refresh()
```
#### Set the auto-refresh interval
Enables periodic refresh of targeting data. You can call this after boot to change or disable the interval. The minimum interval is 60 seconds when enabled. Set to `0` or a negative value to disable.
```kotlin
amplitudeEngagement.setAutoRefreshInterval(seconds = 3600) // Every hour
amplitudeEngagement.setAutoRefreshInterval(seconds = 0) // Disable
```
| Parameter | Type | Description |
| --- | --- | --- |
| `seconds` | `Int` | Required. The interval in seconds. Must be `60` or greater if enabled. Set to `0` or a negative value to disable auto-refresh. |
#### Manage themes
Configure the visual theme mode if your app supports light and dark modes.
```kotlin
// Set the theme mode
amplitudeEngagement.setThemeMode(ThemeMode.DARK) // Options: AUTO, LIGHT, DARK
```
#### Register a callback
Set the Run callback action on a guide or survey button to execute the callback.
```kotlin
engagement.addCallback(key: String, func: () -> Unit)
```
| Parameter | Type | Description |
| --- | --- | --- |
| `key` | `String` | Required. Refer to this callback by key when setting a callback action on a guide or survey. |
| `func` | `() -> Unit` | Required. The callback to execute. |
```kotlin
engagement.addCallback("show-alert") {
this.runOnUiThread {
android.app.AlertDialog.Builder(this)
.setTitle("Callback")
.setMessage("Callback has been executed!")
.setPositiveButton("OK", null)
.show()
}
}
```
#### Router configuration
Configure how Guides and Surveys handles screen navigation.
```kotlin
engagement.setRouter { identifier ->
// Your screen handling and navigation
}
```
| Parameter | Type | Description |
| --- | --- | --- |
| `identifier` | `String` | Required. A screen identifier (or route) that tells your app where to navigate. |
| `router` (callback) | `(String) -> Unit` | Required. A callback you implement to handle screen navigation when Guides or Surveys need to change screens. |
> **Note:** Update link behavior
>
> After you configure the router with `setRouter()`, update the link behavior setting in the Guides and Surveys interface. For any link actions in your guides or surveys, change the behavior to **Use router**. The guide or survey then uses the custom router function instead of the default browser navigation.
To remove the router, call `unsetRouter()`.
```kotlin
amplitudeEngagement.unsetRouter()
```
#### Reset
Reset a guide or survey to a specific step.
```kotlin
amplitudeEngagement.reset(key = "GUIDE_KEY", stepIndex = 0)
```
| 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.
```kotlin
val guidesAndSurveys = amplitudeEngagement.list()
```
#### Show
Display a specific guide or survey. Ignores any targeting rules and limits except for screen targeting.
```kotlin
amplitudeEngagement.show(key = "GUIDE_KEY")
```
| Parameter | Type | Description |
| --- | --- | --- |
| `key` | `string` | Required. The guide or survey's key. |
#### Forward event
If you don't use the Amplitude Analytics Android SDK plugin (that is, you called `boot` directly), use `forwardEvent` to enable the _On event tracked_ trigger in Guides and Surveys. Forwarded events aren't sent to Amplitude servers. The SDK uses them only for local trigger evaluation.
> **Tip:** Strongly recommended for this installation path
>
> Amplitude strongly recommends setting up event forwarding when not using the Amplitude Analytics Android SDK plugin. Without it, you can't use the _On event tracked_ trigger, which limits your ability to show guides and surveys based on user behavior in your app.
```kotlin
// Forward events from Amplitude to trigger guides
val event = BaseEvent()
amplitudeEngagement.forwardEvent(event)
```
#### Reset smart interactions
Call `resetSmartInteractions()` to clear any cached state from smart interaction detectors, including rage-tap, user inactivity, and element-tap detection.
```kotlin
amplitudeEngagement.resetSmartInteractions()
```
#### Close all
Close all active guides and surveys.
```kotlin
amplitudeEngagement.closeAll()
```
### Super Debugger
When you scan a preview QR code from the Amplitude dashboard, a small Amplitude logo appears at the bottom of your screen. Tap it to open the Super Debugger panel.
The Super Debugger has two tabs: **Details** and **Setup**.
#### Details tab
The _Details_ tab shows information about the guide or survey you're previewing and lets you inspect and control the preview session.
**Guide / Survey**: The name of the active guide or survey. Tap it to switch to a different guide or survey.
**Details**:
- **Step**: The current step number out of the total (for example, "1 of 3"). Tap the copy icon to copy the value.
- **User**: The user ID for the preview session. Tap the copy icon to copy it.
- **Screen**: The screen name the SDK currently reports. Tap the copy icon to copy it.
**Debug**: Shows whether the guide or survey passes each condition check. Each row expands to show details:
- **Limits**: Whether the guide or survey reached its display limit. Expand to review the configured limit. If you configure a limit, tap **Reset User History** to reset your history so the guide or survey can display again.
- **Trigger**: Whether the guide or survey meets the trigger condition. Expand to review the trigger type, screen conditions, and pin target element (if applicable).
- **Throttle**: Whether the guide or survey meets the throttle condition. Expand to review the throttle setting. Toggle **Ignore limits** to bypass throttle limits during your preview session.
**Advanced**:
- **Pin Debugging**: Expand to enable **Reposition pins every 5 seconds**. The debugger periodically re-evaluates pin positions to help debug pin placement on dynamic layouts.
At the bottom of the panel:
- **Restart Preview**: Resets the guide or survey to its first step and restarts the preview.
- **Close Preview**: Exits preview mode and dismisses the Super Debugger.
#### Setup tab
The _Setup_ tab shows SDK configuration and environment details for the current session.
**SDK Versions**: The version of the Engagement SDK installed in your app.
**Installation**:
- **Type**: The SDK installation method (for example, Plugin or standalone).
- **Configuration**: The number and type of custom configuration options applied.
**User**:
- **User ID**: The user ID passed to the SDK on boot.
- **Properties**: Any user properties set for the current session.
**Event Flow**: Confirms whether events are flowing correctly:
- **Events flowing into Guides and Surveys SDK**: Events from your analytics instance reach the Engagement SDK.
- **Events flowing out of Guides and Surveys SDK**: The Engagement SDK sends events to Amplitude.
#### Support
Tap the **?** button to open the _Support_ panel. From here you can:
- Open links to the SDK documentation and Guides and Surveys overview.
- **File Bug Report**: Submit a bug report directly from the debugger. Fill in steps to reproduce, expected results, and actual results, then tap **Send**.
### Known limitations
#### No offline support
The SDK requires an active internet connection to fetch and display guides and surveys. If a device is offline when the app first loads, guides and surveys don't display for that app session.
#### Targeting animated elements and elements inside moving containers
Pins and tooltips can't target views or elements that are:
- Animated or in an animated container (they move around the screen).
- In a container that can move based on user interaction.
> **Note:** Note
>
> Scrollviews usually work.
> **Tip:** Workaround
>
> Use screen-based targeting or event-based triggers to show guides, perhaps with a delay to ensure any animations have completed. Don't pin directly to elements in animated containers or containers that can move through user interaction.
### Changelog
Go to the [Mobile SDK changelog](https://amplitude.com/docs/sdks/guides-and-surveys/guides-and-surveys-mobile-sdk-changelog).
================================================================================
# Guides and Surveys React Native SDK
URL: https://amplitude.com/docs/sdks/guides-and-surveys/guides-and-surveys-rn-sdk
================================================================================
# Guides and Surveys React Native SDK
- **Package:** `@amplitude/plugin-engagement-react-native` ([npm](https://www.npmjs.com/package/@amplitude/plugin-engagement-react-native))
- **Latest version:** 3.14.0
Amplitude's Guides and Surveys SDK enables you to deploy [Guides and Surveys](https://amplitude.com/docs/guides-and-surveys) on your website or application.
## Install and verify
Follow these steps to install the SDK, connect your app to your Amplitude project, and confirm guides and surveys reach your app.
### Requirements
The Guides and Surveys React Native SDK requires:
- The ["new" React Native architecture](https://reactnative.dev/architecture/landing-page).
- React Native 0.79.2+.
- Android Gradle 8.7.2+.
- Gradle 8+.
- iOS 15+.
- Swift 5.9+.
### Installation
#### Install the SDK
Install the Guides and Surveys React Native SDK as a package with npm or Yarn.
#### npm
```bash
npm install @amplitude/plugin-engagement-react-native
npm install @react-native-async-storage/async-storage
```
#### yarn
```bash
yarn add @amplitude/plugin-engagement-react-native
yarn add @react-native-async-storage/async-storage
```
> **Note:** Async storage
>
> Explicitly adding `@react-native-async-storage/async-storage` ensures the native module links correctly, since the `engagement` native module uses it.
Run `pod install` in the `ios` directory.
```bash
cd ios
bundle exec pod install
```
#### Initialize the SDK
```js
//index.js
import { Linking } from "react-native";
import { init, add } from "@amplitude/analytics-react-native";
import {
getPlugin,
handleURL,
} from "@amplitude/plugin-engagement-react-native";
init("<<< YOUR API KEY HERE >>>");
add(getPlugin());
Linking.getInitialURL().then(async (url) => {
if (url) {
const didHandleURL = await handleURL(url);
if (didHandleURL) {
return;
}
// Handle a non-Amplitude SDK URL
}
});
Linking.addEventListener("url", async ({ url }) => {
const didHandleURL = await handleURL(url);
if (didHandleURL) {
return;
}
// Handle a non-Amplitude SDK URL
});
```
> **Note:** Amplitude server zone
>
> The SDK automatically uses the `serverZone` that initializes `@amplitude/analytics-react-native`. Refer to [Configure the SDK](https://amplitude.com/docs/sdks/analytics/react-native/react-native-sdk#configure-the-sdk). You don't need to pass `serverZone` in the `options` argument to `init`.
##### Configuration options
| Parameter | Type | Description |
| --- | --- | --- |
| `apiKey` | `string` | Required. API key of the Amplitude project you want to use. |
| `options.serverUrl` | `string` | Optional. Sets a custom server URL for API requests. Use this option for [proxy setups](https://amplitude.com/docs/guides-and-surveys/proxy). Default: `https://gs.amplitude.com` (US) or `https://gs.eu.amplitude.com` (EU). |
| `options.cdnUrl` | `string` | Optional. Sets a custom CDN URL for static assets. Use this option for [proxy setups](https://amplitude.com/docs/guides-and-surveys/proxy). Default: `https://cdn.amplitude.com` (US) or `https://cdn.eu.amplitude.com` (EU). |
| `options.mediaUrl` | `string` | Optional. Sets a custom URL for proxying nudge images. Use this option for [proxy setups](https://amplitude.com/docs/guides-and-surveys/proxy) when firewalls block images. Default: `https://engagement-static.amplitude.com` (US) or `https://engagement-static.eu.amplitude.com` (EU). |
| `options.logLevel` | `LogLevel.None` or `LogLevel.Error` or `LogLevel.Warn` or `LogLevel.Verbose` or `LogLevel.Debug`. | Optional. Sets the log level. Default: `LogLevel.Warn`. |
| `options.locale` | `string` | Optional. Sets the locale for [localization](#localization). Defaults to the device's system language (for example, `en`). Note that the default is a language code only, not a full locale identifier like `en-US`. |
> **Warning:** Use the same API key for Guides & Surveys and Analytics
>
> To avoid analytics mismatches and ensure accurate data collection, use the same API key for both Guides & Surveys and your Analytics SDK. Both should reference the same Amplitude project. Using different API keys can cause:
>
> - The SDK to fetch guides and surveys from the wrong project.
> - Analytics data to appear in different projects.
> - Insights and survey responses to be incomplete or mismatched.
>
> Make sure the API key you provide to Guides & Surveys matches the API key used to initialize your Amplitude Analytics SDK.
#### Boot the plugin
Booting the plugin (with a user ID) enables Guides and Surveys to be shown:
```js
import { boot } from "@amplitude/plugin-engagement-react-native";
import {
track,
setDeviceId,
setUserId,
} from "@amplitude/analytics-react-native";
import { useEffect } from "react";
export default function App() {
useEffect(() => {
//
// setting the User ID in @amplitude/analytics-react-native
// --and-- passing it to boot() is necessary
//
setUserId("rn-test-user-1");
setDeviceId("test-device-1");
// boot(user_id?: string, device_id?: string, user_properties?: Object): void
boot(
"rn-test-user-1" /* user_id */,
"test-device-1" /* device_id */,
{} /* user_properties */,
);
}, []);
}
```
> **Note:**
>
> After you boot the plugin, installation is complete. Continue to [Set up and verify preview mode](#set-up-and-verify-preview-mode) to confirm everything works.
### Add your application to project settings
After installing the SDK, add your React Native application to your Amplitude project settings so it appears as a platform option when you create guides and surveys.
To add your application:
1. Navigate to _Settings > Projects_ in Amplitude.
2. Select your project.
3. Navigate to the **Guides and Surveys** tab.
4. In the **App Management** section, expand and click **+ Add App**.
5. Select **React Native** from the dropdown.
After you add your application, you can select it as a platform option when you create or edit guides and surveys for your React Native app users.
### Set up and verify preview mode
Preview guides and surveys directly in your application to view the same experience your users receive. Previewing makes it easier to iterate on copy, targeting rules, and trigger logic, and confirms your installation is working.
> **Warning:** Deep linking required for preview
>
> If your app doesn't have deep linking enabled, follow [React Native's instructions](https://reactnative.dev/docs/linking#enabling-deep-links) to add support for deep linking. **Previewing guides and surveys on a phone, tablet, or simulator requires this configuration.**
#### Set up preview in Xcode (iOS)
##### Locate the mobile URL scheme
To locate the URL scheme:
1. Navigate to _Settings > Projects_ in Amplitude.
2. Select your project.
3. Navigate to the **General** tab.
4. Find the **URL scheme (mobile)** field.
5. Copy its value, for example, `amp-abcdefgh12345678`.
##### Add the URL scheme in Xcode
1. Open your iOS project in Xcode.
2. In the Project navigator, select your app's target.
3. On the **Info** tab, locate or add the **URL Types** section.
4. Add a new URL type with the following values:
- **URL identifier**: Provide a descriptive name, like `AmplitudeURLScheme`.
- **URL Schemes**: Paste the value you copied from Amplitude, for example `amp-abc123`.
#### Set up preview in Android Studio (Android)
##### Locate the mobile URL scheme
To locate the URL scheme:
1. Navigate to _Settings > Projects_ in Amplitude.
2. Select your project.
3. Navigate to the **General** tab.
4. Find the **URL scheme (mobile)** field.
5. Copy its value, for example, `amp-abcdefgh12345678`.
##### Add the URL scheme in Android Studio
Add the following intent filter to the main activity to your project's `AndroidManifest.xml` file:
```xml
```
#### URL handling for preview links
The [initialization code snippet](#initialize-the-sdk) handles URL handling for preview links. The relevant code is:
```js
Linking.getInitialURL().then(async (url) => {
if (url) {
const didHandleURL = await handleURL(url);
if (didHandleURL) {
return;
}
// Handle a non-Amplitude SDK URL
}
});
Linking.addEventListener("url", async ({ url }) => {
const didHandleURL = await handleURL(url);
if (didHandleURL) {
return;
}
// Handle a non-Amplitude SDK URL
});
```
#### Verify your installation with a QR code scan
Confirm your installation works end to end:
1. In Amplitude, open a guide or survey and click **Preview**.
2. Scan the displayed QR code with your device's camera, or open the preview URL on a device that has your app installed.
3. Confirm the guide or survey opens inside your app.
4. Look for a small Amplitude logo at the bottom of the screen, and tap it to open the Super Debugger. Refer to [Super Debugger](#super-debugger) for what to check there.
If the preview doesn't open in your app, or the logo doesn't appear, review the deep linking and URL scheme setup steps above before continuing.
## Reference
### Set a minimum SDK version (when needed)
Mobile SDK versions `3.0.0` and later support `Minimum SDK version`. Use this setting as a safety control when you identify a critical issue in an older SDK release.
To configure a minimum SDK version:
1. Navigate to _Settings > Projects_ in Amplitude.
2. Select your project.
3. Navigate to the **Guides and Surveys** tab.
4. In the **App Management** section, expand and click **+ Add App**.
5. Select **React Native** from the dropdown.
6. Enter a value in **Minimum SDK version**.
When you set this value, Guides and Surveys compares the configured minimum with the SDK version in each app build:
- If an app build uses an older SDK version, the SDK doesn't initialize in that build.
- If an app build uses the same or newer SDK version, the SDK initializes as expected.
Use this setting to stop guides and surveys on known problematic SDK versions without rolling back your application release.
#### Example usage of minimum SDK version
Suppose app version `120` uses Guides and Surveys SDK `3.0.2`, and app version `121` uses Guides and Surveys SDK `3.1.0` with a bug fix. If you set **Minimum SDK version** to `3.1.0`:
- App version `120` no longer loads Guides and Surveys.
- App version `121` continues to load Guides and Surveys.
### Element targeting
Pin, tooltip, and card embed guides require the SDK to target specific views on screen. The Engagement SDK uses the `testID` property on an element in the React Native DOM.
In the following example, use `welcome-banner` as the element targeting string in the Guides and Surveys dashboard.
```js
import React from "react";
import { View, Text, StyleSheet } from "react-native";
/**
* A simple component with a testID that can be targeted
* by the Amplitude Guides & Surveys SDK.
*/
export default function WelcomeBanner() {
return (
Welcome to the App!
);
}
```
### Localization
The SDK defaults to the device's system language when you don't set the `locale` option at initialization. The default is a language code only (for example, `en`), not a full locale identifier like `en-US`.
To set a specific language, pass the `locale` option when you initialize the SDK:
```js
import { init, add } from "@amplitude/analytics-react-native";
import { getPlugin } from "@amplitude/plugin-engagement-react-native";
init("YOUR_API_KEY");
add(
getPlugin({
locale: "es-ES",
}),
);
```
### Super Debugger
When you scan a preview QR code from the Amplitude dashboard, a small Amplitude logo appears at the bottom of your screen. Tap it to open the Super Debugger panel.
The Super Debugger has two tabs: **Details** and **Setup**.
#### Details tab
The _Details_ tab shows information about the guide or survey you're previewing and lets you inspect and control the preview session.
**Guide / Survey**: The name of the active guide or survey. Tap it to switch to a different guide or survey.
**Details**:
- **Step**: The current step number out of the total (for example, "1 of 3"). Tap the copy icon to copy the value.
- **User**: The user ID for the preview session. Tap the copy icon to copy it.
- **Screen**: The screen name the SDK currently reports. Tap the copy icon to copy it.
**Debug**: Shows whether the guide or survey passes each condition check. Each row expands to show details:
- **Limits**: Whether the guide or survey reached its display limit. Expand to review the configured limit.
- **Trigger**: Whether the guide or survey meets the trigger condition. Expand to review the trigger type, screen conditions, and pin target element (if applicable).
- **Throttle**: Whether the guide or survey meets the throttle condition. Expand to review the throttle setting. Toggle **Ignore limits** to bypass throttle limits during your preview session.
**Advanced**:
- **Pin Debugging**: Expand to enable **Reposition pins every 5 seconds**. The debugger periodically re-evaluates pin positions to help debug pin placement on dynamic layouts.
At the bottom of the panel:
- **Restart Preview**: Resets the guide or survey to its first step and restarts the preview.
- **Close Preview**: Exits preview mode and dismisses the Super Debugger.
#### Setup tab
The _Setup_ tab shows SDK configuration and environment details for the current session.
**SDK Versions**: The version of the Engagement SDK installed in your app.
**Installation**:
- **Type**: The SDK installation method (for example, Plugin or standalone).
- **Configuration**: The number and type of custom configuration options applied.
**User**:
- **User ID**: The user ID passed to the SDK on boot.
- **Properties**: Any user properties set for the current session.
**Event Flow**: Confirms whether events are flowing correctly:
- **Events flowing into Guides and Surveys SDK**: Events from your analytics instance reach the Engagement SDK.
- **Events flowing out of Guides and Surveys SDK**: The Engagement SDK sends events to Amplitude.
#### Support
Tap the **?** button to open the _Support_ panel. From here you can:
- Open links to the SDK documentation and Guides and Surveys overview.
- **File Bug Report**: Submit a bug report directly from the debugger. Fill in steps to reproduce, expected results, and actual results, then tap **Send**.
### Known limitations
#### Tab bar element targeting
Pins and tooltips can't target tab bar items in navigation components (such as `@react-navigation/bottom-tabs`). Tab bars use native components that exist outside the standard React Native view hierarchy, which prevents the SDK from reliably locating and attaching guides to these elements.
> **Tip:** Workaround
>
> Use screen-based targeting or event-based triggers to show guides when users navigate to specific tabs. Do not pin directly to tab bar items.
#### Targeting animated elements and elements inside moving containers
Pins and tooltips can't target views or elements that are:
- Animated or in an animated container (they move around the screen).
- In a container that can move based on user interaction.
> **Note:** Note
>
> Scrollviews usually work.
> **Tip:** Workaround
>
> Use screen-based targeting or event-based triggers to show guides, perhaps with a delay to ensure any animations have completed. Don't pin directly to elements in animated containers or containers that can move through user interaction.
### Changelog
Go to the [Mobile SDK changelog](https://amplitude.com/docs/sdks/guides-and-surveys/guides-and-surveys-mobile-sdk-changelog).
================================================================================
# Guides and Surveys Flutter SDK
URL: https://amplitude.com/docs/sdks/guides-and-surveys/guides-and-surveys-flutter-sdk
================================================================================
# Guides and Surveys Flutter SDK
- **Package:** `amplitude_engagement_flutter` ([pubdev](https://pub.dev/packages/amplitude_engagement_flutter))
- **Latest version:** 0.0.10
> **Warning:** Early Access
>
> This feature is experimental. Expect changes as development continues. Because the feature continues to evolve, this documentation may be out of date.
Amplitude's Guides and Surveys Flutter SDK lets you deploy [Guides and Surveys](https://amplitude.com/docs/guides-and-surveys) in your Flutter applications.
## Install and verify
Follow these steps to install the SDK, connect your app to your Amplitude project, and confirm guides and surveys reach your app.
### Requirements
The Guides and Surveys Flutter SDK requires:
- Dart 3.3+.
- Flutter 3.7+.
- [Amplitude Analytics Flutter SDK](https://amplitude.com/docs/sdks/analytics/flutter) 4.4.0+.
### Installation
#### Install the SDK
Add the Guides and Surveys package and the Amplitude Analytics SDK to your `pubspec.yaml`:
```yaml
dependencies:
amplitude_flutter: ^4.4.0
amplitude_engagement_flutter: ^0.0.5
```
Run `flutter pub get` to install the dependencies.
Run `pod install` in the `ios` directory.
```bash
cd ios
pod install
```
#### Initialize the SDK
```dart
import 'package:app_links/app_links.dart';
import 'package:amplitude_flutter/amplitude.dart';
import 'package:amplitude_flutter/configuration.dart';
import 'package:amplitude_engagement_flutter/amplitude_engagement.dart' as engagement;
// Initialize Analytics
final amplitude = Amplitude(Configuration(apiKey: 'YOUR_API_KEY'));
// Connect the engagement SDK to the analytics instance
await engagement.installAmplitudeEngagementPlugin(amplitude);
// Handle deep links for preview mode
final appLinks = AppLinks();
appLinks.getInitialLink().then((uri) async {
if (uri != null) {
final didHandleURL = await engagement.handleURL(uri.toString());
if (didHandleURL) { return; }
// Handle a non-Amplitude SDK URL
}
});
appLinks.uriLinkStream.listen((uri) async {
final didHandleURL = await engagement.handleURL(uri.toString());
if (didHandleURL) { return; }
// Handle a non-Amplitude SDK URL
});
```
`installAmplitudeEngagementPlugin` initializes the engagement SDK using the same API key and passes the native analytics instance to the engagement layer on iOS and Android.
##### Configuration options
Pass an `AmplitudeInitOptions` object to `installAmplitudeEngagementPlugin` to configure the SDK:
```dart
await engagement.installAmplitudeEngagementPlugin(amplitude, options: AmplitudeInitOptions(
serverZone: AmplitudeServerZone.eu,
logLevel: AmplitudeLogLevel.debug,
));
```
| Parameter | Type | Description |
| --- | --- | --- |
| `serverZone` | `EU` or `US` | Optional. Sets the Amplitude server zone. Set this to `EU` for Amplitude projects created in the EU data center. Default: `US` |
| `serverUrl` | `string` | Optional. Custom server URL for API requests. Use this option for [proxy setups](https://amplitude.com/docs/guides-and-surveys/proxy). |
| `cdnUrl` | `string` | Optional. Custom CDN URL for static assets. Use this option for [proxy setups](https://amplitude.com/docs/guides-and-surveys/proxy). |
| `mediaUrl` | `string` | Optional. Custom URL for proxying nudge images. Use this option for [proxy setups](https://amplitude.com/docs/guides-and-surveys/proxy) when firewalls block images. |
| `logLevel` | `LogLevel` enum | Optional. Sets the log level. Default: `LogLevel.warn`. |
| `locale` | `string` | Optional. Sets the locale for [localization](#localization). Defaults to the device's system language (for example, `en`). Note that the default is a language code only, not a full locale identifier like `en-US`. |
> **Warning:** Use the same API key for Guides & Surveys and Analytics
>
> To avoid analytics mismatches and ensure accurate data collection, use the same API key for both Guides & Surveys and your Analytics SDK. Both should reference the same Amplitude project. Using different API keys can cause:
>
> - The SDK to fetch guides and surveys from the wrong project.
> - Analytics data to appear in different projects.
> - Insights and survey responses are incomplete or mismatched.
>
> Make sure the API key you provide to Guides & Surveys matches the API key used to initialize your Amplitude Analytics SDK.
#### Boot the SDK
Boot the SDK with a user ID to enable Guides and Surveys:
```dart
import 'package:amplitude_flutter/amplitude.dart';
import 'package:amplitude_flutter/events/identify.dart';
import 'package:amplitude_engagement_flutter/amplitude_engagement.dart' as engagement;
// Setting the User ID in Amplitude Analytics
// --and-- passing it to boot() is necessary
amplitude.setUserId('test-user-1');
// boot(userId, deviceId, userProperties)
await engagement.boot(
userId: 'test-user-1',
deviceId: 'test-device-1', // optional if userId is set
userProperties: {'plan': 'premium'}, // optional
);
```
> **Note:**
>
> After you boot the SDK, installation is complete. Continue to [Set up and verify preview mode](#set-up-and-verify-preview-mode) to confirm everything works.
### Add your application to project settings
After installing the SDK, add your Flutter application to your Amplitude project settings so it appears as a platform option when you create guides and surveys.
To add your application:
1. Navigate to _Settings > Projects_ in Amplitude.
2. Select your project.
3. Navigate to the **Guides and Surveys** tab.
4. In the **App Management** section, expand and click **+ Add App**.
5. Select **Flutter** from the dropdown.
After you add your application, you can select it as a platform option when you create or edit guides and surveys for your Flutter app users.
### Set up and verify preview mode
Preview guides and surveys directly in your application to view the same experience your users receive. Previewing makes it easier to iterate on copy, targeting rules, and trigger logic, and confirms your installation is working.
> **Warning:** Deep linking required for preview
>
> If your app doesn't have deep linking enabled, follow [Flutter's instructions](https://docs.flutter.dev/ui/navigation/deep-linking) to add support for deep linking. **Previewing guides and surveys on a phone, tablet, or simulator requires this configuration.**
#### Set up preview in Xcode (iOS)
##### Locate the mobile URL scheme
To locate the URL scheme:
1. Navigate to _Settings > Projects_ in Amplitude.
2. Select your project.
3. Navigate to the **General** tab.
4. Find the **URL scheme (mobile)** field.
5. Copy its value, for example, `amp-abcdefgh12345678`.
##### Add the URL scheme in Xcode
1. Open your iOS project in Xcode.
2. In the Project navigator, select your app's target.
3. On the **Info** tab, locate or add the **URL Types** section.
4. Add a new URL type with the following values:
- **URL identifier**: Provide a descriptive name, like `AmplitudeURLScheme` for example.
- **URL Schemes**: Paste the value you copied from Amplitude, for example `amp-abc123`.
#### Set up preview in Android Studio (Android)
##### Locate the mobile URL scheme
To locate the URL scheme:
1. Navigate to _Settings > Projects_ in Amplitude.
2. Select your project.
3. Navigate to the **General** tab.
4. Find the **URL scheme (mobile)** field.
5. Copy its value, for example, `amp-abcdefgh12345678`.
##### Add the URL scheme in Android Studio
Add the following intent filter to the main activity in your project's `AndroidManifest.xml` file:
```xml
```
#### URL handling for preview links
The [initialization code snippet](#initialize-the-sdk) handles URL handling for preview links. The relevant code is:
```dart
final appLinks = AppLinks();
appLinks.getInitialLink().then((uri) async {
if (uri != null) {
final didHandleURL = await engagement.handleURL(uri.toString());
if (didHandleURL) { return; }
// Handle a non-Amplitude SDK URL
}
});
appLinks.uriLinkStream.listen((uri) async {
final didHandleURL = await engagement.handleURL(uri.toString());
if (didHandleURL) { return; }
// Handle a non-Amplitude SDK URL
});
```
#### Verify your installation with a QR code scan
Confirm your installation works end to end:
1. In Amplitude, open a guide or survey and click **Preview**.
2. Scan the displayed QR code with your device's camera, or open the preview URL on a device that has your app installed.
3. Confirm the guide or survey opens inside your app.
4. Look for a small Amplitude logo at the bottom of the screen, and tap it to open the Super Debugger. Refer to [Super Debugger](#super-debugger) for what to check there.
If the preview doesn't open in your app, or the logo doesn't appear, review the deep linking and URL scheme setup steps above before continuing.
## Reference
### Set a minimum SDK version (when needed)
Mobile SDK versions `3.0.0` and later support `Minimum SDK version`. Use this setting as a safety control when you identify a critical issue in an older SDK release.
To configure a minimum SDK version:
1. Navigate to _Settings > Projects_ in Amplitude.
2. Select your project.
3. Navigate to the **Guides and Surveys** tab.
4. In the **App Management** section, expand and click **+ Add App**.
5. Select **Flutter** from the dropdown.
6. Enter a value in **Minimum SDK version**.
When you set this value, Guides and Surveys compares the configured minimum with the SDK version in each app build:
- If an app build uses an older SDK version, the SDK doesn't initialize in that build.
- If an app build uses the same or newer SDK version, the SDK initializes as expected.
Use this setting to stop guides and surveys on known problematic SDK versions without rolling back your application release.
### Screen tracking
Call `screen` to enable screen-based targeting and the Time on Screen trigger. Guides and Surveys compares the screen string (for example, `"HomeScreen"`) with the string you set in the guide or survey page targeting section.
```dart
engagement.screen('HomeScreen');
```
### Element targeting
Pin, tooltip, and card embed guides require the SDK to target specific widgets on screen. The SDK automatically enables element targeting on initialization.
Tag targetable widgets with `AmplitudeEngagementView` as a `SemanticsTag` to give them a stable identifier. In the following example, use `"welcome-banner"` as the element targeting string in the Guides and Surveys dashboard.
```dart
import 'package:flutter/material.dart';
import 'package:amplitude_engagement_flutter/amplitude_engagement.dart' as engagement;
Semantics(
tagForChildren: const engagement.AmplitudeEngagementView('welcome-banner'),
child: Banner(
child: Text('Welcome to the app'),
),
)
```
### Localization
The SDK defaults to the device's system language when you don't set the `locale` option at initialization. The default is a language code only (for example, `en`), not a full locale identifier like `en-US`.
To set a specific language, pass the `locale` option when you initialize the SDK:
```dart
import 'package:amplitude_flutter/amplitude.dart';
import 'package:amplitude_engagement_flutter/amplitude_engagement.dart' as engagement;
final amplitude = Amplitude(Configuration(apiKey: 'YOUR_API_KEY'));
await engagement.installAmplitudeEngagementPlugin(amplitude, options: AmplitudeInitOptions(
locale: 'es-ES',
));
```
### Other SDK methods
#### Manage themes
```dart
engagement.setThemeMode(AmplitudeThemeMode.dark); // Options: auto, light, dark
```
#### Register a callback
```dart
engagement.addCallback('show-alert', () {
// Custom logic when the guide or survey triggers this callback
});
```
#### Reset
```dart
engagement.reset('GUIDE_KEY', 0);
```
#### List
```dart
final guidesAndSurveys = await engagement.list();
```
#### Show
```dart
engagement.show('GUIDE_KEY');
```
#### Forward event
Use `forwardEvent` to enable the _On event tracked_ trigger in Guides and Surveys. The SDK doesn't send forwarded events to Amplitude servers; it uses them only for local trigger evaluation.
```dart
engagement.forwardEvent({
'event_type': 'Button Clicked',
'event_properties': {'name': 'Submit'},
});
```
#### Close all
```dart
engagement.closeAll();
```
### Super Debugger
When you scan a preview QR code from the Amplitude dashboard, a small Amplitude logo appears at the bottom of your screen. Tap it to open the Super Debugger panel.
The Super Debugger has two tabs: **Details** and **Setup**.
#### Details tab
The _Details_ tab shows information about the guide or survey you're previewing and lets you inspect and control the preview session.
**Guide / Survey**: The name of the active guide or survey. Tap it to switch to a different guide or survey.
**Details**:
- **Step**: The current step number out of the total (for example, "1 of 3"). Tap the copy icon to copy the value.
- **User**: The user ID for the preview session. Tap the copy icon to copy it.
- **Screen**: The screen name the SDK currently reports. Tap the copy icon to copy it.
**Debug**: Shows whether the guide or survey passes each condition check. Each row expands to show details:
- **Limits**: Whether the guide or survey reached its display limit. Expand to review the configured limit.
- **Trigger**: Whether the guide or survey meets the trigger condition. Expand to review the trigger type, screen conditions, and pin target element (if applicable).
- **Throttle**: Whether the guide or survey meets the throttle condition. Expand to review the throttle setting. Toggle **Ignore limits** to bypass throttle limits during your preview session.
**Advanced**:
- **Pin Debugging**: Expand to enable **Reposition pins every 5 seconds**. The debugger periodically re-evaluates pin positions to help debug pin placement on dynamic layouts.
At the bottom of the panel:
- **Restart Preview**: Resets the guide or survey to its first step and restarts the preview.
- **Close Preview**: Exits preview mode and dismisses the Super Debugger.
#### Setup tab
The _Setup_ tab shows SDK configuration and environment details for the current session.
**SDK Versions**: The version of the Engagement SDK installed in your app.
**Installation**:
- **Type**: The SDK installation method (for example, Plugin or standalone).
- **Configuration**: The number and type of custom configuration options applied.
**User**:
- **User ID**: The user ID passed to the SDK on boot.
- **Properties**: Any user properties set for the current session.
**Event Flow**: Confirms whether events are flowing correctly:
- **Events flowing into Guides and Surveys SDK**: Events from your analytics instance reach the Engagement SDK.
- **Events flowing out of Guides and Surveys SDK**: The Engagement SDK sends events to Amplitude.
#### Support
Tap the **?** button to open the _Support_ panel. From here you can:
- Open links to the SDK documentation and Guides and Surveys overview.
- **File Bug Report**: Submit a bug report directly from the debugger. Fill in steps to reproduce, expected results, and actual results, then tap **Send**.
### Known limitations
#### Targeting animated elements and elements inside moving containers
Pins and tooltips can't target widgets that are:
- Animated or inside an animated container (they move on screen).
- Inside a container that moves based on user interaction.
> **Note:**
>
> Scrollable views usually work.
> **Tip:** Workaround
>
> Use screen-based targeting or event-based triggers to show guides, perhaps with a delay to ensure any animations have completed. Don't pin directly to elements in animated containers or containers that can move through user interaction.
### Changelog
Go to the [Mobile SDK changelog](https://amplitude.com/docs/sdks/guides-and-surveys/guides-and-surveys-mobile-sdk-changelog).
================================================================================
# Localization API
URL: https://amplitude.com/docs/apis/guides-and-surveys/guides-and-surveys-api-localization
================================================================================
# Localization API
The Guides and Surveys Localization API imports and exports translation files for your guides and surveys in XLIFF 1.2 format. The API integrates with external translation management systems and workflows.
| Name | Description |
| --- | --- |
| [Import Translations](#import-translations) | Imports an XLIFF file to add or update translations for one or more Nudges. |
| [Export Translations](#export-translations) | Exports translations for specified Nudges (by `flag_key`) into an XLIFF 1.2 file. |
## Regions
All API endpoints described here are relative to the following base URLs:
| Data residency | Base URL |
| --- | --- |
| Default | `https://app.amplitude.com/a/` |
| EU | `https://app.eu.amplitude.com/a/` |
## Authentication
The API uses Basic Authentication. You need to provide your **API Key** (not the **app key**) and **Project Secret Key**.
Construct the Basic Auth header by Base64 encoding the string `YOUR_API_KEY:YOUR_PROJECT_SECRET_KEY`.
**Example Header:** `Authorization: Basic `
Replace `` with your actual Base64 encoded credentials.
## XLIFF file structure
The API uses XLIFF version 1.2. The XLIFF structure includes the following elements:
- **`` element:** Represents translations for a guide or survey.
- `original`: Identifies the guide or survey and optionally a specific variant.
- Format: `` or `_`
- ``: The unique key of your guide or survey.
- `` (optional): The identifier of a specific variant within the guide or survey.
- For import, if `` is omitted, the API updates the first variant of the guide or survey.
- For export, if a guide or survey has multiple active variants, each variant appears in a separate `` element within the XLIFF document. The `original` attribute uses the format `_` to distinguish them.
- `datatype="plaintext"`
- `source-language`: The source language code (for example, "en").
- `target-language`: The target language code for the translations in this file (for example, "de", "fr").
- **`` element:** Contains one or more `` elements.
- **`` element:** Represents a segment of text for translation.
- `id`: A unique identifier for the text segment within the guide or survey (for example, `snooze_label`, `step_1_title`, `step_6_content.markdown`). These IDs correspond to the translatable fields of your guide or survey content.
- ``: The original text in the `source-language`.
- ``: The translated text in the `target-language`. For import, provide the translation here. For export, the element contains the existing translation. An empty `` element means the text isn't yet translated for that target language.
## Endpoints
### Import translations
Imports an XLIFF file to add or update translations for one or more guides or surveys. After a successful import, Amplitude purges the relevant cache for your application so the new translations are available.
- **HTTP Method:** `POST`
- **URL:** `/import/`
- **Headers:**
- `Authorization: Basic `
- `Content-Type: application/xml; charset=utf-8`
- **Request Body:** The raw XLIFF 1.2 XML content.
```xml
Welcome!Willkommen!This is an important announcement.Dies ist eine wichtige Ankündigung.
```
- **Example Request (curl):**
```bash
curl -X POST \\
-H "Authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS" \\
-H "Content-Type: application/xml; charset=utf-8" \\
--data \'\'\'
AnnouncementAnkündigung\'\'\' \\
"https://app.amplitude.com/a/guides-surveys/api/v1/localization/import/"
```
(Replace `` with your actual Base64 encoded API Key and Project Secret Key.)
- **Response:**
- **`200 OK`**: All translation units in the XLIFF file processed successfully. The response body is a JSON object that details the status for each file processed. Example:
```json
{
"nudge-translated-announcement-1": {
"de": {
"state": "COMPLETE",
"message": "Updated 5 translation units."
}
}
}
```
### Export translations
Exports translations for specified guides or survey (by `key`) into an XLIFF 1.2 file.
- **HTTP Method:** `GET`
- **URL:** `/export/`
- **Headers:**
- `Authorization: Basic `
- **Query Parameters:**
- `key` (string, required): The key of the guide or survey to export translations for. To request multiple guides or surveys, provide this parameter multiple times or provide a comma separated list (for example, `?key=key1&key=key2` or `?key=key1,key2`). At least one `key` is required.
- `locale` (string, optional): The specific target language codes to export (for example, "de", "fr"). Provide this parameter multiple times for multiple locales. If omitted, the API exports translations for all configured target locales for the app, excluding the source language.
- **Example Request (curl):** To export translations for a single guide or survey and a specific locale:
```bash
curl -X GET \\
-H "Authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS" \\
"https://app.amplitude.com/a/guides-surveys/api/v1/localization/export/?key=nudge-translated-announcement-1&locale=de"
```
To export for multiple guide or survey keys and locales:
```bash
curl -X GET \\
-H "Authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS" \\
"https://app.amplitude.com/a/guides-surveys/api/v1/localization/export/?key=key-one&key=key-two&locale=de&locale=fr"
```
(Replace `YOUR_BASE64_ENCODED_CREDENTIALS` with your actual Base64 encoded API Key and Project Secret Key.)
- **Response:**
- **`200 OK`**: The response body contains the XLIFF 1.2 XML content.
================================================================================
# Analytics Glossary
URL: https://amplitude.com/docs/guides-and-surveys/analytics-glossary
Updated: 2025-08-25
================================================================================
# Analytics Glossary
This glossary lists the events and event properties Amplitude tracks automatically for Guides and Surveys.
================================================================================
# Guides and Surveys Mobile SDK Changelog
URL: https://amplitude.com/docs/sdks/guides-and-surveys/guides-and-surveys-mobile-sdk-changelog
Updated: 2026-09-02
================================================================================
# Guides and Surveys Mobile SDK Changelog
## 3.14.0
Released September 2, 2026. Platforms: Android, iOS, React Native.
**Features**
- \[iOS\] \[Android\] Support referencing previous steps' survey responses in conditional logic (GSM-1055).
- \[iOS\] \[Android\] Show event property filters in the debugger (GSM-1214).
**Fixes**
- \[iOS\] The debug toolbar no longer breaks when a guide or survey is triggered by smart delay, rage click, user confusion, or no trigger.
- \[iOS\] \[Android\] The debug toolbar keeps working when a guide or survey uses a trigger type your SDK version doesn't recognize yet (GSM-1208).
- \[iOS\] No longer crash when a tracked event's event properties contain a Codable Swift value, for example a Codable enum (GSM-1203).
- \[iOS\] \[Android\] Simplify survey's Other textfield keyboard view and dismiss on deselect (GSM-1228).
- \[iOS\] Track active window lifecycle synchronously to prevent dangling or uncloseable guides and surveys from being left on the UI (GSM-1196).
## 3.13.0
Released August 21, 2026. Platforms: Android, iOS, React Native.
**Features**
- \[iOS\] \[Android\] Support "element is marker" tooltip option (GSM-1123).
- \[iOS\] \[Android\] Support multiple survey questions on a single step (GSM-1050).
**Fixes**
- \[iOS\] \[Android\] Horizontal layout uses theme gap between media and content (GSM-1174).
- \[iOS\] \[Android\] Fixed-height card embeds keep cta at the bottom (GSM-1173).
- \[iOS\] Theme line height applies to guide titles and body content, matching the editor preview (GSM-1192).
- \[Android\] Rating questions appear in card embed (GSM-1204).
- \[iOS\] \[Android\] Theme values using `em`, `rem`, and `%` units now apply on device instead of falling back to defaults, matching the editor preview; previously only `px` worked (GSM-1034).
**Performance improvements**
- \[iOS\] `refresh()` is now "async" and won't interfere with the main thread (GSM-1201).
## 3.12.1
Released August 13, 2026. Platforms: Android, iOS, React Native.
**Fixes**
- \[Android\] Declare a uniquely-named `FileProvider` subclass so apps with other dependencies that declare `androidx.core.content.FileProvider` no longer fail manifest merge (GSM-1194).
## 3.12.0
Released July 31, 2026. Platforms: Android, iOS, React Native.
**Features**
- \[Flutter\] Flutter release now auto-bumps native iOS and Android SDK pins from the released native SDK versions.
- \[iOS\] \[Android\] Support showcase and split content layouts on mobile (GSM-1126).
- \[Android\] Add card embed form factor type (GSM-1135).
- \[iOS\] Add card embed form factor type (GSM-1049).
- \[iOS\] \[Android\] Add support for link images (GSM-1144).
- \[iOS\] Show a placeholder icon while guide images are loading (GSM-1120).
- \[React Native\] `boot()` now accepts options object with `integrations` callbacks to forward G+S events to analytics providers other than Amplitude Analytics (GSM-512).
- \[React Native\] Add `setRouter` / `unsetRouter` SDK methods to React Native for handling in-app navigation from CTA buttons (GSM-1169).
**Fixes**
- \[iOS\] \[Android\] Announce star rating and selection state to voiceover/talkback (GSM-1155).
- \[Android\] Gray out survey cta when a required response is missing (GSM-1151).
- \[Android\] Dropdowns won't use crashing material3 apis when app compose version differs (GSM-1147).
- \[iOS\] Skip nudge render when dismissed before render completes (GSM-1139).
- \[iOS\] \[Android\] Support CSS named colors in themes (GSM-1035).
- \[iOS\] \[Android\] Theme padding applies to the container, with all content blocks (title, body, images, videos, surveys, buttons) evenly spaced by the theme's "gap" value; existing themes are unaffected (GSM-1127).
- \[iOS\] \[Android\] Include Guides and Surveys mobile SDK version in event properties for "standalone" use case (GSM-1116).
- \[iOS\] \[Android\] Do not show duplicate image when using "vertical split" or "horizontal split" layouts (GSM-1129).
- \[Android\] Prevent duplicate debug buttons when navigating between activities (GSM-1159).
- \[iOS\] Show one close button on vertical-split popovers and pins with media (GSM-1165).
- \[iOS\] \[Android\] Clean up layouts and media alignment for card embeds and other types (GSM-1141).
- \[iOS\] \[Android\] Images use theme's button corner radius instead of card corner radius (GSM-1164).
- \[iOS\] \[Android\] Card embed border and background match fixed height (GSM-1163).
- \[iOS\] \[Android\] Hide debug button when test user mode is turned off (GSM-1156).
- \[Flutter\] Pass `mediaUrl` through when installing the engagement plugin so media proxy URLs take effect (GSM-1167).
- \[Android\] \[Flutter\] Opening a preview link no longer crashes apps whose activity does not extend `ComponentActivity` (GSM-1160).
- \[iOS\] Recognize taps near the top and bottom edges of a guide with image (GSM-1179).
- \[Android\] Hide pin nudge when the target element scrolls fully off-screen (GSM-1180).
- \[iOS\] \[Android\] Reduce image fade-in time (GSM-1181).
## 3.11.0
Released July 1, 2026. Platforms: Android, iOS, React Native, Flutter.
**Features**
- \[iOS\] \[Android\] Support "stay on step" CTA action for guides (GSM-1118).
- \[Android\] Add fullscreen text input editing ui for modals, popovers, pins with open keyboard (GSM-1056).
- \[iOS\] \[Android\] Add super debugger test user functionality and tests (GSM-892, GSM-1117).
**Fixes**
- \[iOS\] \[Android\] Render guide content blocks in the order configured in the web builder (GSM-1083).
- \[iOS\] \[Android\] VoiceOver/TalkBack skip background elements; navigate carousel elements on current step (GSM-1112).
- \[Android\] Ensure CTA is visible on long nudges (GSM-1056).
- \[iOS\] \[Android\] Use "gap" variable in theme for spacing between title/body and content blocks (existing themes unaffected) (GSM-1113).
- \[iOS\] Correct fullscreen keyboard editing layout after device rotation on iOS 26+ (GSM-1107).
- \[iOS\] Hide debug button if simulation context fails (GSM-1115).
- \[iOS\] Show debug button with error state when simulation context fails to load (GSM-1119).
- \[iOS\] Replace view hierarchy polling with event-driven monitoring and ensure it is only done in the foreground (GSM-1125).
- \[iOS\] Observe SwiftUI hosting-view layout changes in view hierarchy monitor (GSM-1125).
- \[Flutter\] Support "tap element" CTA action (GSM-1029).
- \[Flutter\] Support "element tapped" trigger (GSM-1028).
- \[Flutter\] Anchor pins to target element when scrolling (GSM-1027).
## 3.10.0
Released June 11, 2026. Platforms: Android, iOS, React Native, Flutter.
**Features**
- \[iOS\] \[Android\] Support survey input "prompt" (GSM-1073).
- \[iOS\] Add fullscreen text input editing ui for modals, popovers, pins with open keyboard (GSM-1056).
**Fixes**
- \[iOS\] \[Android\] Apply only theme typography and color to nps survey (GSM-1051).
- \[iOS\] Respect custom popover/pin/tooltip widths with media blocks (GSM-1045).
- \[iOS\] Ensure orphaned pin guide "marker" is cleaned up (GSM-1087).
- \[iOS\] \[Android\] Style disabled primary buttons (GSM-1080).
## 3.9.0
Released June 4, 2026. Platforms: Android, iOS, React Native.
**Features**
- \[iOS\] \[Android\] Support event-based trigger "delay" feature (GSW-552).
- \[Flutter\] Support swift package manager (GSM-1048).
- \[iOS\] \[Android\] Support `sub_priority` field for fine-grained guide ordering within priority buckets (GSW-425).
**Fixes**
- \[Android\] Persist bug report content on device rotation (GSM-1011).
- \[iOS\] Add top safe area padding for banner (GSM-1053).
- \[Flutter\] SDK not respecting native singleton on android (GSM-1057).
- \[iOS\] Ensure Engagement window displays above host app windows (GSM-1061).
- \[iOS\] Hide pin nudge when target element is obscured by another window (GSM-1061).
- \[iOS\] Ensure pin nudge mask is always cleaned up (GSM-1061).
- \[iOS\] \[Android\] Targeting nudges to users based on the app "version" (GSM-1068).
- \[iOS\] Use square corners on bottom of carousel Guide (on mobile phone only) (GSM-1077).
## 3.8.0
Released May 7, 2026. Platforms: Android, iOS, React Native, Flutter.
**Features**
- \[iOS\] \[Android\] Support for nudges that trigger after N events in a session (GSW-454).
**Fixes**
- \[Android\] Block TalkBack focus on background elements behind nudge (GSM-1018).
- \[Android\] Show selected debug nudge after device rotation instead of original debug nudge (GSDK-937).
- \[Android\] Add top safe area padding for banner (GSM-1033).
- \[iOS\] Use `actualContentSize` to position pin arrow (GSM-1040).
- \[iOS\] Changing font size when guide/survey is rendered causes elements to become non-tappable (GSM-899).
- \[iOS\] Position anchorable nudge UI on main thread after JS callback (GSM-1041).
## 3.7.0
Released April 28, 2026. Platforms: Android, iOS, React Native, Flutter.
**Features**
- \[iOS\] \[Android\] Show alert if user attempts to exit bug report before submitting (GSDK-945).
- \[iOS\] \[Android\] \[Flutter\] \[React Native\] Add `autoRefreshInterval` to init options and deprecate passing it through boot options (GSM-1014).
- \[Android\] Add debug logs screen and bug report logs (GSDK-911).
**Fixes**
- \[iOS\] Block VoiceOver focus on background elements behind nudge (GSM-1018).
- \[iOS\] Lead-align close button when title is trailing-aligned (GSM-1019).
- \[Android\] Update text animation to continue after device rotation (GSDK-923).
## 3.6.0
Released April 15, 2026. Platforms: Android, iOS, React Native, Flutter.
**Features**
- \[Android\] Update UI for debug overlay (GSDK-932).
- \[iOS\] \[Android\] Add debug support and bug report screens (GSDK-913).
- \[iOS\] Add debug logs screen and bug report logs (GSDK-911).
- \[Flutter\] \[React Native\] Add `updateLanguage` SDK method to Flutter & React Native (GSM-358).
**Fixes**
- \[iOS\] \[Android\] Support for multi-action CTAs in Guides & Surveys.
- \[iOS\] \[Android\] Support for conditional actions in Guides & Surveys.
- \[iOS\] Fix flickering on initial pin guide rendering (GSDK-864).
## 3.5.0
Released April 9, 2026. Platforms: Android, iOS, React Native, Flutter.
**Features**
- \[Android\] Update UI for debug overlay (GSDK-932).
- \[Android\] \[React Native\] Add support for HLS video playback for Android (GSDK-924).
**Fixes**
- \[Android\] Reposition debug button so it's not off-screen on device rotation (GSDK-927).
- \[iOS\] Fix abort signal crash in super debugger (GSDK-928).
- \[iOS\] Fix sequence nudge rendering so text animations don't block each other (GSDK-909).
- \[Android\] \[React Native\] \[Flutter\] Potential duplicate class errors when a host app also depends on `org.commonmark` (GSDK-940).
- \[iOS\] Ensure font weight is applied to form components and markdown (GSDK-805).
- \[iOS\] When CSS system font keywords are specified as the font family in theme, use the system font (GSDK-805).
- \[iOS\] Ensure font weight in markdown matches web preview (GSDK-805).
**Performance improvements**
- \[iOS\] Reduce SDK bundle size by ~500KB by using variable fonts (GSDK-805).
## 3.4.0
Released March 31, 2026. Platforms: Android, iOS, React Native.
**Features**
- \[iOS\] \[Android\] Launch any unarchived guide or survey through debugger (GSDK-893).
- \[iOS\] \[Android\] Add debug mode to periodically reposition pins (GSDK-910).
- \[iOS\] \[Android\] Add debug mode "telltale" to indicate whether events are from and to the G+S SDK (GSDK-912).
- \[iOS\] Update UI for debug overlay (GSDK-913).
**Fixes**
- \[iOS\] Reposition debug button so it's not off-screen on device rotation (GSDK-927).
- \[iOS\] Fix incomplete banner text animations on device rotation (GSDK-918).
## 3.3.1
Released March 23, 2026. Platforms: Android, iOS, React Native.
**Fixes**
- \[iOS\] \[Android\] \[React Native\] Fix issue causing SDK method `screen` to not work properly if it was called before the SDK is fully initialized (GSDK-915, assistance-browser PR #1072).
- \[React Native\] Remove trailing comma to re-enable Swift 6.0 support.
- \[Android\] \[iOS\] Fix survey content width to match nudge step type (GSDK-908).
- \[Android\] Fix banner sizing for phone landscape mode (GSDK-907).
- \[iOS\] Fade in banner buttons after text animation completes (GSDK-904).
- \[iOS\] \[Android\] \[React Native\] Remove unnecessary 1 second delay in `screen` SDK method (GSDK-898).
## 3.3.0
Released March 17, 2026. Platforms: Android, iOS, React Native.
**Features**
- \[iOS\] Add theme support for rating button padding (GSDK-803).
- \[Android\] \[iOS\] Fade in buttons after text animation, and add image fade-in (GSDK-889).
- \[Android\] \[iOS\] Refresh SDK on app foregrounded (GSDK-886).
- \[Android\] \[iOS\] Replace reboot call with refresh on session change (GSDK-886).
**Fixes**
- \[Android\] \[iOS\] Fix animated text showing link syntax while in-progress (GSDK-601).
- \[Android\] Fix stuck text when coroutine cancelled mid-animation (GSDK-891).
- \[iOS\] Fix misaligned and unclosable tooltip with image (GSDK-890).
- \[iOS\] Fix undismissible star and number surveys (GSDK-906).
## 3.2.0
Released March 6, 2026. Platforms: Android, iOS, React Native.
**Features**
- \[React Native\] Allow "user\_properties" to be passed into "boot" SDK method (GSDK-869).
- \[Android\] Add theme support for line height (GSDK-820).
- \[Android\] Add theme support for rating button padding (GSDK-822).
- \[Android\] \[iOS\] Add theme support form control and button shadows (GSDK-806, GSDK-824).
**Fixes**
- \[Android\] Update step counter for multi-step pins (GSDK-876).
- \[iOS\] Use currentParent instead of view when resolving bar in nav hierarchy (GSDK-874).
- \[iOS\] Defer pin positioning to correct for layout timing (GSDK-868).
- \[Android\] Fix horizontal pin UI and positioning (GSDK-815).
- \[Android\] \[iOS\] Improve in-app support for vimeo and loom videos (GSDK-338, GSDK-861).
- \[Android\] Increase nudge width for number surveys with nps-format buttons (GSDK-833).
- \[Android\] \[iOS\] Fix nps and numbers rating wrapping to support theming (GSDK-849).
- \[Android\] Add chevron to dropdown list ui (GSDK-239).
- \[iOS\] Expand carousel to fullscreen for phones (GSDK-870, GSDK-871).
## 3.1.1
Released February 23, 2026. Platforms: Android, iOS, React Native.
**Fixes**
- \[Android\] \[iOS\] Reset survey responses on done or dismiss (GSDK-854).
## 3.1.0
Released February 13, 2026. Platforms: Android, iOS, React Native.
**Features**
- \[Android\] \[iOS\] \[React Native\] On `boot`, allow "user ID" to be null or blank as long as device ID is specified (GSDK-732).
- \[Android\] Add youtube video player (GSDK-856).
**Fixes**
- \[Android\] \[iOS\] Fix auto-advance logic (GSDK-859).
- \[iOS\] Race condition causing pin nudge to be unable to render until the view hierarchy is updated (GSDK-827, GSDK-844).
## 3.0.0
Released February 11, 2026. Platforms: Android, iOS, React Native.
**Breaking changes**
- \[iOS\] `AmplitudeEngagement` is now an interface rather than a class. New instances (as of 3.0.0) are created using `AmplitudeEngagementFactory.make` rather than the `AmplitudeEngagement` constructor (GSDK-690).
**Features**
- \[Android\] \[iOS\] \[React Native\] Add SDK methods `disable` which temporarily hides any displayed guides or surveys and `enable` which shows them again (GSDK-513).
- \[React Native\] Add SDK method `shutdown` to React Native SDK binding (GSDK-769).
- \[Android\] \[iOS\] \[React Native\] Add `Minimum SDK version` support to App Management so older SDK versions don't initialize Guides and Surveys.
**Fixes**
- \[Android\] \[iOS\] Fix theming issues (GSDK-845, GSDK-847).
- \[Android\] Fix tap outside to close behavior for modals (GSDK-850).
## 2.1.1
Released February 2, 2026. Platforms: Android, iOS, React Native.
**Fixes**
- \[React Native\] Trailing comma issue causing build error on Swift compiler less than version 6.1.
- \[iOS\] Fix keyboard layout bug during iOS 26 device rotation (GSDK-632).
- \[Android\] Restore nudge keyboard after configuration change (GSDK-831).
## 2.1.0
Released February 2, 2026. Platforms: Android, iOS, React Native.
**Features**
- \[Android\] \[iOS\] Add support for `autoRefreshIntervalSeconds` option to `AmplitudeBootOptions` to configure the auto-refresh interval for the SDK (GSDK-799).
- \[Android\] \[iOS\] Add SDK method `setAutoRefreshInterval` to configure the auto-refresh interval for the SDK on the fly (GSDK-799).
- \[Android\] \[iOS\] Add SDK method `refresh` to manually trigger a refresh of targeting data (GSDK-799).
**Fixes**
- \[Android\] \[iOS\] Fix theming issues (GSDK-676).
- \[iOS\] Ensure Pin guide is displayed when it follows another guide in a Tour (a multi-step guide) (GSDK-827).
- \[Android\] Reposition nudge when keyboard shows (GSDK-782).
- \[Android\] Fix link appearance and click behavior (GSDK-821).
- \[Android\] Update components to use form control theme (GSDK-835).
- \[Android\] Ensure host app still receives touch events after session/activity changes (GSDK-198).
**Performance improvements**
- \[iOS\] View hierarchy tracking is now "async" and won't interfere with the main thread (GSDK-819).
## 2.0.3
Released January 26, 2026. Platforms: Android, iOS, React Native.
**Fixes**
- \[Android\] \[iOS\] Persist survey values when step-navigating (GSDK-582).
- \[Android\] \[iOS\] Hide buttons until text animation completes, if applicable (GSDK-780).
- \[Android\] Popover overlaps system bars because we were not consuming WindowInsets from host app appropriately (GSDK-784).
- \[Android\] Crash occurring on transition to a new activity that has `enableEdgeToEdge()` by waiting for root view to be attached to window (GSDK-768).
- \[iOS\] Ensure Modal Guides & Surveys are properly dismissed when `shutdown()` is called (GSDK-790).
- \[iOS\] Update default content alignment to leading GSDK-796.
- \[iOS\] Identify containerView as EngagementWindow to dismiss keyboard as needed GSDK-797.
- \[iOS\] Expand nudge to show Other textfield without scrolling (GSDK-779).
- \[React Native\] Internal engagement Android dependency version is incorrectly set.
## 2.0.2
Released January 9, 2026. Platforms: iOS.
**Fixes**
- \[iOS\] Compile SDK framework with Xcode 16.2 / Swift 6.0.3 for broader compatibility (GSDK-786).
## 2.0.1
Released January 7, 2026. Platforms: Android, iOS, React Native.
**Features**
- \[Android\] \[iOS\] Add `ignoreAnalyticsAutomaticScreenTracking` option to `AmplitudeInitOptions` to configure default Engagement SDK behavior for automatic screen tracking (GSDK-750).
**Fixes**
- \[Android\] Reset animation queue when nudge disappears (GSDK-518).
- \[Android\] \[iOS\] Crash in debug mode when used without calling "boot" on the SDK.
- \[iOS\] Ensure element selector and preview mode can be started when the other is active (GSDK-717).
- \[Android\] \[iOS\] Ignore Amplitude Analytics automatic screen tracking by default in Engagement SDK (GSDK-781).
## 2.0.0
Released January 2, 2026. Platforms: Android, iOS, React Native.
**Breaking changes**
- \[Android\] `AmplitudeEngagement` is now an interface rather than a class, and the `options` and `apiKey` are no longer accessible.
- \[Android\] \[iOS\] `AmplitudeInitOptions.Options` has been removed and `logLevel` now lives at the top level of the options object.
- \[Android\] `handlePreviewLinkIntent` is deprecated, use `handleLinkIntent` instead (GSDK-322).
**Features**
- \[Android\] \[iOS\] Add support for share links (GSDK-322).
- \[Android\] \[iOS\] Add support for custom tooltip size (GSDK-353).
- \[React Native\] Add support for `serverZone`, `serverUrl`, `cdnUrl`, `mediaUrl`, `logLevel` and `locale` init options (GSDK-767).
**Fixes**
- \[Android\] \[iOS\] Pin visibility logic and mask interactions (GSDK-748).
- \[iOS\] Allow banner content to expand vertically for tablet (GSDK-759).
- \[iOS\] Add finite checks before using actual content size in constraints (GSDK-761).
- \[iOS\] Maintain status bar visibility state when nudge shows (GSDK-758).
- \[iOS\] Fix arrow misalignment on scrolled pins (GSDK-725).
- \[Android\] Gracefully handle failure to initialize mobile SDK, instead of crashing host app (GSDK-775).
- \[Android\] Fix theming for step counter size and background color (GSDK-538).
- \[Android\] Correctly handle "null" user and device IDs (FOO-2908).
- \[iOS\] Remove `isObscuredByPresentedViewController` check for target view visibility (GSDK-720).
- \[iOS\] Tooltip is re-openable after using the "close" button to close it (GSDK-776).
- \[Android\] \[iOS\] Properly apply drop shadow to Guide/Survey cards from theme (GSDK-772).
- \[iOS\] Trigger display of matching guide/survey (if any) when user properties are updated through "\_setUserProperties" (FOO-2911).
- \[React Native\] React Native plugin automatically sets `serverZone` based on the server zone used for Amplitude initialization (GSDK-767).
- \[Android\] \[iOS\] Hook up nudge position/alignment fields to floating ui and improve arrow styles (GSDK-623, GSDK-684).
- \[Android\] \[iOS\] Fix button height calculation (GSDK-739).
- \[Android\] Fix close button foreground color from theme not being applied (GSDK-739).
**Performance improvements**
- \[iOS\] Event forwarding from Amplitude Analytics to G+S SDK is now "async" and won't interfere with the main thread (GSDK-763).
## 1.8.1
Released December 4, 2025. Platforms: iOS.
**Fixes**
- \[iOS\] Update default title+text alignment to leading (GSDK-733).
- \[iOS\] Bug causing app crash when Foundation.Data is used as an event property value (GSDK-736).
## 1.8.0
Released November 26, 2025. Platforms: Android, iOS, React Native.
**Features**
- \[iOS\] Update nudges to be scrollable for long content (GSDK-693).
- \[Android\] \[iOS\] Track nudge engagement event with link source (GSDK-144).
- \[Android\] \[iOS\] Respect modal height setting for carousels+modals on tablets.
**Fixes**
- \[Android\] Fix nps button height (GSDK-708).
- \[iOS\] Re-render mask + target view on device orientation changes (GSDK-441).
- \[Android\] Use theme background color for top+bottom of Carousel (GSDK-731).
- \[iOS\] Background mask for pins flickers when advancing between steps (GSDK-660).
- \[iOS\] Guide renders in top-left corner briefly before being moved to correct location (GSDK-718).
- \[Android\] Drop shadows on form factors is clipped and duplicated by Surface (GSDK-259).
- \[iOS\] Add support for conditional actions on button blocks (GSDK-726).
- \[Android\] Update spacing between ctas (GSDK-734).
## 1.7.1
Released November 21, 2025. Platforms: iOS.
**Fixes**
- \[iOS\] Additional logging for the `isObscuredByPresentedViewController` pin Guide target check, and flash a red background on the obscuring view to aid debugging (GSDK-720).
## 1.7.0
Released November 18, 2025. Platforms: Android, iOS, React Native.
**Fixes**
- \[React Native\] Type error when using the Engagement Analytics Plugin with "amplitude.add(...)" (GSDK-698).
- \[Android\] Guide title incorrectly center-aligned when left alignment was configured (GSDK-701).
- \[Android\] Allow underscore ("\_") separated font files on Android (GSDK-701).
- \[Android\] Use correct corner radius and outer padding when rendering Guide (GSDK-701).
- \[iOS\] App is unresponsive after displaying StoreKit content (for example, `manageSubscriptionsSheet`) (GSDK-699).
## 1.6.1
Released November 13, 2025. Platforms: Android, iOS, React Native.
**Fixes**
- \[Android\] \[iOS\] Update ordering of survey and media blocks (GSDK-689).
- \[iOS\] Fix threading issue for uikit click element (GSDK-571).
- \[iOS\] Fix nudge anchoring on custom nav bar behind transparent system nav bar (GSDK-664).
- \[Android\] Refactor view hierarchy scanning to improve performance on the Main thread.
## 1.6.0
Released November 7, 2025. Platforms: Android, iOS, React Native.
**Features**
- \[Android\] \[iOS\] Proxy support (GSDK-630). Go to [Proxy](https://amplitude.com/docs/guides-and-surveys/proxy).
- \[Android\] \[iOS\] Support 4 new popover Guide positions (top-center, bottom-center, left-center, right-center) (FOO-2639).
**Fixes**
- \[Android\] \[iOS\] Add debug logging to all SDK methods.
- \[Android\] Proper handling of null or blank user IDs on boot (GSDK-681).
- \[Android\] Theming fixes (incorrect colors, text alignment, popover Guide width, and so forth.) (GSDK-671).
- \[Android\] When pin target scrolls offscreen, guide should be displayed again when target re-appears (GSDK-651).
- \[iOS\] \[Android\] On tablets, modal carousel max width in theme is used, rather than device's max-width (GSDK-633, GSDK-616).
- \[iOS\] Stop showing previously previewed guide when initiating a new preview (GSDK-595).
- \[iOS\] Ensure URLs opened in browser are opened on main UI thread (GSDK-652).
- \[Android\] Odd whitespace appears when Guide content is right-aligned (GSDK-647).
- \[iOS\] Automatically call shutdown() when the user ID is set to `nil` through Amplitude Analytics SDK (#436).
- \[iOS\] Modal Guide moves from centered to top left of screen (GSDK-627).
- \[iOS\] App hangs when executing a callback through a CTA button (GSDK-458).
- \[iOS\] Banners using text animations have blank text (GSDK-638).
- \[iOS\] Tooltip markers not staying with their targeted element when scrolling vertically (GSDK-607).
- \[iOS\] Tooltip appearing without pointer (GSDK-607).
- \[iOS\] User-driven dismissal of tooltip should NOT hide the tooltip marker (GSDK-607).
- \[iOS\] Ensure user properties passed to `analytics.identify` are used for Guide user property interpolation (#415).
- \[iOS\] Prevent flickering for tooltips and closed-by-default pins (GSDK-659).
- \[iOS\] Allow pins to target navbar elements (GSDK-664).
- \[iOS\] Close button ("x") padding uses value from theme (GSDK-661).
- \[iOS\] Images sometimes not loading (GSDK-656).
- \[Android\] Add padding below bottom content on nudges (GSDK-687).
## 1.5.2
Released October 31, 2025. Platforms: iOS, React Native.
**Fixes**
- \[iOS\] \[React Native\] Crash when calling `setUserId`.
## 1.5.1
Released October 30, 2025. Platforms: Android, iOS, React Native.
**Breaking changes**
- \[Android\] \[iOS\] The `cleanup()` and `reboot()` functions have been removed, use `shutdown()` instead.
**Fixes**
- \[Android\] \[iOS\] \[React Native\] Ensure `shutdown()` removes all active nudges from view.
- \[Android\] \[iOS\] \[React Native\] Ensure non-JSON-safe values are serializable.
## 1.5.0
Released October 21, 2025. Platforms: Android, iOS, React Native.
**Breaking changes**
- \[Android\] \[iOS\] \[React Native\] Require calling `shutdown()` before calling `boot()` with a new user ID.
**Features**
- \[Android\] \[iOS\] Custom font support (GSDK-578, GSDK-620).
- \[Android\] Analytics plugin tracks changes to user ID (#355).
- \[Android\] \[iOS\] Support links and italics in Guide titles (GSDK-600).
**Fixes**
- \[iOS\] Multiple crashes involving QuickJS (GSDK-640, GSDK-625).
- \[Android\] Crash when rendering Guides in Android apps with multiple Activity or "plain" Activity (for example, not `AppCompatActivity`) (GSDK-589).
- \[iOS\] Crash on preview when using Debugger (#337).
- \[iOS\] "Arrow" for tooltip Guide not hiding when tooltip is closed (GSDK-609).
- \[iOS\] Carousel Guide is correct size on large (tablet) screens (GSDK-616).
- \[iOS\] Pin form factor "offset" positioning + alignment bugs (GSDK-593).
- \[iOS\] Modal and popover Guide snaps to the top-left rather than remaining in the configured position (GSDK-627).
- \[Android\] \[iOS\] \[React Native\] A race condition which could cause a Guide to be un-dismissable (#355).
- \[Android\] Condition causing duplicate carousel Guides (GSDK-641).
- \[iOS\] Text animations not always rendering properly (GSDK-638).
- \[Android\] \[iOS\] Issue causing Dark Mode theme to not be used, or incorrect colors to be used (GSDK-596, GSDK-612).
- \[Android\] \[iOS\] Remove extra spacing when actions are hidden (GSDK-421).
- \[Android\] Possible issue with "smart delay" trigger (GSDK-605).
- \[iOS\] Guide title font weight now defaults to semi-bold (GSDK-615).