Intercom on Android supports 4.0.3 (API 15) and above.

Option 1 - If you're using Gradle + Maven

In your app's build.gradle file add the following block to your repositories block:

repositories { 
    maven {
        url 'https://dl.bintray.com/intercom/intercom-maven'
    } 
}

Then add the following to your app's build.gradle file dependencies block:

dependencies {
    compile ('io.intercom.android:intercom-sdk:1.+@aar') { 
        transitive = true
    }
}

Option 2 - Manual Install

Android Studio

  1. Download Intercom from Github and unzip it.
  2. In Android Studio go to File -> New Module and select 'Import .JAR or .AAR Package' from the 'More Modules' list and click Next.
  3. In the 'File Name' box enter the path to the 'intercom-sdk-base-1.x.x.aar' which is inside the 'aar' folder. Remove the version number from the subproject name and click Finish. Android Studio will add the module and automatically update your settings.gradle file to include this new module.
  4. Repeat 3 for the 'intercom-sdk-gcm-1.x.x.aar' file.
  5. In your apps build.gradle file add the following dependencies block:
dependencies { 
    compile project(':intercom-sdk-base') 
    compile project(':intercom-sdk-gcm') 
    compile 'com.google.android.gms:play-services-gcm:7.5.0'
}

Eclipse

  1. Download Intercom from Github and unzip it.
  2. Add the jar/intercom-sdk-base folder as a library in your workspace by going to File -> Import -> Existing Android Code -> Next and selecting the folder in the file chooser.
  3. Repeat 2 for the jar/intercom-sdk-gcm folder
  4. Make sure Intercom is marked as a library by right clicking on the projects and going to Properties -> Android.
  5. Add the Google Play Services project as a dependent library for the intercom-sdk-gcm project by right clicking the Play Services project and going to Properties -> Android -> Add
  6. Add the intercom-sdk-gcm project as a dependent library for the intercom-sdk-base project by right clicking the gcm project and going to Properties -> Android -> Add
  7. Add the intercom-sdk-base project as a dependent library for your app by right clicking your app's project and going to Properties -> Android -> Add
  8. Add the line
    manifestmerger.enabled=true
    to your app's project.properties file and make sure the android:minSdkVersion in your app's AndroidManifest.xml file matches that in the IntercomSDK's AndroidManifest.xml file.
  9. Transfer the assets/fonts folder from the Intercom SDK to your app's assets folder.

Option 3 - without GCM

By default options 1 and 2 include GCM notifications. If you'd rather not have GCM notifications in your app then you can simply exclude the 'intercom-sdk-gcm' aar/folder from your project for a manual install and for a gradle install instead use this dependency:

dependencies { 
    compile ('io.intercom.android:intercom-sdk-base:1.+@aar') { 
        transitive = true 
    } 
}

How should I use Intercom in my app?

Broadly speaking, there are three types of apps that the Intercom SDK will work in.

  1. Apps that only have registered users, like Facebook, Instagram or Slack. Your users have to log in straight away in order to use your app.
  2. Apps that never log users in, like Angry Birds or a flashlight app. Your users never have to log in to use your app.
  3. Apps that support both logged in and logged out users, like Google Maps or Youtube.

Initialize Intercom

No matter what category of app you have, you'll need your Intercom app id along with the Android API key which can be found in Settings: Integrations: Intercom for Android

Once you've found those keys, initialize Intercom by calling the following in the oncreate() method of your application class:

Intercom.initialize(this, "your api key", "your app id");

My app only has logged in users

1. Firstly, on successful completion of your authentication method in your login activity you will need to register your user.

private void successfulLogin(){
    ...
    // Registering with Intercom is easy. For best results, use a unique user_id if you have one.
    Intercom.client().registerIdentifiedUser(new Registration().withUserId("123456"));
}

Note: If you don't have a unique userId to use here, or if you have a userId and an email you can use withEmail(String email) on the Registration object.

2. Also, in your launch activity (or wherever you check your user's authenticated state when your app starts up)

if(loggedIn){
    ...
    // We're logged in, we can register the user with Intercom
    Intercom.client().registerIdentifiedUser(new Registration().withUserId("123456"));
    // Carry on as normal
    ...
}

3. Finally, when users eventually want to log out of your app, we should clear Intercom's caches so that when they log back in again, everything works perfectly. In your logout code, simply call Intercom.client().reset(); like so:

private void logout(){
    ...
    // This reset's the Intercom SDK's cache of your user's identity and wipes the slate clean.
    Intercom.client().reset();
}

My apps users never log in

1. If you only have unidentified users in your app then your integration is only one line. Just register an unidentified user in the onCreate() method of your application class like so:

@Override public void onCreate(){
    super.onCreate();
    Intercom.initialize(this, APP.getApiKey(), APP.getAppId());
    Intercom.client().registerUnidentifiedUser();
}

My app has logged in and logged out users

1. Firstly, on successful completion of your authentication method in your login activity you will need to register your user.

private void successfulLogin(){
    ...
    // Registering with Intercom is easy. For best results, use a unique user_id if you have one.
    Intercom.client().registerIdentifiedUser(new Registration().withUserId("123456"));
}

Note: If you don't have a unique userId to use here, or if you have a userId and an email you can use withEmail(String email) on the Registration object.

2. Also, in your launch activity (or wherever you check your user's authenticated state when your app starts up)

if(loggedIn){
    ...
    // We're logged in, we can register the user with Intercom
    Intercom.client().registerIdentifiedUser(new Registration().withUserId("123456"));
} else {
    // Since we aren't logged in, we are an unidentified user. Lets register.
    Intercom.client().registerUnidentifiedUser();        
}

3. Finally, when users eventually want to log out of your app, we should clear Intercom's caches so that when they log back in again, everything works perfectly. In your logout code, simply call Intercom.client().reset(); like so:

private void logout(){
    ...
    // This reset's the Intercom SDK's cache of your user's identity and wipes the slate clean.
    Intercom.client().reset();
    // Now that you have logged your user out and reset, you can register a new
    // unidentified user in their place.
    Intercom.client().registerUnidentifiedUser();
}

Tips on getting the best out of your installation

  1. Do not 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 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.
  3. Intercom knows when your app is backgrounded and comes alive again, so all you need to do is register a type of user like the examples above and we'll do the rest.

How does the Intercom Messenger work?

Intercom allows you to send messages to your users while also enabling your users send messages to you. If you have a dedicated button in your app that you wish to hook the new message composer up to, you can control Intercom's messaging UI via the Intercom.client().displayMessageComposer(); and Intercom.client().displayConversationsList(); methods. More information on messaging can be found here.

What about events, push notifications, company and user data?

Intercom for Android supports all these things. For full details please read this documentation.

What next?

Once you've got Intercom installed it's time to configure it for your product.

Did this answer your question?