# @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`

```sh
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:

```sh
$ 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