Installation

This is a plugin that allows your Cordova or PhoneGap app to use Intercom for iOS and/or Intercom for Android.
If you’re new to Intercom, you’ll need to create an account and start your free trial.

OS Requirements

Intercom for iOS supports iOS 8, 9, 10 & 11.
Intercom for Android supports API 15 and above.

Step 1 - Install Intercom

Cordova

To install the plugin in your Cordova app, run the following:

cordova plugin add cordova-plugin-intercom

Phonegap

To add the plugin to your PhoneGap app, add the following to your config.xml:

<plugin name="cordova-plugin-intercom" version="~6.2.0" />

Android Support Repository

You need to make sure that you have either the Android Support Repository or Google Repository installed. Follow these instructions on how to do that.

Step 2 - Initialize Intercom

First, you'll need to get your Intercom app ID and iOS/Android API key. To find these, just select the 'Intercom for iOS' or 'Intercom for Android' option in your app settings.

Then initialize Intercom by importing Intercom and adding the following to your config.xml:

<preference name="intercom-app-id" value="your_app_id"/>
<preference name="intercom-ios-api-key" value="ios_sdk-..."/>
<preference name="intercom-android-api-key" value="android_sdk-..."/>

Step 3 - Registering Users

You’ll need to register your users with Intercom before you can talk to them or see what they do in your app. Depending on the type of app you have, you can register logged in users of your app, website visitors of your website or both. Here’s tailored instructions for each option:

Register your logged in users

If you have an app with logged in (identified) users only (like Facebook, Instagram or Slack) follow these instructions:

  1. First, you’ll need to register your user when your app launches, like this:
onDeviceReady: function() {
    if(loggedIn){
        // We're logged in, we can register the user with Intercom
        intercom.registerIdentifiedUser({userId: "123456"});
    }
}
  1. You’ll also need to register your user anywhere they log in:
function successfulLogin() {
    //For best results, use a unique user_id if you have one.
    intercom.registerIdentifiedUser({userId: "123456"});
}

Tip

If you don't have a unique userId to use here, or if you have a userId and an email you can register with those too, by calling intercom.registerIdentifiedUser({email: "alice@example.com"}) or intercom.registerIdentifiedUser({email:"alice@example.com", userId: "123456"})

Register your website visitors

If you have an app with website visitors (unidentified) only (like Angry Birds or a flashlight app), follow these instructions:

Just register an unidentified user when your app launches:

onDeviceReady: function() {
    // This registers an unidentifed user with Intercom.
    intercom.registerUnidentifiedUser();
}

Register your logged in and website visitors

If you have an app with both logged in and website visitors (like Google Maps or YouTube), follow these instructions:

  1. First, you’ll need to register your user when your app launches, like this:
onDeviceReady: function() {
    if(loggedIn){
        // We're logged in, we can register the user with Intercom
        intercom.registerIdentifiedUser({userId: "123456"});
    } else {
        intercom.registerUnidentifiedUser();
    }
}

Tip

If you don't have a unique userId to use here, or if you have a userId and an email you can register with those too, by calling intercom.registerIdentifiedUser({email: "alice@example.com"}) or intercom.registerIdentifiedUser({email:"alice@example.com", userId: "123456"})

  1. You’ll also need to register your user anywhere they log in:
function successfulLogin() {
    //For best results, use a unique user_id if you have one.
    intercom.registerIdentifiedUser({userId: "123456"});
}

How to unregister a user

When users want to log out of your app, simply call:

function logout() {
    // This resets the Intercom integration's cache of your user's identity and wipes the slate clean.
    intercom.logout();
}

Best practices for registering users

  1. Don’t use an email address as a userId as this field is unique and cannot be changed or updated later. If you only have an email address, you can just register a user with that.
  2. If you register users with an email address, the email must be a unique field in your app. Otherwise we won't know which user to update and the mobile integration won't work.

Intercom knows when your app is backgrounded and comes alive again, so you won’t need to re-register your users.

What next?