SDK integration

This guide assumes that you've already followed the prerequisites.

Integrating the SDK

Batch is compatible with Android 4.0.3 (API Level 15) and higher.

Simply add in your app's build.gradle:

implementation ''

Exact version numbers can be found in the changelog.

Using Batch might require you to enable Java 8 support through desugaring in your project.
You might need to add the following in your build.gradle:

android {
  // ...
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8


As of 1.15.0, Batch requires AndroidX. If you see one of the following errors:

This project uses AndroidX dependencies, but the 'android.useAndroidX' property is not enabled. Set this property to true in the file and retry.
Manifest merger failed : Attribute application@appComponentFactory value=( from [androidx.core:core:1.0.0] AndroidManifest.xml:22:18-86
	is also present at []
error: package does not exist

Please migrate your project to androidx.

If you cannot migrate to AndroidX just yet, please use Batch 1.14.4 and consider migrating to AndroidX in the near future, as the legacy support libraries are not updated anymore.

implementation ''

Adding push notifications support

This guide assumes that you've already setup your Firebase project in your Android application.
If you didn't, please follow Firebase's Get Started tutorial or use the Firebase Cloud Messaging wizard in Android studio.

In order to enable push notifications support, Batch requires firebase-core and firebase-messaging 11.0.0 or higher. We highly recommend to use the latest version when possible. Add the following to your build.gradle, if not already present:

implementation ""
implementation ""

If you want to allow Batch to fetch your Advertising ID and facilitate debugging your integration, you can also include firebase-analytics. Don't worry, it is entirely optional.

implementation ""

// Or, if you want an even lighter dependency:

implementation ""

Note that adding this in your apps will enable Advertising ID collection in both Firebase and Batch. Your app must provide a privacy policy to comply with Play Store rules. You can always disable Advertising ID collection in Batch by calling setCanUseAdvertisingID(false) on Batch's Config object. Please see Firebase's documentation regarding how to disable it.

Your first start

You are now ready to setup Batch.

The setConfig function should be called only once during your application lifetime to set up the SDK. As an application can be started without entenring an activity, it is very important that you call any of Batch's global setup methods in an Application subclass.

In your Application subclass:

  • Java
  • Kotlin
public class YourApp extends Application
  public void onCreate() 

    Batch.setConfig(new Config(YOUR_API_KEY));
    registerActivityLifecycleCallbacks(new BatchActivityLifecycleHelper());
    // You should configure your notification's customization options here.
    // Not setting up a small icon could cause a crash in applications created with Android Studio 3.0 or higher.
    // More info in our "Customizing Notifications" documentation
    // Batch.Push.setSmallIconResourceId(R.drawable.ic_notification_icon);

YOUR_API_KEY is your Batch Dev or Live API key. You'll find the API keys needed to set up the SDK in ⚙ Settings → General:

  • Dev API key: Use it for development or testing purposes. This API key won't trigger stats computation. Please take care not to ship an app on a Store with this API key.
  • Live API key: Should be used in a production environment only and in the final version of your app on the Store.

If you've got any Activity in singleTop mode, please call Batch.onNewIntent() in its onNewIntent() method, or simply add it in all of your activities.

You can find more information on what you can customize on your notifications and how here

Testing your integration

Congratulations on finishing the bulk of the integration!

After deploying a build to your device or an Google Play enabled simulator, open the Logcat tab of Android Studio. You should see the following logs:

Batch (<version>) is running in dev mode (your API key is a dev one)
Installation ID: <your installation ID>

Your first notification

1. Obtaining your device token

You can find your device's token using the debug tool or locating the token Batch posts to the logcat (see here to know more):

I/Batch: Push - Registration ID/Push Token (FCM): <your device token>

2. Sending a test push

Go to ⚙ Settings → Push settings, paste your device's token and click on Save.

Then, all you have to do is to click on the "Send" button. If you sucessfuly set up the SDK, you will receive a notification on your device.

Test push


If you're having trouble integrating the SDK, check our troubleshooting documentation.

What's next

Congratulations on finishing your Batch integration!

Here are a couple of extra steps you can take before releasing your app:

  • Live API key: Ensure you don't use Batch's DEV API key in the build you will upload to the Play Store.
  • Small icon / Accent color: Make sure the small icon you are using is opaque white. We also recommend you use an accent color. You will find more information here.
  • Mobile Landings: Make sure Mobile Landings are set up correctly.
  • Custom user identifier: Add support for custom user identifiers if you are planning to use the Transactional or the Custom Data APIs.
  • Token import: Import your existing tokens if you're coming from another push provider.