Installation
The Intercom React Native wrapper allows you to use Intercom for iOS and Intercom for Android in your React Native apps.
If you’re new to Intercom, you’ll need to create an account and start your free trial.
Supported versions
- The Intercom React Native wrapper supports version 0.59 of React Native and above.
- Intercom for iOS supports iOS 15 and above.
- Intercom for Android supports API 21 and above.
Enable in your workspace
Step 1 - Adding the wrapper
To install Intercom you'll need to add the wrapper to your React Native project using the following snippet:
yarn add @intercom/intercom-react-native
npm install @intercom/intercom-react-native
There are separate steps for setting up Android and iOS. If your React Native app does not support Android skip to Step 3.
Step 2 - Android Setup
You'll need to take steps to link the wrapper in your project. These vary based on your apps React Native version.
Using React Native v0.60 and above
If you're using React Native v0.60 or above, the library will be linked automatically
Automatic linking with React Native v0.59
To automatically link the Intercom React Native wrapper in v0.59 of React Native run the following command:
react-native link @intercom/intercom-react-native
Manual linking with React Native v0.59
If you prefer to manually link libraries, add the following snippet to android/settings.gradle
:
include ':intercom-react-native' project(':intercom-react-native').projectDir = new File(rootProject.projectDir, '../node_modules/@intercom/intercom-react-native/android')
Inside the dependancies block of android/app/build.gradle
add the following line:
dependencies { implementation project(':intercom-react-native') }
React Native versions below 0.65 use OkHttp 3. The Intercom SDK currently uses OkHttp 4.
There is a problem with compatibility between those two versions which may result in crashes.
If you need to use a React Native version < 0.65, prevent the compatibility issue by adding an explicit dependency on okhttp-urlconnection
to dependencies in app/build.gradle
:
dependencies { implementation("com.squareup.okhttp3:okhttp-urlconnection:4.9.1") [...] }
Initialize Intercom
The minSdkVersion
in build.gradle
needs to be to 21
or greater.
In the dependencies block of the build.gradle
make sure that com.android.tools.build:gradle
is at version 4.0.1
You'll need to update the MainApplication.java
class. First add the import com.intercom.reactnative.IntercomModule
at the top of the class.
Then in the onCreate
method, add the snippet below using the apiKey
and appId
found in your workspace settings.
import com.intercom.reactnative.IntercomModule; // <-- Add this line // ... @Override public void onCreate() { super.onCreate(); SoLoader.init(this, /* native exopackage */ false); // ... IntercomModule.initialize(this, "apiKey", "appId"); // <-- Add this line // ... }
Android Permissions
Add below permissions to AndroidManifest.xml
You'll need to include the READ_EXTERNAL_STORAGE permission if you have enabled attachments:
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
You can also include VIBRATE to enable vibration in push notifications:
<uses-permission android:name="android.permission.VIBRATE"/>
Step 3 - iOS Setup
If you don't support iOS in your React Native app, you can skip to the configuration step.
Using React Native v0.60 and above
If you're using React Native v0.60 or above, the library will be linked automatically after running the pod install
command.
Manual linking with React Native v0.59
Firstly open your apps .xcworkspace
. If you don't have a .workspace
file open the .xcodeproj
.
Download intercom for iOS and extract the zip
Drag Intercom.xcframework into your project. Make sure "Copy items if needed" is selected and click Finish.
For additional information on iOS manual linking please refer to the React Native developer docs.
Initialize Intercom
Open iOS/AppDelegate.m
and import <IntercomModule.h>
#import "AppDelegate.h" #import <React/RCTBridge.h> #import <React/RCTBundleURLProvider.h> #import <React/RCTRootView.h> // ... #import <IntercomModule.h> // <-- Add This
Next, in the method didFinishLaunchingWithOptions
you'll need to initialize Intercom. Add the snippet below using the apiKey
and appId
found in your workspace settings.
// ... self.window.rootViewController = rootViewController; [IntercomModule initialize:@"apiKey" withAppId:@"appId"]; // <-- Add this (Remember to replace strings with your api keys) return YES; }
IOS Permissions
Camera usage:
You need to make sure that you have a NSCameraUsageDescription
entry in your Info.plist
. This is required by Apple to access device's camera. It is necessary when installing Intercom due to the camera upload functionality. Users will be prompted for the camera and permission only when they tap the camera upload button. You can also optionally add an entry for NSMicrophoneUsageDescription
. This is required if you wish to use record a video and upload it to a conversation.
Step 4 - Register your users
You’ll need to register your users with Intercom before you can talk to them or see what they do in your app. If a person visits your mobile app they will be a user - the Intercom SDKs do not create leads or visitors. There are three way to register people who visit your app: (1) register only unidentified users (2) register only identified users (3) register both identified and unidentified users. The option you choose should be informed by the design of your app, namely whether you have a login option.
Register only your unidentified users
If you have an app with no login option (like Angry Birds or a flashlight app), you should register unidentified users only.
Just register an unidentified user in your application like so:
Intercom.loginUnidentifiedUser();
Register only your identified (logged in) users
If people must log in to access your app (as with Facebook, Instagram or Slack) you should follow these instructions to register identified users only.
Best practices for registering users
- It is important to only register identified users after verification of a login.
- You can provide a userId and/or email when registering an identified user. We recommend giving all your users unique userIds, but if you haven't implemented this, you should provide an email.
- Don’t use an email address as a userId as this field cannot be changed later. If you choose provide only an email address, the email address must not be associated with any other users on your workspace.
Intercom.loginUserWithUserAttributes({ email: "bob@example.com", userId: "bob-123", });
Register both unidentified (non-logged in) and identified (logged in) users
If you have an app with both unidentified and identified users (like Google Maps or YouTube), you will need to either conditionally choose which registration to call:
if (loggedIn) { Intercom.loginUserWithUserAttributes({ email: "bob@example.com", userId: "bob-123", }); } else { Intercom.loginUnidentifiedUser(); }
Or you can register with Intercom.loginUnidentifiedUser()
and if a user signs up/logs in later in your app call Intercom.loginUserWithUserAttributes
. We will automatically transfer over any attributes or conversations from the unidentified user to the identified user, so you won't lose anything.
How to unregister an identified user
You should only unregister an identified user. Unregistering an unidentified user will result in orphan records that cannot be merged in future.
When users want to log out of your app, simply call:
Intercom.logout();
Intercom knows when your app is backgrounded and comes alive again, so you won’t need to re-register your users.
Using Intercom with Expo
If you are using Expo, you can use the built-in plugin. After installing the intercom-react-native package, add the config plugin to the plugins
array of your app.json
or app.config.js
:
{ "expo": { "plugins": ["@intercom/intercom-react-native"] } }
The plugin provides props for extra customization. Every time you change the props or plugins, you'll need to rebuild (and prebuild
) the native app. If no extra properties are added, defaults will be used.
appId
(string): App ID from Intercom.androidApiKey
(string): Android API Key from Intercom.iosApiKey
(string): iOS API Key from Intercom.intercomRegion
(string): Region for IntercomUS
,EU
,AU
. Optional. Defaults toUS
.
{ "expo": { "plugins": [ [ "@intercom/intercom-react-native", { "appId": "abc123", "androidApiKey": "android_sdk-abc123", "iosApiKey": "ios_sdk-abc123", "intercomRegion": "EU" // Europe } ] ] } }
Next, rebuild your app as described in the "Adding custom native code" guide.
Limitations
- No push notifications support: Intercom push notifications currently aren't supported by this config plugin extension.
What next?
- Configure your React Native app for Intercom and create customizations.
- Enable push notifications so you can send push messages.
- Enable Identity Verification for your React Native app.
- If Data Hosting in Europe, modify your app's region configuration