Articles in this section

Installing Iterable's React Native SDK

Table of contents

Requirements

Iterable's React Native SDK depends on the following:

Sample application

The repository for Iterable's React Native SDK contains JavaScript and TypeScript sample applications that have been configured to use the SDK.

Instructions

To set up Iterable's React Native SDK, follow these instructions:

1. Install the SDK package

To install the package for Iterable's React Native SDK:

  • If you use Yarn, run this command:

    yarn add @iterable/react-native-sdk

  • If you use npm, run this command:

    npm install @iterable/react-native-sdk

2. Install other dependencies

Next, install some other necessary dependencies:

  • For iOS, navigate to the ios folder and run pod install. If you see errors, try pod install --repo-update.

  • For Android, there are no more dependencies to install.

3. Configure your native iOS project

To use Iterable's features with your React Native iOS application, first configure its Xcode project and native code to handle push notifications, in-app messages and deep links:

  1. In the Apple Developer Portal:

  2. In Iterable:

  3. In Xcode:

    TIP

    As you reference Iterable's SDK in your iOS code, be sure to add import statements as needed.

TIP

Take a look at the sample app's AppDelegate file to see an implementation of some of the above configuration.

4. Configure your native Android project

To use Iterable's features with your React Native Android application, first configure its native code to handle push notifications, in-app messages, and deep links:

  1. Set up Firebase for your Android app:

    • Add the Google Services Gradle Plugin as a dependency (for example, classpath 'com.google.gms:google-services:4.3.3') in your root-level build.gradle file (not your app's build.gradle file). Then, apply the plugin by adding this line to your app-level build.gradle file: apply plugin: 'com.google.gms.google-services'.

    • Add the Firebase Cloud Messaging SDK, as a dependency (for example, implementation "com.google.firebase:firebase-messaging:20.2.3") in your app's build.gradle file (not the root build.gradle file).

  2. In Iterable, create a mobile app and give it a push integration.

    By default, the React Native SDK looks for a push integration that has the same package name as your app (but you can change this setting IterableConfig.pushIntegrationName).

  3. If you're using ProGuard, update its configuration for Iterable's Android SDK.

  4. To handle deep links:

  5. Starting with version 1.1.0+ of Iterable's React Native SDK, you'll need to update your Android application's Application class:

    • Add this import:

      import com.iterable.iterableapi.IterableApi;

    • At the end of the onCreate method, add this line of code:

      IterableApi.setContext(this);

5. Import classes as needed

In your JavaScript or TypeScript code, import classes from Iterable's React Native SDK whenever you need to reference them.

For example, to reference the Iterable and IterableConfig classes in a particular file in your app's source code, include this import statement:

import { Iterable, IterableConfig } from '@iterable/react-native-sdk';

To see the various classes you may need to import, take a look at Iterable.ts and IterableInAppClasses.ts, in Iterable's React Native SDK GitHub repository.

6. Initialize the SDK

To initialize Iterable's React Native SDK in your app's JavaScript or TypeScript code, call the static initialize method on the Iterable class and pass the following parameters:

  • A mobile API key from Iterable. To learn how to create one, read API keys.

    WARNING

    Never use server-side API keys with Iterable's mobile SDKs. Since API keys are, by necessity, distributed with the mobile apps that contain them, bad actors can potentially access them. For this reason, Iterable provides mobile API keys, which have minimal access.

  • An IterableConfig object with various properties set:

    • pushIntegrationName - The name of the Iterable push integration that will send push notifications to your app. Defaults to your app's application ID (Android) or bundle ID (iOS). Don't specify this value unless you're using an older Iterable push integration that has a custom name.

    • autoPushRegistration - When true (the default value), causes the SDK to automatically register and deregister for push tokens when you provide email or userId values to the SDK.

    • inAppDisplayInterval - When displaying multiple in-app messages in sequence, the number of seconds to wait between each. Defaults to 30 seconds.

    • urlHandler - A function expression used to handle deep link URLs and in-app message button and link URLs.

    • authHandler - A function expression that provides a valid JWT for the app's current user to Iterable's React Native SDK. Provide an implementation for this method only if your app uses a JWT-enabled API key.

    • expiringAuthTokenRefreshPeriod - The number of seconds before the current JWT's expiration that the SDK should call the authHandler to get an updated JWT.

    • customActionHandler - A function expression used to handle action:// URLs for in-app message buttons and links.

    • allowedProtocols - Use this array to declare the specific URL protocols that the SDK can expect to see on incoming links from Iterable, so it knows that it can safely handle them as needed. This array helps prevent the SDK from opening links that use unexpected URL protocols.

      For example, to allow the SDK to handle http, tel, and custom links, use code similar to this:

      JavaScript

      const config = new IterableConfig()
config.allowedProtocols = ["http", "tel", "custom"]

      IMPORTANT

      Iterable's React Native SDK handles https, action, itbl, and iterable links, regardless of the contents of this array. However, you must explicitly declare any other types of URL protocols you'd like the SDK to handle (otherwise, the SDK won't open them in the web browser or as deep links).

Example SDK configuration

JavaScript

import { IterableConfig } from '@iterable/react-native-sdk';

const config = new IterableConfig();
config.authHandler = () => {
    // ... Fetch a JWT from your server, or locate one you've already retrieved
    return new Promise(function (resolve, reject) {
        // Resolve the promise with a valid auth token for the current user
        resolve("<AUTH_TOKEN>")
    });
};
config.autoPushRegistration = false;

Iterable.initialize('<YOUR_API_KEY>', config);

This example demonstrates how an app that uses a JWT-enabled API key might initialize the SDK. To make requests to Iterable's API using a JWT-enabled API key, you should first fetch a valid JWT for your app's current user from your own server, which must generate it. The authHandler provides this JWT to Iterable's React Native SDK, which can then append the JWT to subsequent API requests. The SDK automatically calls authHandler at various times:

  • When your app sets the user's email or user ID.
  • When your app updates the user's email.
  • Before the current JWT expires (at a configurable interval set by expiringAuthTokenRefreshPeriod)
  • When your app receives a 401 response from Iterable's API with a InvalidJwtPayload error code. However, if the SDK receives a second consecutive 401 with an InvalidJwtPayload error when it makes a request with the new token, it won't call the authHandler again until you call setEmail or setUserId.

TIP

For more information about JWT-enabled API keys, read JWT-Enabled API Keys.

7. Test your mobile apps with Iterable

To test that you've successfully set up Iterable's React Native SDK in your iOS and Android apps, follow these instructions once for each platform:

  1. At some point in your app's React Native code, call Iterable.setEmail, passing in a test email address that does not yet exist in your Iterable project. For example:

    Iterable.setEmail("docs@iterable.com");

  2. Run the app until it calls setEmail, which creates an Iterable user profile.

    • Test your iOS app on a physical device. When prompted, allow the app to display push notifications.
    • Test your Android app on a physical device or an emulator.

  3. To verify that Iterable now has a user profile for the new email address, navigate to Audience > Contact Lookup and search it.

  4. Send a push notification:

    • For iOS, move the app to the background (since some iOS apps do not display push notifications for apps that are in the foreground).

    • In Iterable, create a push notification campaign. On step 3 (Design) of the campaign creation process, send a proof to the email address configured above. The push notification should appear on your device.

TIPS

If the above steps don't work, make sure that you're using a valid mobile API key in your React Native code, and that you've correctly configured your native iOS project and your native Android project. If you're still having trouble, please contact your Iterable CSM.

Upgrading the SDK

This section describes how to upgrade from earlier versions of Iterable's React Native SDK.

Upgrading to version 1.2.0+

When upgrading to version 1.2.0+ of Iterable's React Native SDK, you'll need to provide a value for the allowedProtocols array on IterableConfig. This array tells the SDK what types of links it can expect to find in the campaigns you send from Iterable, so that it knows it's safe to handle them. For more details, read about initializing the SDK.

Further reading

Related articles

Comments

0 comments

Article is closed for comments.