Guides and Surveys React Native SDK

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

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

yarn add @amplitude/plugin-engagement-react-native
yarn add @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 {
  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');
    getPlugin().boot('rn-test-user-1', 'test-device-1');
  }, []);
}

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, it appears as a platform option when you create or edit guides and surveys. This enables you to deliver guides and surveys to your React Native app users.

Set a minimum SDK version (when needed)

Minimum SDK version is available for mobile SDK versions 3.0.0 and later. 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.

This setting lets you 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 and tooltip guides require the ability for 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 example component below, "welcome-banner" is the element targeting string that should be used 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 via testID
      style={styles.banner}
    >
      <Text style={styles.bannerText}>
        Welcome to the App!
      </Text>
    </View>
  );
}

Simulate Guides and Surveys for preview

Previewing guides and surveys direclty in your application allows you to experience what your users will. Previewing makes it much easier to iterate on copy, targeting rules, trigger logic, etc.

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

Setting 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 already takes care of URL handling for preview links. Specifically, this code:

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

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.

Changelog

You can access the changelog here.