Setting up Android Push Notifications

This guide describes the technical setup necessary to use Iterable to send push notifications to Android devices.

# In this article

# Configuring Iterable to send Android push notifications

Follow the steps below to configure Iterable to send Android push notifications:

# Step 1: Set up Firebase for your Android app

To send Android push notifications, Iterable uses Firebase Cloud Messaging (FCM). To learn how to set up Firebase for your Android app, read Google's Add Firebase to your Android project document.

# Step 2: Create a mobile app in Iterable

In your Iterable projects, you can define mobile apps that correspond to your real-world mobile apps. Each mobile app in Iterable stores details about an app's name, identifier, platform, and store URL.

To create a mobile app in Iterable:

1. Navigate to Settings > Apps and Websites.

2. Click New app or website. This brings up the New app or website page:

   

3. For Name, enter the name of your app. For example, Example Push Test.

4. For Platform, select Android.

5. For Package name, enter your app's package name. For example, com.example.pushtest.

6. (Optional) For Store URL, enter your app's Play Store URL.

7. Click Create app. You'll be taken to the app's details page:

   

# Step 3: Add a push integration to the mobile app

A push integration stores the credentials Iterable uses to authenticate with FCM when sending push notifications. Push integrations are stored in the mobile apps you create in your Iterable project.

To create a push integration:

1. Create a service account in Firebase.
2. Create a JSON private key that Iterable can use to authenticate with Firebase.
3. Configure the push integration in Iterable.
4. Send a test push notification.

# Step 3.1: Create a service account in Firebase

First, create a service account in Firebase and give it the necessary permissions to send push notifications on your behalf.

To create and configure a service account:

1. Sign in your Firebase account. Open the Firebase project that contains the app to which you'll send push notifications.

   

2. Click the gear button (in the upper-left). From the menu, choose Project settings.

   

3. Navigate to the Service accounts tab and click Manage service account permissions.

   

4. To create a new service account, click Create Service Account.

   

5. Under Service account details, enter a name, account ID, and description. Then, click Create and Continue.

   

6. Under Grant this service account access to project, select role Firebase Cloud Messaging API Admin. Or, choose a custom role that has the cloudmessaging.messages.create permission. Then, click Continue.

   

   TIP

   To learn about creating and managing custom Identity and Access Management (IAM) roles in Google Cloud, read Google's Create and manage custom roles document.

7. Under Grant users access to this service account, leave both fields blank.

   

8. Click Done. You'll be taken back to the Service Accounts page.

# Step 3.2: Create and download an FCM private key (JSON)

Now, create and download a JSON private key that Iterable can use to authenticate with FCM when sending push notifications.

1. On the Service Accounts page, in the row for your new service account, click the three dots in the Actions column. Choose Manage keys.

   

2. Click Create new key, and then choose JSON.

   

3. Click Create. This downloads the JSON private key to your machine.

# Step 3.3: Configure the push integration in Iterable

Back in Iterable, configure your mobile app's push integration:

1. Navigate to Settings > Apps and Websites and open your app.

2. In the Push sections, under Integrations, in the Firebase row, click Configure. A Configure Firebase integration window will appear.

   

3. For Firebase Cloud Messaging (FCM) type, choose between:

   • Notification messages - The Firebase SDK handles incoming push notifications. Generally, you should only select this option if you aren't using Iterable's Android SDK.
   • Data notifications - Iterable's SDK handles incoming push notifications. If you're using Iterable's Android SDK, this is usually the right option.

   TIP

   For more information about these options, read About FCM messages, from Google.

4. Upload the JSON file you created above.

5. Click Save. As soon as you do, Iterable starts using these new credentials to send push notifications to your Android app.

# Step 3.4: Send a test push notification

Finally, a Test Firebase integration window appears. Send a test push notification to make sure that everything works as expected (assuming that you've set your app up to receive push notifications, as described further down in this document).

1. Grab a test user's device token:

   • Visit Audience > User Lookup.
   • Look up an internal user by email or userId (whatever makes sense in your project).
   • Navigate to the User fields tab.
   • Open the devices array.
   • From an Android device where appPackageName is your app's package name, and endpointEnabled is true, copy the token field.

2. In the Test Firebase integration window:

   • Enter the device token and a message.
   • Click Send test.

   The device should receive the push notification message. If not, check the configuration of the service account in Firebase, fix as necessary, and try again. If you're still having trouble, contact Iterable support.

# Step 4: Install Iterable's Android SDK in your mobile app

To learn how to install Iterable's Android SDK, read about Iterable's Android SDK.

# Step 5: Additional SDK configuration

# Handling Firebase push messages and tokens

The SDK automatically adds a FirebaseMessagingService to the app manifest, so you don't have to do any extra setup to handle incoming push messages.

If your application implements its own FirebaseMessagingService, make sure you forward onMessageReceived and onNewToken calls to IterableFirebaseMessagingService.handleMessageReceived and IterableFirebaseMessagingService.handleTokenRefresh, respectively:

public class MyFirebaseMessagingService extends FirebaseMessagingService {

    @Override
    public void onMessageReceived(RemoteMessage remoteMessage) {
        IterableFirebaseMessagingService.handleMessageReceived(this, remoteMessage);
    }

    @Override
    public void onNewToken(String s) {
        IterableFirebaseMessagingService.handleTokenRefresh();
    }
}

To handle silent push notifications, use a custom FirebaseMessagingService.

Note that FirebaseInstanceIdService is deprecated and replaced with onNewToken in recent versions of Firebase.

# Disabling push notifications to a device

When a user logs out, you typically want to disable push notifications to that user/device. This can be accomplished by calling disablePush. Please note that it will only attempt to disable the device if you have previously called registerForPush.

In order to re-enable push notifications to that device, simply call registerForPush as usual when the user logs back in.

# Step 6: Use Iterable to send a test Android push notification

To send a test Android push notification:

1. In Iterable, navigate to Audience > User Lookup and enter the user's email or userId.

   • In the devices array, find an object where appPackageName corresponds to your app's package name, and endpointEnabled is true.
   • Copy that object's token.

2. Navigate to Settings > Apps and Websites.

3. Click the mobile app to which you'd like to send a push notification.

4. In the Integrations section, click Test Push. You'll see a Send Test Push window:

   

5. Enter the device token you found above, and specify a test message.

6. Click Send test.

Monitor the recipient's device to verify that the push notification arrives.

# Android 13: Push notification permissions

To learn about the POST_NOTIFICATIONS permission introduced in Android 13, which allows you to prompt users for permission to send push notifications, check out this information about Android 13.

# Customizing Android push notifications

The following sections describe the technical setup necessary for various Android push notification customizations in Iterable.

For marketer-specific information about how to configure these features in Iterable when sending a campaign, read Creating a Push Notification Campaign.

# Notification color

Add this line to AndroidManifest.xml to specify the notification color:

<meta-data android:name="iterable_notification_color" android:value="#FFFFFF"/>

where #FFFFFF can be replaced with a hex representation of a color of your choice. In stock Android, the notification icon and action buttons will be tinted with this color.

You can also use a color resource:

<meta-data android:name="iterable_notification_color" android:resource="@color/notification_color"/>

# Channel name

Since Android 8.0, Android requires apps to specify a channel for every notification. Iterable uses one channel for all notification; to customize the name of this channel, add this to AndroidManifest.xml:

<meta-data android:name="iterable_notification_channel_name" android:value="Notifications"/>

You can also use a string resource to localize the channel name:

<meta-data android:name="iterable_notification_channel_name" android:resource="@string/notification_channel_name"/>

# Badging / dots

Since Android 8.0, apps can indicate that they've received a notification by displaying a dot (badge) on their icon. By default, Iterable's Android SDK displays these badges. However, you can explicitly enable or disable them in AndroidManifest.xml:

<meta-data android:name="iterable_notification_badging" android:value="false"/>

# Sounds

To add sound to Android push notifications sent with Iterable, follow these instructions:

1. Put the necessary sound files in the Android project's res/raw folder.

   IMPORTANT

   • Sound file names should be lowercase and should not have any special characters.
   • Take a look at Android's documentation about supported media formats. This documentation is not specific about which formats work for push notifications, so it's best to test as necessary.

2. Navigate to Content > Templates and open the push notification template.

3. Click Edit details and scroll down.

4. Enter the path to the custom sound file in the Custom sound field.

   

   NOTES

   • To use the default push notification sound, set this field to default.
   • Whether or not a device plays the sound or vibrates depends on the user's device settings.

# Deep links

Iterable push notification templates make it possible to set deep link URLs for iOS and Android.

To learn more about using Iterable's Android SDK to handle deep links, read Android App Links.

If your app is not using Iterable's Android SDK, it can still handle a deep link contained in an Iterable push notification. Iterable provides the deep link URL in the defaultAction object included in the notification's payload. When this object's type field is set to openUrl, the data field will contain the deep link URL.

After a user has opened a tapped on a push notification to open the app, use the getPayloadData method on IterableApi to access the notification payload.

# Background color

To set the background color of a push notification, update the AndroidManifest.xml file:

<meta-data android:name="iterable_notification_color" android:value="#FFFFFF"></meta-data>

#FFFFFF can be replaced with any hex color. In stock Android, the notification icon and action buttons will be tinted with this color.

Alternatively, you can also use a color resource:

<meta-data android:name="iterable_notification_color" android:resource="@color/notification_color"/>

# Custom icons

By default, push notifications display the application icon. To use a different icon, place the image resource inside your app's res/drawable directory. Then, edit AndroidManifest.xml, adding the following line:

<meta-data android:name="iterable_notification_icon" android:resource="@drawable/ic_notification_icon"/>

In this case, ic_notification_icon is the name of the notification icon.

Alternatively, call setNotificationIcon(String iconName) to use the custom icon, referencing the image asset by name and without a file extension.

# Further reading

For more information about push notifications in Iterable, read:

• Sending Push Notifications
• Iterable's Android SDK