React Native wrapper to bridge our iOS and Android SDK

• Installation
  • Android
    • Automatic linking (React Native <=0.59)
    • Manual linking (React Native <=0.59)
    • Setup
    • Permissions
    • Push Notifications
    • Push notification deep links support
  • iOS
    • Manual linking (React Native <=0.59)
    • Setup
    • Permissions
    • Push Notifications
    • Push notification deep links support
  • Expo
    • Push Notifications
    • Push notification deep links support
      • Android
      • iOS
• Common methods
  • Types
• Usage
• Troubleshooting
• Author
• License

$ npm install @intercom/intercom-react-native

or

yarn add @intercom/intercom-react-native

If you're using React Native v0.60 or above, the library will be linked automatically without any steps being taken.

$ react-native link @intercom/intercom-react-native

• Add below code to android/settings.gradle

include ':intercom-react-native'
project(':intercom-react-native').projectDir = new File(rootProject.projectDir, '../node_modules/@intercom/intercom-react-native/android')

• Then edit android/app/build.gradle, inside dependencies at very bottom add

implementation project(':intercom-react-native')

• Add below lines to android/app/src/main/java/com/YOUR_APP/app/MainApplication.java inside onCreate method, replacing apiKey and appId which can be 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

  // ...
}

• Open android/build.gradle and change minSdkVersion to 21, compileSdkVersion to at least 34 and targetSdkVersion to at least 33

buildscript {
    // ...
    ext {
        buildToolsVersion = "29.0.2"
        minSdkVersion = 21 // <-- Here
        compileSdkVersion = 34 // <-- Here
        targetSdkVersion = 33 // <-- Here
    }
    // ...
}

• In android/build.gradle make sure that com.android.tools.build:gradle version is greater than 4.0.0

dependencies {
    classpath("com.android.tools.build:gradle:4.0.1")
    // ...
}

You will need to include the READ_EXTERNAL_STORAGE permission in android/app/src/main/AndroidManifest.xml 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"/>

For Push notification support add GoogleServices and Firebase Cloud Messagng to your app.

More information about push notification setup HERE

• Inside android/build.gradle add

buildscript {
    // ...
    dependencies {
        // ...
        classpath 'com.google.gms:google-services:4.2.0' // <-- Add this
    }
}

• In android/app/build.gradle in dependencies add Firebase Messaging and at the very bottom apply Google Services Plugin:

// ...

dependencies{
    implementation "com.facebook.react:react-native:+"

    implementation 'com.google.firebase:firebase-messaging:20.2.+' // <-- Add this
    // ...
}
// ...

apply plugin: 'com.google.gms.google-services' // <-- Add this
apply from: file("../../node_modules/@react-native-community/cli-platform-android/native_modules.gradle"); applyNativeModulesAppBuildGradle(project)

• Place google-services.json in android/app directory.

• Create MainNotificationService.java inside your app directory(com.example.app) with below content:

  Remember to replace package com.example.app;, with your app package name

package com.example.app;

import com.google.firebase.messaging.FirebaseMessagingService;
import com.google.firebase.messaging.RemoteMessage;
import com.intercom.reactnative.IntercomModule;

public class MainNotificationService extends FirebaseMessagingService {

  @Override
  public void onNewToken(String refreshedToken) {
    IntercomModule.sendTokenToIntercom(getApplication(), refreshedToken);
    //DO LOGIC HERE
  }

  public void onMessageReceived(RemoteMessage remoteMessage) {
    if (IntercomModule.isIntercomPush(remoteMessage)) {
      IntercomModule.handleRemotePushMessage(getApplication(), remoteMessage);
    } else {
      // HANDLE NON-INTERCOM MESSAGE
    }
  }
}

• Edit AndroidManifest.xml. Add below content inside <application> below <activity/>

Make sure that xmlns:tools="http://schemas.android.com/tools" is added to manifest tag

<!-- Add xmlns:tools to manifest. See example below-->
<manifest
  xmlns:tools="http://schemas.android.com/tools"
