Set up Blueshift's Android SDK

This article provides information on how-to set up Blueshift's Android SDK to integrate your app with our platform.

Installing Blueshift's Android SDK into your Android App is pretty straightforward. Follow the step-by-step instructions provided below.

1. Firebase Cloud Messaging

Blueshift's Android SDK uses Firebase Cloud Messaging (FCM) to send push messages to your app. So you must first integrate it into your project. If you have already integrated it, skip this step.

Follow the documentation provided here to complete the FCM integration.


According to this documentation, if you are using Firebase libraries with versions released on June 17, 2019 or later, then you must use Jetpack (AndroidX) libraries in your project. Otherwise, you can continue to use the older libraries that are supported. The minimum Firebase versions that the Blueshift Android SDK (android-sdk) β€” version 2.0.2 or later β€” supports are: 16.0.6 (core) and 17.3.4 (messaging).


The minimum Firebase versions that the Blueshift Android SDK (android-sdk-x) β€” version 3.2.5 or later β€” supports are: 17.4.4 (core) and 20.3.0 (messaging).

2. Get the Blueshift Android SDK

Please add Blueshift Android SDK as a dependency in your Android app project.

Add Maven Central repository

Blueshift's Android SDK is published to Maven Central repository. Ensure that you have mavenCentral() added inside the repositories section of your project level build.gradle file.

repositories {

Add Blueshift SDK dependency

We have two variants of the SDK to support Google's Support libraries and AndroidX libraries.

If the app is migrated to use AndroidX libraries, we highly recommend you to use the AndroidX compatible version of the Blueshift Android SDK (android-sdk-x).

Blueshift Android SDK with AndroidX Libraries

dependencies {
  // Blueshift Android SDK (AndroidX compatible)
  implementation "com.blueshift:android-sdk-x:$sdkVersion"

Blueshift Android SDK with Google Support Libraries

:warning: Use this variant ONLY IF the project is NOT migrated to use AndroidX libraries.

dependencies {
  // Blueshift Android SDK (Google Support Library compatible)
  implementation "com.blueshift:android-sdk:$sdkVersion"

3. Update AndroidManifest.xml


<!-- Internet permission is required to send events, 
get notifications and in-app messages. -->
<uses-permission android:name="android.permission.INTERNET" />

<!-- Network state access permission is required to detect changes 
in network connection to schedule sync operations. -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!-- Location access permission is required if you want to track the 
location of the user. You can skip this step if you don't want to 
track the user location. -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Firebase Cloud Messaging (FCM) Receiver

First time FCM Integration

If this is the first time that you are integrating FCM with your application, add the following lines of code into the AndroidManifest.xml file. This will enable the Blueshift Android SDK to receive the push notification sent from Blueshift servers via Firebase.

<service android:name="com.blueshift.fcm.BlueshiftMessagingService">
        <action android:name="" />

Existing FCM Integration

If you have an existing FCM integration, let your FirebaseMessagingService class to extend BlueshiftMessagingService as mentioned below. This will enable the Blueshift Android SDK to receive the push notification sent from Blueshift servers via Firebase.

public class AwesomeAppMessagingService extends BlueshiftMessagingService {

    public void onMessageReceived(RemoteMessage remoteMessage) {
        if (BlueshiftUtils.isBlueshiftPushMessage(remoteMessage)) {
        } else {
             * The push message does not belong to Blueshift. Please handle it here.

    public void onNewToken(String newToken) {

         * Use the new token in your app. the super.onNewToken() call is important
         * for the SDK to do the analytical part and notification rendering.
         * Make sure that it is present when you override onNewToken() method.

Install Referrer Tracking (Optional)

To automatically track the installation referrer, add the following lines inside the application tag


The app_install event occurs only when a user installs the app from the Play Store by clicking a referral URL. If the user navigates to the Play Store, searches for, and then installs the app, the app_install event is not triggered. As such, the number of app_installs captured by Blueshift might be lower than the actual app installs.

        <action android:name="" />

        <data android:scheme="package" />

What’s Next

Now that you're done setting up the SDK in your app, it's time to include it in your code, configure it, and initialize it to start using its features. For more information about it, see: