Install Intercom to see and talk to users of your Android app. Intercom for Android supports API 21 and above.
Note: We recommend using the latest available compileSdkVersion.

Step 1 - Install Intercom

If you’re new to Intercom, you’ll need to create an account and start your free trial. Then you have three options:

Option 1: Install Intercom with Firebase Cloud Messaging (FCM)

Add the following dependency to your app's build.gradle file:

dependencies {
    implementation 'io.intercom.android:intercom-sdk:12.3.0'
    implementation 'com.google.firebase:firebase-messaging:20.2.+'
}

dependencies {
    implementation("io.intercom.android:intercom-sdk:10.+")
    implementation("com.google.firebase:firebase-messaging:20.2.+")
}

Option 2: Install Intercom without Push Messaging

If you'd rather not have push notifications in your app, you can use this dependency:

dependencies {
    implementation 'io.intercom.android:intercom-sdk-base:12.3.0'
}

dependencies {
    implementation("io.intercom.android:intercom-sdk-base:10.+")
}

🚧
Important
If you choose this method you won’t be able to send push messages.

Maven central

Intercom is hosted on maven central. You will need to add maven central to your root build.gradle file.

allprojects {
    repositories {
      mavenCentral()
    }
}

Permissions

We include the INTERNET permission by default as we need it to make network requests:

<uses-permission android:name="android.permission.INTERNET"/>

You will need to include the READ_EXTERNAL_STORAGE permission if you have enabled image 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"/>

🚧
Transitive Dependencies
As of version 9.0.0, Intercom Android SDK transitively depends on the latest versions of Gson, Otto, Okio, Okhttp and Retrofit. If your app is using any one of these libraries, they should at least be on the same major version that the Intercom SDK is using. When there are two versions of a library at build time, Gradle automatically picks the newer version. This means if you are currently using Retrofit 2.4.0, you would automatically get Retrofit 2.9.0 after including Intercom.
For the exact version numbers we are using, please check the dependency graph on Github.

Step 2 - Initialize Intercom

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

Then, initialize Intercom by calling the following in the onCreate() method of your application class:

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

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

Note: If you don't currently implement a custom application, you’ll need to create one. A custom application looks like this:

class CustomApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Intercom.initialize(this, "your api key", "your app id")
    }
}

public class CustomApplication extends Application {
    @Override public void onCreate() {
        super.onCreate();
        Intercom.initialize(this, "your api key", "your app id");
   }
}

You’ll need to update your manifest to use your application:

<application
    android:name=".CustomApplication">
</application>

📘
Important
Intercom must be initialized inside the application onCreate() method. Initializing anywhere else will result in Intercom not behaving as expected and could even result in the host app crashing.

Step 3 - Create a user

Finally, you’ll need to create a user, like this:

val registration = Registration.create().withUserId("123456")

Registration registration = Registration.create().withUserId("123456");

You’ll now need to login your users before you can talk to them and track their activity in your app.

Login your users (to talk to them and see their activity)

Depending on the type of app you have, you can log in users, visitors or both. Here’s tailored instructions for each option:

Login your logged in users into Intercom

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

First, you’ll need to login your user, like this:

private fun successfulLogin() {
        /* For best results, use a unique user_id if you have one. */
        val registration = Registration.create().withUserId("123456")
        Intercom.client().loginIdentifiedUser(
            userRegistration = registration,
            intercomStatusCallback = object : IntercomStatusCallback{
                override fun onSuccess() {
                    // Handle success
                }

                override fun onFailure(intercomError: IntercomError) {
                    // Handle failure
                }

            }
        )
}

private void successfulLogin() {
    /* For best results, use a unique user_id if you have one. */
    Registration registration = Registration.create().withUserId("123456");
    Intercom.client().loginIdentifiedUser(registration, new IntercomStatusCallback() {
                @Override
                public void onSuccess() {
                    // Handle success
                }

                @Override
                public void onFailure(@NonNull IntercomError intercomError) {
                    // Handle failure
                }
            });
}

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

You’ll also need to register your user anywhere they sign in. Just call:

if (loggedIn) {
/* We're logged in, we can register the user with Intercom */
    val registration = Registration.create().withUserId("123456")
    Intercom.client().loginIdentifiedUser(
            userRegistration = registration,
            intercomStatusCallback = object : IntercomStatusCallback{
                override fun onSuccess() {
                    // Handle success
                }

                override fun onFailure(intercomError: IntercomError) {
                    // Handle failure
                }

            }
        )
}

if (loggedIn) {
    /* We're logged in, we can register the user with Intercom */
    Registration registration = Registration.create().withUserId("123456");
    Intercom.client().loginIdentifiedUser(registration, new IntercomStatusCallback() {
                @Override
                public void onSuccess() {
                    // Handle success
                }

                @Override
                public void onFailure(@NonNull IntercomError intercomError) {
                    // Handle failure
                }
            });
}

Login your visitors

If you have an app with visitors (unidentified) only (like Angry Birds or a flashlight app), you can do the following:

override fun onCreate() {
    super.onCreate()
    Intercom.initialize(this, "your api key", "your app id")
    Intercom.client().loginUnidentifiedUser(
            intercomStatusCallback = object : IntercomStatusCallback{
                override fun onSuccess() {
                    // Handle success
                }

                override fun onFailure(intercomError: IntercomError) {
                    // Handle failure
                }

            }
        )
}

@Override public void onCreate() {
    super.onCreate();
    Intercom.initialize(this, "your api key", "your app id");
    Intercom.client().loginUnidentifiedUser(new IntercomStatusCallback() {
            @Override
            public void onSuccess() {
                // Handle success
            }

            @Override
            public void onFailure(@NonNull IntercomError intercomError) {
                // Handle failure
            }
        });
}

Login your users and visitors

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

First, you’ll need to login your user, like this:

private fun successfulLogin() {
    /* For best results, use a unique user_id if you have one. */
    val registration = Registration.create().withUserId("123456")
    Intercom.client().loginIdentifiedUser(registration, new IntercomStatusCallback() {
                @Override
                public void onSuccess() {
                    // Handle success
                }

                @Override
                public void onFailure(@NonNull IntercomError intercomError) {
                    // Handle failure
                }
            });
}

private void successfulLogin() {
    /* For best results, use a unique user_id if you have one. */
    Registration registration = Registration.create().withUserId("123456");
    Intercom.client().loginIdentifiedUser(registration, new IntercomStatusCallback() {
                @Override
                public void onSuccess() {
                    // Handle success
                }

                @Override
                public void onFailure(@NonNull IntercomError intercomError) {
                    // Handle failure
                }
            });
}

📘
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.

You’ll also need to login your user anywhere they sign in. Just call:

if (loggedIn) {
    /* We're logged in, we can login the user with Intercom */
    val registration = Registration.create().withUserId("123456")
    Intercom.client().loginIdentifiedUser(registration, new IntercomStatusCallback() {
                @Override
                public void onSuccess() {
                    // Handle success
                }

                @Override
                public void onFailure(@NonNull IntercomError intercomError) {
                    // Handle failure
                }
            });
} else {
    /* Since we aren't logged in, we are an unidentified user. 
     * Let's tell Intercom. */
    Intercom.client().loginUnidentifiedUser(new IntercomStatusCallback() {
            @Override
            public void onSuccess() {
                // Handle success
            }

            @Override
            public void onFailure(@NonNull IntercomError intercomError) {
                // Handle failure
            }
        });
}

if (loggedIn) {
    /* We're logged in, we can register the user with Intercom */
    Registration registration = Registration.create().withUserId("123456");
    Intercom.client().loginIdentifiedUser(registration, new IntercomStatusCallback() {
                @Override
                public void onSuccess() {
                    // Handle success
                }

                @Override
                public void onFailure(@NonNull IntercomError intercomError) {
                    // Handle failure
                }
            });
} else {
    /* Since we aren't logged in, we are an unidentified user. 
     * Let's register. */
    Intercom.client().loginUnidentifiedUser(new IntercomStatusCallback() {
            @Override
            public void onSuccess() {
                // Handle success
            }

            @Override
            public void onFailure(@NonNull IntercomError intercomError) {
                // Handle failure
            }
        });
}

How to unregister a user

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

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

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

Best practices for registering users

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.
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.

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

What next?

Once you've installed Intercom it's time to configure it for your Android app.

Once you've got Intercom installed it's time to configure it for your Android app.
Enable push notifications so you can send push messages.
Enable Identity Verification for your Android app.

Installation

Step 1 - Install Intercom

Option 1: Install Intercom with Firebase Cloud Messaging (FCM)

Option 2: Install Intercom without Push Messaging

🚧
Important

Maven central

Permissions

🚧
Transitive Dependencies

Step 2 - Initialize Intercom

📘
Important

Step 3 - Create a user

Login your users (to talk to them and see their activity)

Login your logged in users into Intercom

📘
Note

Login your visitors

Login your users and visitors

📘
Note

How to unregister a user

Best practices for registering users

👍
Note

What next?

Step 1 - Install Intercom

Option 1: Install Intercom with Firebase Cloud Messaging (FCM)

Option 2: Install Intercom without Push Messaging

🚧Important

Maven central

Permissions

🚧Transitive Dependencies

Step 2 - Initialize Intercom

📘Important

Step 3 - Create a user

Login your users (to talk to them and see their activity)

Login your logged in users into Intercom

📘Note

Login your visitors

Login your users and visitors

📘Note

How to unregister a user

Best practices for registering users

👍Note

What next?

🚧
Important

🚧
Transitive Dependencies

📘
Important

📘
Note

📘
Note

👍
Note