>
  <application>
    <activity>
      ...
    </activity>
    ...

    <!-- START: Add this-->
    <service
      android:name=".MainNotificationService">
      <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT"/>
      </intent-filter>
    </service>

    <receiver
      android:name="com.intercom.reactnative.RNIntercomPushBroadcastReceiver"
      tools:replace="android:exported"
      android:exported="true"/>
    <!-- END: Add this-->

  </application>
</manifest>

• Add below code to your React Native app

  useEffect(() => {
    /**
     * Handle PushNotification
     */
    const appStateListener = AppState.addEventListener(
      'change',
      (nextAppState) =>
        nextAppState === 'active' && Intercom.handlePushMessage()
    );
    return () => AppState.removeEventListener('change', () => true); // <- for RN < 0.65
    return () => appStateListener.remove() // <- for RN >= 0.65
  }
  , [])

• Add below code to <activity> inside AndroidManifest.xml

<activity
  android:name=".MainActivity"
  android:label="@string/app_name"
  android:configChanges="keyboard|keyboardHidden|orientation|screenSize|uiMode"
  android:launchMode="singleTask"
  android:windowSoftInputMode="adjustResize">
  <intent-filter>
    <action android:name="android.intent.action.MAIN"/>
    <category android:name="android.intent.category.LAUNCHER"/>
  </intent-filter>

  <!--  START: Add this  -->
  <intent-filter>
    <action android:name="android.intent.action.VIEW"/>
    <category android:name="android.intent.category.DEFAULT"/>
    <category android:name="android.intent.category.BROWSABLE"/>

    <data android:scheme="http" android:host="Your app url(www.app.com)"/> <!-- Edit this line -->
    <data android:scheme="Your app scheme(app)"/> <!-- Edit this line -->
  </intent-filter>
  <!--  END: Add this  -->

</activity>

Add the following in your MainActivity

  override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    setIntent(intent)
  }

See the example app for an example of how to handle deep linking in your app.

Intercom for iOS requires a minimum iOS version of 15.

cd ios
pod install
cd ..

If you're using React Native v0.60 or above, the library will be linked automatically without any steps being taken.

See How to manually link IOS Intercom SDK

• Open ios/AppDelegate.m then add below code:

• At the top of file add the following:

#import "AppDelegate.h"
#import <React/RCTBridge.h>
#import <React/RCTBundleURLProvider.h>
#import <React/RCTRootView.h>
// ...
#import <IntercomModule.h> // <-- Add This

• Inside didFinishLaunchingWithOptions before return YES add, remember to replace apiKey and appId which can be 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;
  }

Add this permission to your Info.plist

<key>NSCameraUsageDescription</key>
<string>Access your camera to take photos within a conversation</string>

Note: You should request user permission to display push notifications. e.g. react-native-permissions

Add Push Notifications and Background Modes > Remote Notifications Details HERE

Option 1: In your JavaScript code

An example using react-native-notifications:

// Request notification permissions
Notifications.registerRemoteNotifications();

// When permission is granted, send the device token to Intercom using [Intercom.sendTokenToIntercom(token)](#intercomsendtokentointercomtoken)
Notifications.events().registerRemoteNotificationsRegistered(({ deviceToken }: Registered) => {
  Intercom.sendTokenToIntercom(deviceToken);
});

Option 2: In your native code

• In AppDelegate.m at the top add

#import <UserNotifications/UserNotifications.h>

• Request notification permissions when app launches by adding the following to didFinishLaunchingWithOptions before return YES;:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    // ...

    // START: Code to add
    UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
    [center requestAuthorizationWithOptions:(UNAuthorizationOptionAlert + UNAuthorizationOptionSound)
                          completionHandler:^(BOOL granted, NSError *_Nullable error) {
                          }];
    [[UIApplication sharedApplication] registerForRemoteNotifications];
    // END: Code to add

    return YES;
}

