Installing Iterable's React Native SDK

# Table of contents

# Requirements

Iterable's React Native SDK depends on the following:

• React Native

  • React Native 0.60.0+
  • React Native CLI 2.0.1+

• iOS

  • Xcode 11+
  • Deployment target 10.0+
  • Iterable's iOS SDK
    • The instructions below will install this SDK for you.

• Android

  • minSdkVersion 16+, compileSdkVersion 28+
  • Iterable's Android SDK
    • The instructions below will install this SDK for you.

# 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 the following command:

  pod install
  

• 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:

   • Configure your App ID to support push notifications

   • Export your push notification certificate.

2. In Iterable:

   • Create a mobile app.

   • Assign a push integration to the mobile app.

3. In Xcode:

   TIP

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

   • Add the Push Notifications capability and Remote Notifications background mode to your app.

   • In your app, register the device token with Iterable (by implementing application(_:didRegisterForRemoteNotificationsWithDeviceToken:)).

   • Handle incoming push notifications and enable push notification tracking.

   • Configure support for in-app messages.

   • If necessary, have your code request permission to display push notifications.

   • If necessary, configure support for rich push notifications (which contain media attachments or action buttons):

     • Create a Notification Service Extension.

     • Add the Iterable-iOS-AppExtensions dependency to your app.

       To do this, navigate to your React Native project's ios folder and edit the Podfile. Specify a platform of 10.0 or higher (whatever your app requires):

       platform :ios, '11.0'
       

       Then, add the Iterable-iOS-AppExtensions pod:

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

       Save the file and run this command to install the new pod:

       pod install
       

     • Finally, configure the Notification Service Extension to take advantage of a base class provided by Iterable's iOS SDK.

   • To handle deep links:

     • Make sure your Iterable project has been configured to support deep links.

     • Set up Universal Links for your iOS app. Make sure to implement application(_:continue:restorationHandler:) in its native code.

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

   • 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. To handle deep links:

   • Make sure your Iterable project has been configured to support deep links.

   • Set up Android App Links for your Android app.

# 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:

• An Iterable Mobile API key. To learn how to create one, read API keys.

  WARNING

  Never use Standard 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.

  • checkForDeferredDeepLink - When true (defaults to false), causes the SDK to check for deferred deep links when the app runs the first time after being installed from a store.

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

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

For example:

const config = IterableConfig();
config.autoPushRegistration = false;
config.checkForDeferredDeepLink = true;
Iterable.initialize('<YOUR_API_KEY>', config);

For another example, take a look at the sample app's App.js file.

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

# Further reading

• React Native
• Iterable's React Native SDK (GitHub)
• Iterable's iOS SDK
• Iterable's iOS SDK (GitHub)
• Iterable's Android SDK
• Iterable's Android SDK (GitHub)
• Iterable's API