SDK integration

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

Integrating the SDK

Batch is compatible with Android 5.0 (Lollipop / API Level 21) and higher.

Simply add in your app's build.gradle:

implementation("com.batch.android:batch-sdk:2.0+")

Exact version numbers can be found in the changelog.

Using Batch require you to enable at least Java 8 support through desugaring in your project. Add the following to your build.gradle if not already present:

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

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-messaging 22.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 "com.google.firebase:firebase-messaging:22.0.0"

Note: If you're using Batch < 1.18 with firebase-messaging >= 22.0, please add the Firebase Installations library to your dependencies or you will not be able to receive push notifications:
implementation "com.google.firebase:firebase-iid:21.1.0".

Optional dependencies

In-App Review

The Play In-App Review library, which enables the use of the Google Play In-App Review API from In-App messages and other features:

implementation 'com.google.android.play:review:2.0.1"

Note: If you are using Batch SDK < 1.21 you should use the Play Core library instead:
implementation("com.google.android.play:core:1.9.0").

Your first start

You are now ready to setup Batch.

Starting the SDK

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

In your Application subclass:

class YourApp: Application() {
  override fun onCreate() {
    super.onCreate()
    
    Batch.start("YOUR_API_KEY")
    registerActivityLifecycleCallbacks(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.

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

Overriding OnNewIntent

As singleTop/singleTask/singleInstance activities only get their new intents in onNewIntent when brought up to the front, you will need to call Batch.onNewIntent() in them to let Batch know about it.

A common way to implement this is to make a base activity and add Batch.onNewIntent in all of them:

In your Activity subclass:

open class BaseActivity : AppCompatActivity() {
    override fun onNewIntent(intent: Intent?) {
        super.onNewIntent(intent)
        Batch.onNewIntent(this, intent)
    }
}

Requesting the notification permission

Since Android 13, your app needs to request for the permission to display notifications. This can be done as following:

// If you don't care of the permission result
Batch.Push.requestNotificationPermission(this)
// or
// If you need to handle the permission result
Batch.Push.requestNotificationPermission(this) {
  // Handle whether the permission is granted or not.
}

To know when you should request the permission to your users, we recommend you to follow the android best practices.

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-Token): <your device token>

If you don't see a push token, there might be an error in the logs describing what happened. See our troubleshooting documentation for more info.

Note: Push notifications are not supported in all emulators. Please use a physical device or a Google API/Google Play emulator to test them.

2. Obtaining your Installation ID

You can then retrieve the Installation ID, which represents an installation of your app on a device, by calling the following method:

Batch.User.getInstallationID();

While Batch prints this in the debug console on start, displaying it in a settings or about page enables users to send you this identifier. This is useful for debugging, sending test notifications, etc.

3. Sending a test push notification

Batch enables you to send a test notification to the application installation currently running on your device.

To do so, open the dashboard and go to ⚙ Settings → Debug. Enter your Installation ID, hit Debug and then click on "Send Test Push".

You should receive a notification on your device. If not, or if you can't find your Installation ID, the SDK might not be properly configured.

If you need to send push notifications to your device on a regular basis, then you should add your ID as a test device by clicking the "Save as a test device" button.

Troubleshooting

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.
• Analytics: Add an event dispatcher to automatically track your campaigns in your third-party analytics tool.
• Token import: Import your existing tokens if you're coming from another push provider.