• In same file, above @end add the following to send the device token to Intercom when permission is granted:

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    [IntercomModule setDeviceToken:deviceToken];
}

@end

Add URL types

Setup of React Native deep links can be found Here

• Add import to AppDelegate.m

#import "AppDelegate.h"

#import <React/RCTBridge.h>
#import <React/RCTBundleURLProvider.h>
#import <React/RCTRootView.h>

#import <React/RCTLinkingManager.h> <--Add this

• Add below code to AppDelegate.m above @end

- (BOOL)application:(UIApplication *)application
   openURL:(NSURL *)url
   options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
  return [RCTLinkingManager application:application openURL:url options:options];
}


- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url
  sourceApplication:(NSString *)sourceApplication annotation:(id)annotation
{
  return [RCTLinkingManager application:application openURL:url
                      sourceApplication:sourceApplication annotation:annotation];
}

@end

See the example app for an example of how to handle deep linking in your app.

If you are using Expo, you can use the built-in plugin.

After installing this npm 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 Intercom US, EU, AU. Optional. Defaults to US.

{
  "expo": {
    "plugins": [
      [
        "@intercom/intercom-react-native",
        {
          "appId": "abc123",
          "androidApiKey": "android_sdk-abc123",
          "iosApiKey": "ios_sdk-abc123",
          "intercomRegion": "EU" // Europe
        }
      ]
    ]
  }
}

Add the following configurations into your app.json or app.config.js:

Place your google-services.json inside the project's root and link it

