Flurry Push For Android

Flurry Push enables app developers to send targeted messages to re-engage and retain users. To start using Flurry Push on Android:

  1. Integrate the latest Flurry SDK for Android

  2. Follow the integration steps below

  3. Provide Flurry your authorization credentials

  4. Test your integration via test push

Push Setup

Add Flurry Marketing and Analytics AARs to your app dependency block:

Add Firebase in your app by following instructions here. Once you’ve completed Firebase setup, make sure you add the following firebase dependencies:

Note

If using Auto-Integration, do not extend FirebaseMessagingService, as Flurry does so. If using Manual Integration, follow the Firebase steps as normal.

Note

If your app is running on Android 16 you might experience the following crash ‘Fatal Exception: java.lang.SecurityException: Requires VIBRATE permission ‘ due to an internal Android OS bug that has been fixed in Android 4.2.1 (https://android.googlesource.com/platform/frameworks/base/+/cc2e849). To prevent this bug from happening add the vibration permission for API 16 to the manifest file:

uses-permission android:name=”android.permission.VIBRATE” android:maxSdkVersion=”18”

Note

It is recommended to update your app so that it targets Android 13 or higher. And request the post notification permission based in your app’s context. Please refer to (https://developer.android.com/develop/ui/views/notifications/notification-permission) for further instructions. Example to add the post notification permission to the manifest file:

uses-permission android:name=”android.permission.POST_NOTIFICATIONS”

Integration Types

  1. Auto Integration - With Auto Integration, Flurry handles everything for you. We’ll receive the notification, convert it to a FlurryMessage, show the notification, handle the notification click, handle the dismissed notification, and handle all the Flurry logging associated with it. Want some customized functionality? You have the option of passing us a listener to handle any of these steps yourself.

  2. Manual Integration - You handle the notification receivers and log events (notification received, notification opened, notification canceled) to Flurry.

Important

If you are integrating Flurry Push alongside one or more other push providers, we recommend using manual instead of auto integration.

Auto Integration

Flurry will receive the push notification and convert it to a Flurry Message. You may optionally set a listener to get notified when a push is received, opened, or dismissed. This allows you to handle and customize each event as you wish. If you handle the event, be sure to return “true” to the callback to request Flurry to not take further action. If you would like Flurry to handle it, simply return “false” and Flurry will proceed with the default behavior. The expected behavior for each callback is listed below.

  • Notification Received - Flurry will show the notification if the app is in the background, and WILL NOT show it if the app is in the foreground. Foreground / Background check can be made by calling FlurryMessaging.isAppInForeground(). If you decide to handle the event yourself, the opened and dismissed callbacks will not be called by Flurry, so be sure to log the notification opened and dismissed events yourself by calling logNotificationOpened and logNotificationCancelled.

  • Notification Clicked - This is called when the user clicks on the notification and the app is about to open. Either you can handle the clicked event and open the appropriate activity, or Flurry will launch the launcher or “click_action” activity with the Intent.FLAG_ACTIVITY_NEW_TASK flag. Note: This will only be called if Flurry handled and displayed the notification when received. (i.e. you returned false to the onNotificationReceived callback).

  • Notification Canceled - This event occurs when the user dismisses or cancels the notification. This is purely informational. Note: This will only be called if Flurry handled and displayed the notification when received. (i.e. you returned false to the onNotificationReceived callback).

  • Token refresh - This event occurs when the system refreshes the push notification token. This is purely informational.

  • Non flurry message received - If a push notification is received from a sender other than Flurry, Flurry will simply pass the push object back to you. You may cast it to the appropriate object type to use as you please.

Integration Steps

In your Application class, place the following code in the onCreate() to initialize Flurry Push.

Note

If this code does not live in the application class, then notifications will be the system default and will not follow any of your customization settings.

  1. (Optional) Create a listener that implements FlurryMessagingListener

  1. Define your customized options using the FlurryMarketingOptions.Builder builder.

You can read more about notification channels and push notification icon and color down below.

Note

You only have to set these values if you request Flurry to create the push notification for you.

  1. Create the FlurryMarketingModule with your defined options.

  1. Register the module while initializing Flurry in the FlurryAgent.Builder

Manual Integration

Manual integration should be used when you setup the notification receivers. Flurry provides a few helper methods for you to determine if a notification is from Flurry, and if so, converts the notification into a FlurryMessage. In manual integration, you must log the following events as described:

  • Notification Received - When a notification from Flurry is received, log this event via the FlurryMessaging.logNotificationReceived(FlurryMessage) api.

  • Notification Clicked - If showing a notification, log this event when the notification is clicked / opened via the FlurryMessaging.logNotificationClicked(FlurryMessage) api.

  • Notification Canceled - If showing a notification, log this event when the notification is canceled / dismissed via the FlurryMessaging.logNotificationCancelled(FlurryMessage) api.

  • Set token - If you receive a callback that the token has been refreshed, provide Flurry with the updated token via the FlurryMessaging.setToken(String) api.

Integration Steps

In your Application class, place the following code in the onCreate() to initialize Flurry Push.

Note

Notifications will not work if this code doesn’t live in the application class. Currently Flurry only supports FCM, so the following sample code will display FCM integration.

  1. Retrieve the token from your push provider.

  1. Define your customized options using the FlurryMarketingOptions.Builder builder.

You can read more about notification channels and push notification icon and color.

Note

You only have to set these values if you request Flurry to create the push notification for you.

  1. Create the FlurryMarketingModule with your defined options.

  1. Register the module while initializing Flurry in the FlurryAgent.Builder

Sample Code

  1. In your FCM FirebaseInstanceIdService.onTokenRefresh, pass the updated token to Flurry

  1. In your FCM FirebaseMessagingService.onMessageReceived, handle the notification like so:

Notification Channels

Overview

In Android Oreo, Android introduced the concept of notification channels. Any app targeting Android O+, must post push notifications to a notification channel. You can read more about it here. The Flurry Marketing Suite supports notification channels.

You Define the Notification Channel

In this case, you create the notification channel and provide us the ID. When you request Flurry to show a push notification, we will use this channel.

Note

If you pass us a notification channel ID, but forget to create the channel itself, Flurry will fallback to the Flurry default channel.

Here is some sample code to show you how to specify the channel ID while initializing Flurry Marketing Module.

Flurry Default Channel

If you don’t want to create a channel, or if you pass in a channel ID for a channel that has not been created, Flurry will fallback on a default channel. This default channel has the following attributes:

ID - <your_package_name>.flurry

Name - News and Announcements

Description - General news and announcements

Importance - default

Lights - On

Vibration - On

Lockscreen Visibility - Public

Deleting the Flurry Default Channel

Flurry will automatically delete its default channel if you pass in a valid channel ID. If, for any reason, you’d like to manually delete the channel, you may use the ID <your_package_name>.flurry

Background Sessions

When pushes are received or tapped, a Flurry background session occurs to allow Flurry to measure push metrics. Flurry exposes a method to allow you to determine whether such sessions are counted in the same way that foreground sessions are counted: withIncludeBackgroundSessionsInMetrics. Make sure to set withIncludeBackgroundSessionsInMetrics according to your app measurement needs.

Setting this method to YES/true:

  • Background sessions initiated by push notifications, as well as session data for other background sessions, will be included in overall session metrics. This will impact time spent, uniques and other metrics.

Setting this method to NO/false

  • Background sessions including sessions initiated by push notifications will not be included in overall session metrics. Push events such as PushOpened will be reported even if set to NO/false.

  • You must set to NO/false to exclude push-initiated background sessions from being counted as sessions for your app.

This is set in the Builder:

Push Notification Icon and Color

Starting with API 21+, Android requires a new design for icons. You can read about the change here. The Android docs note:

The system ignores all non-alpha channels in action icons and in the main notification icon. You should assume that these icons will be alpha-only. The system draws notification icons in white and action icons in dark gray.

In order to ensure this does not occur, be sure to follow the notification icon design guidelines.

In order to prevent icon display problems, pass in the default icon and background color to Flurry while initializing Flurry Marketing Module. Flurry will use these values when displaying the notification. Depending on the Android OS the user is on, you can provide the appropriate icon. Refer to the sample code below:

Deep Linking

Deep linking is the ability for an app to direct a user to a specified location in the app. When setting up a campaign, users may input a deep link.

IMG1

Flurry has reserved the “deeplink” keyword in the app data payload. You may leverage the deeplink string the user enters during campaign set up via FlurryMessage.getAppData().get(“deeplink”). By setting up the proper handling of this string during integration, you will ensure that the user lands on the deep link location after tapping on the notification.

While Flurry can’t define the deep linking experience for an app, here is an example on how to use our suite to implement it.

Deep Linking Setup and Example Code

  1. Set up Deep Linking in Your App

You’ll have to set up certain activities in your app for deep linking. Follow the Android guide to do so. After this, your AndroidManifest.xml can look something like this

  1. Send a Push Notification with a Deep Link

Send a push notification via the Flurry Portal, specifying your “deeplink” value. Using the manifest specified above, an example deep link could look like testapp://deeplink/example?key1=value1.

Let’s breakdown the example deep link. testapp://deeplink/example?key1=value1

Scheme - “testapp”

Host - “deeplink”

Path Prefix - “example”

Additional query params (key value pairs that can be extracted in the associated activity) - key1=value1

3.Retrieve the Deeplink on Notification Clicked

Use the api FlurryMessage.getAppData().get(“deeplink”) to retrieve the deep link when the user clicks on the notification. Be sure to do your null checks, and then set the deeplink string to the intent’s data.

Note

This example handles the deep link inside the FlurryMessagingListener.onNotificationClicked(). If you manually showed the notification, you can handle the deep link similarly, but in your click listener.

  1. Retrieve Extra Query Params From Deep Link in the Associated Activity (if applicable)

Inside the activity that is associated with your deep link, retrieve any extra query params and set up the activity as needed. Using our example above, your onCreate may look something like this -

Push Example

Imagine you are building an app which contains a series of news articles. Each news article is identified by a unique integer identifier. Let’s say the local sports team drafts a top prospect, and you want to send a push notification with the breaking news article. On the Flurry portal, you can create a new push campaign, set the title to “Breaking News!”, set the body to “49ers pick up top prospect”, and set the reserved “deeplink” field to “appproject://main/article?number=149”.

Note

This is a sample deep link, you should format your deep links in accordance with your app’s deep link schema.

Now, when the FlurryMessage is received by the application, you may use the api FlurryMessage.getAppData().get(“deeplink”) to retrieve the deep link string specified in Flurry Push for the message. Be sure to do your null checks, and use the string to set the new intent in onNotificationClicked.

Note

There is another way to implement deep linking using key-value pairs. On the flurry portal, you can add a custom key value pair as: key=article and value=149. On the app side, fetch this key value pair by FlurryMessage.getAppData().get(“article”). Now the app can download the article with unique identifier “149”, and display that to the user.