Table of contents
Requirements
Iterable's React Native SDK depends on the following:
-
React Native
-
iOS
- Xcode 12.0+
- 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
pod install
. If you see errors, trypod 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:
-
In the Apple Developer Portal:
-
In Iterable:
-
In Xcode:
TIP
As you reference Iterable's SDK in your iOS code, be sure to add
import
statements as needed.-
If you created your iOS app with React Native 0.63+, make the following change (so that archiving works as expected):
- Open your app's workspace in Xcode.
- In the Project Navigator, select your project's icon (usually near the top).
- Under Targets, select the target you'll need to archive.
- On the Build Settings tab, enable the All and Levels filters.
- In the search box, enter
Library Search Paths
. - Select the top-level entry that includes the
Debug
and theRelease
build configuration. - Remove
"$(TOOLCHAIN_DIR)/usr/lib/swift-5.0/$(PLATFORM_NAME)"
(but not the.../lib/swift/...
entry, which is still necessary).
TIPS
- Test out the Xcode archiving process as early as possible, to make sure that it works when it comes to submission time. If you see any errors related to the Iterable SDK when archiving, please contact your CSM.
- If you see an error when distributing your build to Apple with the message:
"The bundle at <extension's bundle ID> contains disallowed file 'Frameworks'.
, try settingAlways Embed Swift Standard Libraries
toNo
for the extension by going to theBuild Settings
of the extension's target.
Add the Push Notifications capability and Remote Notifications background mode to your app. If you'll be sending Time Sensitive push notifications (introduced in iOS 15), also add the Time Sensitive Notifications capability.
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):
-
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 aplatform
of10.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
pod install
to install the new pod. If you see errors, trypod install --repo-update
. 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.
Follow the instructions in Deep Links and Custom Actions with Iterable's React Native SDK.
-
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:
-
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).
-
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
). If you're using ProGuard, update its configuration for Iterable's Android SDK.
-
To handle deep links:
Make sure your Iterable project has been configured to support deep links.
Follow the instructions in Deep Links and Custom Actions with Iterable's React Native SDK.
-
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
- Whentrue
(the default value), causes the SDK to automatically register and deregister for push tokens when you provideemail
oruserId
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 theauthHandler
to get an updated JWT.customActionHandler
- A function expression used to handleaction://
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
, andcustom
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
, anditerable
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 anInvalidJwtPayload
error when it makes a request with the new token, it won't call theauthHandler
again until you callsetEmail
orsetUserId
.
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:
-
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");
-
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.
To verify that Iterable now has a user profile for the new email address, navigate to Audience > Contact Lookup and search it.
-
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.
Comments
0 comments
Article is closed for comments.