{
  "expo": {
    ...
    "android": {
      "googleServicesFile": "./google-services.json",
      ...
    }
  }

Add the necessary permission descriptions to infoPlist key.

{
  "expo": {
    ...
    "ios": {
      ...
      "infoPlist": {
        "NSCameraUsageDescription": "This is just a sample text to access the Camera",
      }
      ...
    }
  }
}

Note: You should request user permission to display push notifications. e.g. react-native-permissions

Next, rebuild your app as described in the "Adding custom native code" guide.

Note: You can read more on Expo documentation

{
  "expo": {
    "android": {
       "intentFilters": [
        {
          "action": "VIEW",
          "data": [
            {
              "host": "Your app scheme(app)"
            }
          ],
          "category": ["BROWSABLE", "DEFAULT"]
        }
      ]
    }
  }
}

{
  "expo": {
    "android": {
      "intentFilters": [
        {
          "action": "VIEW",
          "autoVerify": true,
          "data": [
            {
              "scheme": "https",
              "host": "Your app url(www.app.com)",
              "pathPrefix": "Your url prefix e.g. /settings)"
            }
          ],
          "category": ["BROWSABLE", "DEFAULT"]
        }
      ]
    }
  }
}

{
  "expo": {
    "ios": {
      "infoPlist": {
        "LSApplicationQueriesSchemes": ["Your app scheme(app)"]
      }
    }
  }
}

{
  "expo": {
    "ios": {
      "infoPlist": {
        "IntercomUniversalLinkDomains": ["Your app url(www.app.com)"]
      }
    }
  }
}

Sets the user hash necessary for validation when Identity Verification is enabled. This should be called before any registration calls.

Promise<boolean>

Login a unidentified user. This is a user that doesn't have any identifiable information such as a userId or email.

Promise<boolean>

Login a user with identifiable information.

One of below fields is required.

Promise<boolean>

Updates a user in Intercom.

• relates to customer development, such as price plan, value of purchases, etc. Once these have been sent to

• Intercom you can then apply filters based on these attributes.

Intercom.updateUser({
  email: 'name@intercom.com',
  userId: 'userId',
  name: 'Name',
  phone: '010-1234-5678',
  languageOverride: 'languageOverride',
  signedUpAt: 1621844451,
  unsubscribedFromEmails: true,
  companies: [{
    createdAt: 1621844451,
    id: 'companyId',
    monthlySpend: 100,
    name: 'CompanyName',
    plan: "plan",
    customAttributes: {
      city: "New York"
    },
  }],
  customAttributes: {
    userCustomAttribute: 123,
    hasUserCustomAttribute: true
  }
});

Promise<boolean>

Logout is used to clear all local caches and user data the Intercom SDK has created. Use this at a time when you wish to log a user out of your app or change a user. Once called, the SDK will no longer communicate with Intercom until a further registration is made.

Promise<boolean>

Logs an event with a given name and some metadata.

Promise<boolean>

This takes a push registration token to send to Intercom to enable this device to receive push.

Promise<boolean>

Gets the number of unread conversations for a user.

Promise<number>

Handles the opening of an Intercom push message. This will retrieve the URI from the last Intercom push message.

  useEffect(() => {
  /**
   * Handle PushNotification Open
   */
  const appStateListener = AppState.addEventListener(
    'change',
    (nextAppState) =>
      nextAppState === 'active' && Intercom.handlePushMessage()
  );

  return () => AppState.removeEventListener('change', () => {}); // <- for RN < 0.65
  return () => appStateListener.remove(); // <- for RN >= 0.65
}, []);

Promise<boolean>

Opens the Intercom Messenger automatically to the best place for your users.

Promise<boolean>

Open the conversation screen with the composer pre-populated text.

Promise<boolean>

Open up your apps help center

Promise<boolean>

Present the help center with specific collections only .

Promise<boolean>

Fetch a list of all Collections.

Promise<HelpCenterCollectionItem[]>

Get a list of subcollections/articles for a collection.

Promise<HelpCenterCollectionContent>

Get a list of articles in the Help Center, filtered by a search term

Promise<HelpCenterArticleSearchResult[]>

Displays article with given id.

Promise<boolean>

Displays carousel

Promise<boolean>

Promise<boolean>

Toggles visibility of in-app messages.

Promise<boolean>

Toggles visibility of the launcher view. Set as Intercom.Visibility.GONE to hide the launcher when you don't want it to be visible.

Promise<boolean>

Set the bottom padding of in app messages and the launcher.

Setting the bottom padding will increase how far from the bottom of the screen the default launcher and in app messages will appear

Promise<boolean>

Set the level of the native logger

Promise<boolean>

Sets a listener for listed events:

useEffect(() => {
  const listener = Intercom.addEventListener('IntercomUnreadConversationCountDidChangeNotification', ({count}) => alert(count));
  return () => {
    listener.remove();
  }
}, [])

EmitterSubscription

type HelpCenterArticle = {
  it: string;
  title: string;
};

type HelpCenterCollectionItem = {
  id: string;
  title: string;
  summary: string;
};

type HelpCenterCollectionContent = {
  id: string;
  name: string;
  summary: string;
  articles: HelpCenterArticle[];
  collections: HelpCenterCollectionItem[];
};

type HelpCenterArticleSearchResult = {
  id: string;
  title: string;
  matchingSnippet: string;
  summary: string;
};

Check example app

• This project uses AndroidX dependencies, but the 'android.useAndroidX' property is not enabled.

  • To enable jetifier, add those two lines to your gradle.properties file:

    android.useAndroidX=true
    android.enableJetifier=true
    

• When Android app keeps stopping (E/AndroidRuntime: FATAL EXCEPTION: mqt_native_modules)

  • Add those lines to dependencies in ./android/app/build.gradle:

    implementation 'androidx.appcompat:appcompat:1.1.0'
    implementation 'androidx.swiperefreshlayout:swiperefreshlayout:1.1.0-alpha03'
    

• When tests with Jest fail mentioning "Cannot read property 'UNREAD_CHANGE_NOTIFICATION' of undefined"

  • Make a jest.mock function with the library:

    // jest/setup.ts
    jest.mock('@intercom/intercom-react-native', () => jest.fn());
    

👤 Intercom (https://www.intercom.com/)

Give a ⭐️ if this project helped you!

This project is MIT licensed.

Created with ❤️ by Intercom