Set up Blueshift Android SDK

Step-by-step instructions to install the SDK and configure it for your app.

Follow these steps to install the Blueshift Android SDK and get it ready for use in your app.

1. Prerequisites

Before adding the SDK, make sure your project meets the following requirements:

  • Android Studio is installed.
  • Your project uses a minimum SDK version of 21 (Android 5.0).
  • Firebase Cloud Messaging (FCM) is integrated. For details, see the Firebase Cloud Messaging setup guide.
Blueshift SDK versionMinimum Firebase CoreMinimum Firebase Messaging
android-sdk-x v3.2.5+17.4.420.3.0

Note: Firebase libraries released after June 17, 2019, require Jetpack (AndroidX).


2. Add the SDK

First, make sure mavenCentral() is included in your project repositories:

  • New projects (Kotlin DSL / Android Studio Arctic Fox and later): Check that it is present in settings.gradle.kts under dependencyResolutionManagement.repositories.

  • Older projects (Groovy / project-levelbuild.gradle): Add it to the repositories section of your build.gradle file.

// Applies for Groovy (build.gradle) and Kotlin DSL (build.gradle.kts)

repositories {
    mavenCentral()
    google()
}
 

Next, add the SDK dependency to your app-level build file (app/build.gradle for Groovy or app/build.gradle.kts for Kotlin DSL):

// Groovy (build.gradle)

dependencies {
    // Blueshift Android SDK (AndroidX compatible)
    implementation "com.blueshift:android-sdk-x:4.0.2"
}
// Kotlin DSL (build.gradle.kts)

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

Note: Version 4.0.2 is used in the above snippets as an example. Always check the GitHub releases page for the latest SDK version.


3. Update AndroidManifest.xml

Add permissions

Add the following permissions inside your app/src/main/AndroidManifest.xml file, just below the <manifest> tag and outside the <application> tag:

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

<!-- Required for checking network connectivity before sending events or fetching live content -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!-- For Android 13+ push notifications -->
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

<!-- Optional: Used for location-based personalization and segmentation.
     Important: You must disclose location data usage in your Play Store privacy policy. -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Add Firebase messaging service

If this is your first time integrating FCM, add this service:

<service
    android:name="com.blueshift.fcm.BlueshiftMessagingService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

If your app already has a custom FirebaseMessagingService, make it extend BlueshiftMessagingService instead of FirebaseMessagingService.

class MyMessagingService : BlueshiftMessagingService() {
    override fun onMessageReceived(remoteMessage: RemoteMessage) {
        if (BlueshiftUtils.isBlueshiftPushMessage(remoteMessage)) {
            super.onMessageReceived(remoteMessage)
        } else {
            // The push message is not from Blueshift. Handle it here.
        }
    }

    override fun onNewToken(newToken: String) {
        super.onNewToken(newToken)
        // Use the new token if needed.
    }
}
public class MyMessagingService extends BlueshiftMessagingService {
    @Override
    public void onMessageReceived(RemoteMessage remoteMessage) {
        if (BlueshiftUtils.isBlueshiftPushMessage(remoteMessage)) {
            super.onMessageReceived(remoteMessage);
        } else {
            // The push message is not from Blueshift. Handle it here.
        }
    }

    @Override
    public void onNewToken(String newToken) {
        super.onNewToken(newToken);
        // Use the new token if needed.
    }
}

4. ProGuard rules (optional)

If your app uses ProGuard or R8 (tools for shrinking unused code and obfuscating class names to protect your APK), add the following rules to the app/proguard-rules.pro file to avoid runtime issues:

-keep class com.blueshift.** { *; }
-dontwarn com.blueshift.**

For more details, see the Android Developer Guide on Code Shrinkage.