Setting up Android Push Notifications

Iterable can send push notifications to iOS and Android devices. Push notifications display content such as text and images, and can alert users by playing a sound.

Depending on a user's device settings, push notifications can appear even when an application is closed. Upon receipt, users can tap these notifications to open the associated application or perform another action associated with the notification.

Read Google's Notifications Overview document for technical information about push notifications on Android.

This guide describes the technical setup necessary to send Android push notifications with Iterable. Work with your organization's mobile engineers to complete the steps below.

# Table of contents

# Overview

To use Iterable to send push notifications to an Android app, the following things must happen:

• Your users must install your mobile app.
• Your mobile app must store a unique Firebase token on the user's Iterable profile.
• Iterable must contact Firebase, telling it what content to send and which devices to send it to.

Iterable's Android SDK automatically tracks push notification opens. Alternatively, you can track push notification opens with Iterable's POST /api/events/trackPushOpen API.

# Instructions

Follow the steps below to set up Iterable to send Android push notifications:

# 1. Set up Firebase for your Android app

For Iterable to send Android push notifications, it must communicate with Firebase Cloud Messaging.

To learn how to set up Firebase for your Android app, read Google's Add Firebase to your Android project document.

# 2. Create a mobile app in Iterable

Iterable uses mobile apps to store the details about your app's name, identifier, platform, and store URL.

To create a mobile app in Iterable:

1. Navigate to Settings > Apps and websites.

2. Click Add a new app or website.

3. For Name, enter the name of your app. For example, Iterable Docs Push.

4. For Platform, select Android.

5. For Package name, enter your application ID. For example, com.example.yourapp.

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

7. Click Create app.

# 3. Assign a push integration to the mobile app

A push integration stores the API key Iterable uses to authenticate with Firebase when sending push notifications on your behalf. A push integration is stored as part of a mobile app. You can either associate an existing push integration or a new push integration with a mobile app.

# Existing push integration

To associate an already-existing push integration with the newly created mobile app:

1. Navigate to Settings > Apps and websites.

2. In the Unassigned Integrations section, find the existing push integration.

3. For that push integration, click Assign App.

4. In the Assign Push Integration window, select the mobile app you just created.

5. Click Assign.

# New push integration

To create a new push integration for the mobile app:

1. With the new mobile app still open in Iterable, click the Configure button next to Firebase, bringing up a window similar to the following:

   

2. Select whether or not to Use OS Notifications.

   Enabling this option causes Android (instead of Iterable's SDK) to render push notifications for the app. Disabling this option causes the Iterable SDK to render push notifications for the app.

   WARNING

   It's usually best to leave this option disabled unless you are not using the Android SDK (or have another compelling reason to enable it).

3. For API Key, enter your Firebase Server Key, which can be found in your Firebase project.

4. Click Update to save the push integration.

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

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

# 5. Additional SDK configuration

# Handling Firebase push messages and tokens

The SDK adds a FirebaseMessagingService to the app manifest automatically, 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.

# 6. Use Iterable to send a test Android push notification

To send a test Android push notification, first look up the device token for a test user who has installed and run the app:

1. In Iterable, navigate to Audience > Contact Lookup and enter the user's email address or their user ID (the search box will reflect the necessary field):

   • In the devices array, examine the appPackageName field to find the object that corresponds to your app.

   • Copy the token, since you'll need this to send the test push notification.

Then, send a test push notification to that user:

2. Navigate to Settings > Apps and websites.

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

   • In the Integrations section, click Test Push to bring up the Send Test Push window:

     

3. For Device Token, enter the token you located above.

4. For Message, enter a message to display in the push notification.

5. Click Send Notification.

Then, monitor the recipient's device (or emulator) 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.

# Upgrading from Google Cloud Messaging (GCM) to Firebase Cloud Messaging (FCM)

Google has deprecated Google Cloud Messaging (GCM) in favor of Firebase Cloud Messaging (FCM). GCM APIs will soon be removed.

Refer to Google's Firebase migration guide for information about migrating your app from GCM to FCM.

# 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 icon

Notifications are rendered with the app launcher icon by default. To specify a custom icon for notifications, add this line to AndroidManifest.xml:

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

where ic_notification_icon is the name of the notification icon.

# 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"/>

# Notification 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"/>

# Notification 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"/>

# Adding sounds to Android push notifications

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.

# Adding deep links to Android push notifications

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.

# Setting the background color of a push notification

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"/>

# Add custom icons to your push notifications

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:

• Push Notification Setup FAQ.
• Creating a Push Notification Campaign
• Iterable's Android SDK