Articles in this section

Installing Iterable's React Native SDK

This article describes how to install Iterable's React Native SDK in your React Native apps, and how to configure your iOS and Android apps to support Iterable features like push notifications and in-app messages.

In this article

Requirements

Iterable's React Native SDK depends on the following:

React Native

iOS

Android

Sample application

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

Encrypted data

Starting with version 1.3.7, Iterable’s React Native SDK, as a privacy enhancement, includes support for encrypting some data stored at rest.

Which data gets encrypted depends on mobile platform, since Iterable's React Native SDK relies on Iterable's underlying iOS and Android SDKs. For more information, read about:

Instructions

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

Step 1: Install the SDK package

Run one of these commands in your project's directory (depending on which package manager you use):

yarn add @iterable/react-native-sdk
npm install @iterable/react-native-sdk

If your app will use a mobile inbox, you'll also need to install the React Native Webview package.
To do this, run one of these commands:

yarn add react-native-webview
npm install react-native-webview

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

Step 3: iOS app setup

After installing the Iterable's React Native SDK, you'll need to make some updates in the Apple Developer Portal, in Iterable, and in your app's Xcode project:

Step 3.1: Configure your App ID

In the Apple Developer Portal, configure your App ID to support push notifications, and export an auth token or push certificate. To learn more, read Setting up iOS Push Notifications.

Step 3.2: In Iterable, set up a mobile app

In Iterable, create a mobile app and give it a push integration. For more details, read Setting up iOS Push Notifications.

Step 3.3: Import the SDK

To use Iterable's SDK in your code (for example, in your app delegate), add import statements wherever necessary:

Objective-C

@import IterableSDK;

Swift

import IterableSDK

To use Iterable's SDK with apps built on React Native versions 0.68 or higher, which rely on Objective-C++, if you encounter any build errors, you may need to do things a little differently:

  1. Download the Objective-C compatibility header for Iterable's SDK.

  2. Add the header file to your Xcode project.

  3. In the Objective-C++-based AppDelegate class generated by React Native, use this import statement instead of the ones shown above:

    Objective-C++

    #import "IterableSDK-Swift.h"

NOTES

For more information about Objective-C compatibility headers, check out Apple's documentation.

We've also generated an Objective-C compatibility header for IterableAppExtensions. If you have trouble importing Iterable's app extensions in your app's Notification Service Extension, try downloading this file, adding it to your Notification Service Extension in Xcode, and importing it with this statement:

Objective-C

#import "IterableAppExtensions-Swift.h"

Step 3.4: Update your project's build settings

If you've created your iOS app with React Native 0.63+, you'll need to make some configuration changes to ensure that archiving works as expected:

  1. Open your app's workspace in Xcode.

  2. In the Project Navigator, select your project's icon.

  3. In Targets, select the target you'll need to archive.

  4. On the Build Settings tab, enable the All and Levels filters.

  5. In the search box, enter Library Search Paths.

  6. Select the top-level entry that includes the Debug and the Release build configuration.

  7. Remove "$(TOOLCHAIN_DIR)/usr/lib/swift-5.0/$(PLATFORM_NAME)" (but not the .../lib/swift/... entry, which is still necessary).

Test these changes as early as possible in your development cycle, to help you avoid any problems when you're trying to release. If you have any trouble, contact Iterable Support. See Working with Iterable Support.

TIP

If you see this error when distributing your build to Apple:

The bundle at <EXTENSION_BUNDLE_ID> contains disallowed file 'Frameworks'.

Try navigating to the build settings for your extension's target, and setting Always Embed Swift Standard Libraries to No.

Step 3.5: Set up support for push notifications

To add support for push notifications to your app:

  1. Add the Push Notifications capability.

  2. Add the Remote Notifications background mode to your app.

  3. If you'll be sending Time Sensitive push notifications (introduced in iOS 15), add the Time Sensitive Notifications capability to your app.

  4. In your code, register the device token with Iterable. To do this, implement application(_:didRegisterForRemoteNotificationsWithDeviceToken:).

  5. If needed, have your code request permission to display push notifications.

  6. Handle incoming push notifications and enable push notification tracking, as described here.

  7. Set up support for rich push notifications, which can include media attachments and action buttons:

    • Create a Notification Service Extension.

    • Install the Iterable-iOS-AppExtensions pod:

      • Open the Podfile that's found in your React Native project's ios folder.

      • Specify a platform of 10.0 or higher (as required by your app):

        platform :ios, '11.0'

      • Add the Iterable-iOS-AppExtensions pod:

        target '<YOUR_NOTIFICATION_EXTENSION_TARGET>' do
  pod 'Iterable-iOS-AppExtensions'
end

      • Save the Podfile.

      • Run pod install to install the new pod. If you see errors, try try pod install --repo-update (docs).

        IMPORTANT

        After you've added the Iterable-iOS-AppExtensions pod to your project, you'll need to import it in your code. Be sure to read Step 3.3: Import the SDK for important instructions about how to do this with React Native versions 0.68 and higher.

    • Configure the Notification Service Extension to use a base class provided by Iterable's iOS SDK.

Step 3.6: Add support for in-app messages

To add support for in-app messages to your app, follow these instructions.

To support deep links in your React Native mobile apps:

  1. Configure your Iterable project to support deep links.

  2. Follow the instructions in Configuring your app to support deep links.

TIP

For an implementation of some of the above steps, take a look at this sample app delegate.

Step 4: Android app setup

To use Iterable's features with your React Native Android application, follow these steps:

Step 4.1: Set up Firebase

To set up Firebase for your Android app:

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

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

Step 4.2: In Iterable, set up a mobile app

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 (to change this, set IterableConfig.pushIntegrationName).

Step 4.3: Update your ProGuard configuration

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

To support deep links in your React Native mobile apps:

  1. Configure your Iterable project to support deep links.

  2. Follow the instructions in Configuring your app to support deep links.

Step 4.5: Update your app's Application class

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

  1. Add this import:

    import com.iterable.iterableapi.IterableApi;

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

    IterableApi.setContext(this);

Step 5: Import Iterable SDK classes wherever 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.

Step 6: Initialize Iterable's React Native 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:

    • dataRegion — If your Iterable project is hosted on Iterable's European data center (EDC), set this value to IterableDataRegion.EU (a constant provided in the SDK). This configures the SDK to interact with Iterable's EDC-based endpoints.

    • pushIntegrationName - The name of the Iterable push integration that will send push notifications to your app. Defaults to your app's application ID 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).

    • useInMemoryStorageForInApps — Determines whether Android and iOS apps should store in-app messages in memory, rather than in an unencrypted local file (defaults to false).

      NOTE

      For more information about this option, and the deprecated-but-related androidSdkUseInMemoryStorageForInApps available in version 1.3.7 of Iterable's React Native SDK, read the release notes for version 1.3.9

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 without passing in an auth token.

    TIP

    The setEmail and setUserId mobile SDK methods accept an optional, prefetched auth token. If you encounter SDK errors related to auth token requests, try using this parameter.

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

Step 7: Test your apps

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("user@example.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. While creating the campaign, send a test message to the email address configured above. The push notification should appear on the device.

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 iOS and Android projects, as described in this article. If you're still having trouble, contact Iterable Support.

Upgrading the SDK

Here are some instructions that describe how to upgrade from earlier versions of Iterable's React Native SDK.

Upgrading to version 1.3.9+

Version 1.3.9 of Iterable's React Native SDK allows iOS apps to store in-app messages in memory, rather than in an unencrypted local file.

To learn more about upgrading to this version of the SDK, read the release notes.

Upgrading to version 1.3.7+

Version 1.3.7 of Iterable's React Native SDK, as a privacy enhancement, includes support for encrypting some data stored at rest. Additionally, it allows Android apps to store in-app messages in memory, rather than in an unencrypted local file.

To learn more about upgrading to this version of the SDK, read the release notes.

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 Initializing Iterable's React Native SDK.

Further reading

Related articles