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:

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 cancelled) 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 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 Cancelled - 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: notifications will not work if this code doesn’t live in the application class.

  1. Optionally 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. 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 Cancelled - If showing a notification, log this event when the notification is cancelled / 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 introduce 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. Flurry’s 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.

// define channel attributes (name, description, and id)

public static final String NOTIFICATION_CHANNEL_ID = “SomeChannelId”

public static final String NOTIFICATION_CHANNEL_NAME = “UserFacingChannelName”

public static final String NOTIFICATION_CHANNEL_DESCRIPTION = “User facing description of the channel”

// create notification channel

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {

NotificationManager notificationManager = (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);

NotificationChannel notificationChannel = notificationManager.getNotificationChannel(NOTIFICATION_CHANNEL_ID);

if (notificationChannel == null) {

// only create it if it hasn’t been created already

notificationChannel = new NotificationChannel(NOTIFICATION_CHANNEL_ID, NOTIFICATION_CHANNEL_NAME, NotificationManager.IMPORTANCE_HIGH);

notificationChannel.setDescription(NOTIFICATION_CHANNEL_DESCRIPTION);

notificationChannel.enableLights(true);

notificationChannel.enableVibration(true);

notificationChannel.setLockscreenVisibility(Notification.VISIBILITY_PUBLIC);

notificationManager.createNotificationChannel(notificationChannel);

}

}

// pass Flurry the channel ID while setting up Marketing Module

FlurryMarketingOptions flurryMarketingOptions = new FlurryMarketingOptions.Builder()

.withDefaultNotificationChannelId(NOTIFICATION_CHANNEL_ID)

.build();

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 - .flurry

Name - News and Announcements

Description - General news and announcements

Importance - default

Lights - On

Vibration - On

Lockscreen Visibility - Public

Deleting Flurry’s 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 .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:

new FlurryAgent.Builder()

.withModule(marketingModule)

.withIncludeBackgroundSessionsInMetrics(false)

.build(context, FLURRY_API_KEY);

Push Notification Icon and Color

Overview

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. See the sample code below:

private void initializeFlurry() {

// pass Flurry the default icon id, and background color

int notificationIcon = getNotificationIcon();

FlurryMarketingOptions flurryMarketingOptions = new FlurryMarketingOptions.Builder()

.withDefaultNotificationIconResourceId(notificationIcon)

.withDefaultNotificationIconAccentColor(getResources().getColor(R.color.notification_icon_background))

.build();

FlurryMarketingModule marketingModule = new FlurryMarketingModule(flurryMessagingOptions);

}

private int getNotificationIcon() {

// based on the current device’s Build, return the appropriate icon. Note: If you only return an icon 21+, a device < 21 will still show the icon, but will not have a background color.

if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.LOLLIPOP) {

return R.drawable.ic_notification_white_and_transparent;

} else {

return R.drawable.ic_notification;

}

}

Deep Linking

Overview

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. Setup Deeplinking in Your App

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

android:name=”.DeeplinkTestActivity”>

android:scheme=”testapp”

android:host=”deeplink”

android:pathPrefix=”/example” />

  1. Send a Push Notification with a Deeplink

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

Let’s breakdown the example deeplink. 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 deeplink 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.

@Override

public boolean onNotificationClicked(FlurryMessage flurryMessage) {

// NOTE: THIS METHOD WILL ONLY BE CALLED IF FLURRY HANDLED onNotificationReceived callback

// determine if you’d like to handle the clicked notification yourself or not

boolean handled = false;

// see if notification contains deeplink

if (flurryMessage.getAppData() != null && flurryMessage.getAppData().containsKey(“deeplink”)) {

String deeplink = flurryMessage.getAppData().get(“deeplink”);

// create the Intent

final Intent deeplinkIntent = new Intent(Intent.ACTION_VIEW);

deeplinkIntent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);

deeplinkIntent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP);

// set the data using your deeplink

deeplinkIntent.setData(Uri.parse(deeplink));

// add the FlurryMessage to extras

FlurryMessaging.addFlurryMessageToIntentExtras(deeplinkIntent, flurryMessage);

// make sure the deeplink resolves to an activity, then open it

if (deeplinkIntent.resolveActivity(context.getPackageManager()) != null) {

context.startActivity(deeplinkIntent);

// tell flurry you’ve handled the notification

handled = true;

}

}

return handled;

}

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

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

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

public class DeeplinkTestActivity extends AppCompatActivity {

@Override

protected void onCreate(Bundle savedInstanceState) {

super.onCreate(savedInstanceState);

// get the data from the intent.

Intent intent = getIntent();

Uri data = intent.getData();

// deeplink - testapp://deeplink/example?key1=value1

if (data != null) {

// get the additional query params added to the deeplink

String value1 = data.getQueryParameter(“key1”); // will return “value1”

}

// get the FlurryMessage from extras

FlurryMessage flurryMessage = FlurryMessaging.getFlurryMessageFromIntent(getIntent());

if (flurryMessage != null) {

// use as required

}

}

}

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 a sample deeplink, you should format your deeplinks 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.