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.

Blueshift's Android SDK is published to the Maven Central repository. So, please add mavenCentral() inside the repositories section of your project level build.gradle file.

repositories {
  mavenCentral()
  google()
}

Now, add the SDK dependency inside your app-level build.gradle.

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

To know the latest version, please check here.

3. Update AndroidManifest.xml

Permissions

<!-- 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" />

<!-- Starting Android 13 (API 33), you need this permission to show push notifications-->
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

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 to 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"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

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.

class MyMessagingService : BlueshiftMessagingService() {
    override fun onMessageReceived(remoteMessage: RemoteMessage) {
        if (BlueshiftUtils.isBlueshiftPushMessage(remoteMessage)) {
            super.onMessageReceived(remoteMessage)
        } else {
            // The push message does not belong to Blueshift. Please handle it here
        }
    }

    override fun onNewToken(newToken: String) {
        super.onNewToken(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.
    }
}
public class MyMessagingService extends BlueshiftMessagingService {

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

    @Override
    public void onNewToken(String newToken) {
        super.onNewToken(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 (Deprecated in v3.4.6)

❗️

Warning

If you are using Blueshift Android SDK version 3.4.6 or higher, DO NOT follow this step.

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.

<receiver
    android:name="com.blueshift.receiver.AppInstallReceiver"
    android:exported="true">
    <intent-filter>
        <action android:name="com.android.vending.INSTALL_REFERRER" />

        <data android:scheme="package" />
    </intent-filter>
</receiver>

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: