Android

Setup Identity Verification with Intercom for Mobile on Android

Identity verification helps to make sure that conversations between you and your users are kept private and that one user can't impersonate another. We strongly encourage all Intercom customers to set up and enable identity verification.

Enable Identity Verification

Get the Android identity verification secret from your app settings and store it in a secure place on your app server.

Next toggle enforce identity verification to on.

❗️

Have you already released your app with the Intercom messenger in it?

If you have then enabling identity verification will stop old versions of your app communicating with Intercom. We recommend that you complete setting up identity verification and test that everything is working. Then turn off identity verification and release an update to your app. This update will be sending user hashes to Intercom but not enforcing it. Once you are happy with the number of users on versions of your app sending the user hash you can come back and toggle identity verification on which will then start enforcing it for all versions of your app.

Returning the HMAC Digest from your App Server's Authentication Call

Your app server authentication code needs to be modified so that is uses the Intercom Android API Secret to create a HMAC digest (hash based message authentication code) from the user id or email address for that user. Then it returns the HMAC digest to your Android app. Note that identity verification does not apply to unidentified users, for whom you do not have a user id or email address.

The HMAC is computed as a SHA-256 digest as follows:

OpenSSL::HMAC.hexdigest('sha256', api_key.secret, user_id_or_email)

If you wish to generate a HMAC in a different programming language we have a comprehensive list here.

Set the User Hash in your Android App

When your Android app initializes Intercom if the user is identified (i.e., you have a user id or email address), pass in a String of the HMAC returned from your server's authentication call:

Intercom.client().setUserHash("your_hmac_of_user_id_or_email");

The Intercom API Auth Server uses its copy of the Android API Secret to recreate the HMAC digest from the user_id or email. If it matches with the supplied HMAC digest, we can be sure that this request is coming from your app server and the API Auth Server issues an access token to the Android messenger.

If the HMAC fails to verify, the API Auth Server responds with a 401.

Troubleshooting

  • You must use the exact Android Secret Key that we provide you within the code. Making up your own won't work. Note: Don't confuse this with your app_id.
  • Make sure you are using the Android Secret Key, not the iOS or web one they are not the same.
  • The user data passed to your server must be either the user_id or email for that Intercom user.
  • Do not forget that identity verification needs to be activated (and configured) separately in your development/test and production apps.