• Dashboard
  • API
  • Guides
  • FAQ
  • Documentation > Android

    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 'com.batch.android:batch-sdk:1.13+'

    Exact version numbers can be found in the changelog.

    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 "com.google.firebase:firebase-core:12.0.1"
    implementation "com.google.firebase:firebase-messaging:12.0.1"

    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 "com.google.firebase:firebase-analytics:12.0.1"
    
    // Or, if you want an even lighter dependency:
    
    implementation "com.google.android.gms:play-services-ads-identifier:15.0.1"

    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.

    React Native users

    While we don't have an official SDK for React Native, Batch works well in Native Android modules!

    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:

    public class YourApp extends Application
    {
        @Override
        public void onCreate() 
        {
            super.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);
        }
    }
    class YourApp: Application() {
        override fun onCreate() {
            super.onCreate()
    
            Batch.setConfig(Config(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.

    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):

    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

    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.
    • Token import: Import your existing tokens if you're coming from another push provider.