Android > SDK integration

Push setup

Adding Google Play Services

GCM uses the Google Play Services library. If you haven't included it yet, you must integrate it to continue.

To include the library, follow Google's instructions: How to include Google Play Services library.

Batch uses GCM via Google Play Services, it's not compatible with the old C2DM API. If you app is using C2DM API, you must migrate to GCM via Google Play Services before using Batch Push.

Adding permissions and service

GCM needs 4 permissions to setup push:

  • com.google.android.c2dm.permission.RECEIVE
  • android.permission.WAKE_LOCK
  • android.permission.VIBRATE
  • [YOUR-PACKAGE-NAME].permission.C2D_MESSAGE

These 4 permissions will not show up in the PlayStore, so you don't need to worry about users asking about them.

Here's how your manifest should appear with these permissions:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

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

    <permission android:name="${applicationId}.permission.C2D_MESSAGE" android:protectionLevel="signature"/> 
    <uses-permission android:name="${applicationId}.permission.C2D_MESSAGE"/> 

    <uses-permission android:name="android.permission.WAKE_LOCK" />
    <uses-permission android:name="android.permission.VIBRATE" />  
    <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE"/>

    <service android:name="com.batch.android.BatchPushInstanceIDService" android:exported="true">
        <intent-filter>
            <action android:name="com.google.android.gms.iid.InstanceID"/>
        </intent-filter>
    </service>
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="YOUR-PACKAGE-NAME"
    android:versionCode="1"
    android:versionName="1.0" >

    <uses-sdk
        android:minSdkVersion="8"
        android:targetSdkVersion="20" />

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

    <permission android:name="YOUR-PACKAGE-NAME.permission.C2D_MESSAGE" android:protectionLevel="signature"/> 
    <uses-permission android:name="YOUR-PACKAGE-NAME.permission.C2D_MESSAGE"/> 

    <uses-permission android:name="android.permission.WAKE_LOCK" />
    <uses-permission android:name="android.permission.VIBRATE" />  
    <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE"/>

If not using gradle/Android studio, be sure to replace YOUR-PACKAGE-NAME with your actual package name, for example: com.google.android. If you're using a gradle based build, the ${applicationId} macro will automatically do that for you.

You must now declare the Batch services and receiver. They will handle notifications and display them for you, without any additional code.

Here's how to declare it in your application tag:

    <application
        android:icon="@drawable/ic_launcher"
        android:label="@string/app_name"
        android:theme="@style/AppTheme" >

        <meta-data
            android:name="com.google.android.gms.version"
            android:value="@integer/google_play_services_version" />

        <activity
            android:name=".MainActivity"
            android:label="@string/app_name" >
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>

        <service android:name="com.batch.android.BatchPushService" />
        <receiver android:name="com.batch.android.BatchPushReceiver" android:permission="com.google.android.c2dm.permission.SEND"> 
          <intent-filter> 
            <action android:name="com.google.android.c2dm.intent.RECEIVE" /> 
            <category android:name="${applicationId}" /> 
          </intent-filter>  
        </receiver>


        <service android:name="com.batch.android.BatchPushInstanceIDService" android:exported="true">
            <intent-filter>
                <action android:name="com.google.android.gms.iid.InstanceID"/>
            </intent-filter>
        </service>

    </application>
    <application
        android:icon="@drawable/ic_launcher"
        android:label="@string/app_name"
        android:theme="@style/AppTheme" >

        <meta-data
            android:name="com.google.android.gms.version"
            android:value="@integer/google_play_services_version" />

        <activity
            android:name=".MainActivity"
            android:label="@string/app_name" >
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>

        <service android:name="com.batch.android.BatchPushService" />
        <receiver android:name="com.batch.android.BatchPushReceiver" android:permission="com.google.android.c2dm.permission.SEND"> 
          <intent-filter> 
            <action android:name="com.google.android.c2dm.intent.RECEIVE" /> 
            <category android:name="YOUR-PACKAGE-NAME" /> 
          </intent-filter>  
        </receiver>

        <service android:name="com.batch.android.BatchPushInstanceIDService" android:exported="true">
            <intent-filter>
                <action android:name="com.google.android.gms.iid.InstanceID"/>
            </intent-filter>
        </service>

    </application>

If you get an error that looks like "Didn't find class com.batch.android.BatchPushInstanceIDService", please make sure that your project correctly has a dependency on the play services library, and that it is at least of version 9.2.0.

Enabling Batch push

Activate Batch Push by setting the FCM/GCM Sender ID that you obtained earlier, right before setting the Batch API Key (either DEV or LIVE, in ⚙ Settings → General):

public class YourApp extends Application
{
    @Override
    public void onCreate() 
    {
        super.onCreate();

        Batch.Push.setGCMSenderId("YOUR-GCM-SENDER-ID");

        Batch.setConfig(new Config(YOUR-BATCH-API-KEY));

    }
}

Be sure to setup Batch Config and Push related configurations in your Application onCreate, not in an Activity. This is important because when you receive a notification, your activity may not be initialized.

HIGHLY RECOMMENDED
- Please read this guide if you are working with a custom Push implementation.
- Follow the Customizing notifications guide to display your notification icon correctly and manage other aspects of your notification (accent color, etc).

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

D/Batch (20509): Batch.Push: Registration id: X

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 sending test notifications, you can check our troubleshooting documentation.

What's next

Congratulations on finishing the integration of Batch Push!

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