Guides and Surveys React Native SDK

Amplitude's Guides and Surveys SDK enables you to deploy 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.
• 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 install @amplitude/plugin-engagement-react-native
npm install @react-native-async-storage/async-storage

Run pod install in the ios directory.

cd ios
bundle exec pod install

Initialize the SDK

//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
});

Configuration options

Boot the plugin

Booting the plugin (with a user ID) enables Guides and Surveys to be shown:

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 */,
    );
  }, []);
}

boot also accepts an options object. If your app doesn't use the Amplitude Analytics React Native SDK, include integrations in that call.

import { boot } from "@amplitude/plugin-engagement-react-native";

// Basic boot with user ID
boot("USER_ID");

// Advanced boot with options
boot({
  user: {
    user_id: "USER_ID",
    device_id: "DEVICE_ID",
    user_properties: { key: "value" },
  },
  integrations: [
    (eventType, eventProperties) => {
      // Custom event handler
    },
  ],
});

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.

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:

<activity android:name=".MainActivity">
    <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <!-- Add your URL scheme from Amplitude Dashboard here -->
    <!-- ex: android:scheme="amp-12345" -->
    <data android:scheme="<your-unique-scheme-id>" />
    </intent-filter>
</activity>

URL handling for preview links

The initialization code snippet handles URL handling for preview links. The relevant code is:

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

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.

import { screen } from "@amplitude/plugin-engagement-react-native";

// Track screen views to trigger guides based on screens
screen("HomeScreen");

Pin, tooltip, and card embed guides require the SDK to target specific views on screen. Pins and tooltips anchor an overlay to a target view, while card embeds render inline before, after, or in place of a view. The two use different APIs, but in both cases the identifier you set in React Native must match the element targeting string you configure on the guide in the Guides and Surveys dashboard.

Pins and tooltips

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.

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 (
    <View
      testID="welcome-banner" // Element targeting through testID
      style={styles.banner}
    >
      <Text style={styles.bannerText}>Welcome to the App!</Text>
    </View>
  );
}

Card embed

Card embeds render inline, so they use the AmplitudeCardEmbedView component. Wrap the target in AmplitudeCardEmbedView and give it an identifier. When a card embed guide targets that identifier, the card takes up space in your layout and surrounding content moves out of the way. The SDK renders the card before, after, or in place of the children, based on the position you set in the dashboard.

import { Text } from "react-native";
import { AmplitudeCardEmbedView } from "@amplitude/plugin-engagement-react-native";

export default function WelcomeBanner() {
  return (
    <AmplitudeCardEmbedView identifier="welcome-banner">
      <Text>Welcome to the App!</Text>
    </AmplitudeCardEmbedView>
  );
}

AmplitudeCardEmbedView fills the width of its parent, so the width and alignment you set on the guide apply to the card. A testID alone still targets the view, but the card layers over surrounding content instead of taking up space. Use AmplitudeCardEmbedView for card embeds, and testID for pins and tooltips.

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:

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",
  }),
);

To dynamically update the language after the SDK initializes, use the updateLanguage method. Calling updateLanguage re-fetches the configuration with the new locale.

updateLanguage(locale: string): Promise<void>

import { updateLanguage } from "@amplitude/plugin-engagement-react-native";

// Example: Update language to French with full locale
updateLanguage("fr-FR");

// Example: Update language to English with language code
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.

import { disable, enable } from "@amplitude/plugin-engagement-react-native";

// Temporarily disable the SDK
disable();

// Re-enable the SDK
enable();

Register a button callback

Register a function that runs when a user taps a guide or survey button with the Run callback action. The key you pass to addCallback must match the callback name you enter on that button.

addCallback(key: string, func: () => void): () => void

addCallback returns a function that removes the callback.

import { Alert } from "react-native";
import { addCallback } from "@amplitude/plugin-engagement-react-native";

addCallback("show-alert", () => {
  Alert.alert("Callback", "Callback has been executed!");
});

Router configuration

Configure how Guides and Surveys handles screen navigation.

import { setRouter } from "@amplitude/plugin-engagement-react-native";

setRouter((url) => {
  // Your screen handling and navigation
});

To remove the router, call unsetRouter().

import { unsetRouter } from "@amplitude/plugin-engagement-react-native";

unsetRouter();

List

Retrieve a list of all live guides and surveys along with their status.

import { list } from "@amplitude/plugin-engagement-react-native";

const guidesAndSurveys = await list();

Show

Display a specific guide or survey. Ignores any targeting rules and limits except for screen targeting.

import { show } from "@amplitude/plugin-engagement-react-native";

show("GUIDE_KEY", 0);

Forward event

If you don't use the Amplitude Analytics React Native 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.

import { forwardEvent } from "@amplitude/plugin-engagement-react-native";

forwardEvent({
  event_type: "Button Clicked",
  event_properties: { name: "Submit" },
});

Close all

Close all active guides and surveys.

import { closeAll } from "@amplitude/plugin-engagement-react-native";

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

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.

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.

View flattening and element targeting

React Native supports a feature called View Flattening, which is enabled by default. When React Native flattens a view, it removes the view from the native view hierarchy, making it unavailable for pin guide targeting or "On element tapped" triggers.

<View testID="my-element" collapsable={false}>
  {/* view content */}
</View>

Changelog

Go to the Mobile SDK changelog.