@amplitude/plugin-engagement-react-native

Amplitude Engagement plugin for React Native

Installation

To install:

• Add @amplitude/analytics-react-native and @amplitude/plugin-engagement-react-native
• Also, add @react-native-async-storage/async-storage
  • Why? This is used by the engagement native module, but the CLI only auto links native modules which you directly depend on in your app’s package.json

npm install @amplitude/analytics-react-native
npm install @react-native-async-storage/async-storage
npm install @amplitude/plugin-engagement-react-native

Re-run pod install in the ios directory:

$ cd ios
$ bundle exec pod install

Usage

Setup code

Setup by adding the plugin and calling “init” as usual:

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

Linking setup

If you don't already have it set up, please follow this guide to enable deep-linking support in your React Native app in addition to adding the above Linking code: https://reactnative.dev/docs/linking#enabling-deep-links

Then, following the Alpha Onboarding guide to setup the "scheme" for the deep links in your Android and iOS projects.

Boot

Finally, “boot” the plugin with the user’s ID; "booting" the SDK enables Guides and Surveys to be shown:

import {
  setDeviceId,
  setUserId,
} from '@amplitude/analytics-react-native';
import { useEffect } from 'react';
import { getPlugin } from '@amplitude/plugin-engagement-react-native';

export default function App() {
  useEffect(() => {
    //
    // NOTE: setting the User ID in @amplitude/analytics-react-native
    // --and-- passing it to boot() is necessary for now, but in a
    // future version will not be necessary
    //
    setUserId('rn-test-user-1');
    setDeviceId('test-device-1');
    getPlugin().boot('rn-test-user-1', 'test-device-1');
  }, []);

Integrations

To forward events tracked by the Guides and Surveys SDK to analytics providers other than Amplitude Analytics, pass integrations to boot(). Each integration is a callback that receives the event type and event properties for every tracked event:

getPlugin().boot({
  user: { user_id: 'rn-test-user-1', device_id: 'test-device-1' },
  integrations: [
    (eventType, eventProperties) => {
      // e.g. forward to your third-party analytics provider
      thirdPartyAnalytics.track(eventType, eventProperties);
    },
  ],
});

License

MIT