Android SDK — Push Notifications

Setting up Push Notifications using Taplytics is simple. Follow the steps below to get started.

# Step
1 Setup: Android Studio
2 Receiving Push Notifications
3 Push Campaigns
4 Custom Data and Tracking Push Interactions
5 Special Push Options (title, silent, priority)
6 Resetting Users
6 Tracking Self Built Notifications

New!: Taplytics has updated the way push notifications are handled. See here!

1. Setup

Android Studio

If you wish to use Push Notifications on Taplytics, you must add the following permissions (replace com.yourpackagename with your app's package name) to your Android Manifest:

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

And you must add the following receiver and service under your application tag:

<receiver
    android:name="com.taplytics.sdk.TLGcmBroadcastReceiver"
    android:permission="com.google.android.c2dm.permission.SEND" >
    <intent-filter>
        <action android:name="com.google.android.c2dm.intent.RECEIVE" />
    </intent-filter>

    <intent-filter>
         <action android:name="taplytics.push.OPEN" />
         <action android:name="taplytics.push.DISMISS" />
    </intent-filter>
</receiver>
<service android:name="com.taplytics.sdk.TLGcmIntentService" />

Then add the following to your build.gradle:

compile("com.google.android.gms:play-services-gcm:9.+")

In order to set the notification icon you must add a meta-tag to your manifest specifying the drawable you want to use as the icon:

<meta-data android:name="com.taplytics.sdk.notification_icon"
            android:resource="@drawable/notification_icon"/>

If this isn't set the application's icon will be used instead.


2. Receiving Push Notifications

To send your users Push Notifications, we'll need you to upload your Google Cloud Messaging credentials. Please follow this guide to do so.

Activity Routing

By default, when a notification sent by Taplytics is clicked, it will open up the main activity of the application. However, you may want to route your users to a different Activity. This can be done on the Taplytics Push page.

Simply add a custom data value to the push with the key tl_activity and with the full (including package name) class name of your activity. For example:

image

Push Title

By default, the title of a push notification will be the application name.

Currently, the best way to change the title of a push notification is to add a tl_title custom key. For Example:

image

Getting the Push Token

Sometimes, it can be useful to have the actual token generated by GCM, to target pushes at specific users.

To get this token, use the following method:

Taplytics.setTaplyticsPushTokenListener(new TaplyticsPushTokenListener() {
    @Override
    public void pushTokenReceived(String token) {
        //Do something with the push token here.
    }
});

3. Push Campaigns

Push Campaigns allow you to send pushes in reaction to events, called triggers. Location based triggers use the Google Play Services Location API in order to create geofences for the locations you specify.

For location based triggers add the following two permissions to you manifest:

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

The ACCESS_FINE_LOCATION permission is used to get the devices location, and the RECEIVE_BOOT_COMPLETED permission is to re-register the locations which the campaign is triggered in, which get cleared upon reboot.

Also needed is a boot receiver to re-register events, and an intent service to react to geofence events. Both which go in your manifest, under the application tag:

<receiver android:name="com.taplytics.sdk.TLBootReceiver">
    <intent-filter>
        <action android:name="android.intent.action.BOOT_COMPLETED"/>
    </intent-filter>
</receiver>

<service android:name="com.taplytics.sdk.TLGeofenceEventService"/>

The only additional dependency needed is Google Play Services Location API, which you can add to your module's build.gradle file under dependencies:

compile 'com.google.android.gms:play-services-location:9.+'

Geofences require location services 9.x

4. Custom Data and Tracking Push Interactions

Taplytics has changed as of version 1.9 and push notifications are easier than ever:

To retrieve custom data set in the Taplytics dashboard, as well as to track push interactions (receive, open, dismiss), simply extend the TLBroadcastReceiver and override the function that you need. Then, rplace the TLGcmBroadcastReceiver in your manifest with that one!

Below is an example receiver that explains exactly how this is done. You can put this class directly in your app and start tracking push notifications right away. By default, taplytics will open the LAUNCH activity of your app, but this can be changed by not calling the super (see example below).

Note that Taplytics automatically tracks the following, however if you would like to do so for internal reasons, this is how.

Note there is also a TLGgcmBroadcastReceiverNonWakeful.

/**
 * Example receiver to take action with push notifications.
 *
 * Make sure to add this to your manifest (see the docs)
 *
 * Overriding any of these is entirely optional.
 *
 * By default, taplytics will open the launch activity of your
 * app when a push notification is clicked.
 *
 */
public class MyBroadcastReceiver extends TLGcmBroadcastReceiver {

    @Override
    public void pushOpened(Context context, Intent intent) {

        //A user clicked on the notification! Do whatever you want here!

        /* If you call through to the super, 
        Taplytics will launch your app's LAUNCH activity. 
        This is optional. */
        super.pushOpened(context, intent);
    }

    @Override
    public void pushDismissed(Context context, Intent intent) {
        //The push has been dismissed :(

    }

    @Override
    public void pushReceived(Context context, Intent intent) {
        //The push was received, but not opened yet!

        /*
        If you add the custom data of tl_silent = true to the push notification,
        there will be no push notification presented to the user. However, this will
        still be triggered, meaning you can use this to remotely trigger something
        within the application!
         */
    }
}

And then in your manifest:

<receiver
    android:name=".MyBroadcastReceiver"
    android:permission="com.google.android.c2dm.permission.SEND" >
    <intent-filter>
        <action android:name="com.google.android.c2dm.intent.RECEIVE" />
    </intent-filter>

    <intent-filter>
         <action android:name="taplytics.push.OPEN" />
         <action android:name="taplytics.push.DISMISS" />
    </intent-filter>
</receiver>
<service android:name="com.taplytics.sdk.TLGcmIntentService" />

5. Special Push Options (title, silent push, etc)

The dashboard allows for custom data to be entered into your push notifications. However there are some options that can be added to the custom data for special functionality.

Name Values Explanation
tl_title String This changes the TITLE of the push notification. By default, it is your application's name. But with this option you can change the title to be anything.
tl_silent boolean: true/false Taplytics does give the option to send a SILENT push notification (meaning it will not actually show up in the user's push notifications). It will, however, still triger the pushReceived callback in the custom receiver above!
tl_priority integer Set the priority of the push notification. For more info see the section 'Correctly set and manage notification priorty' here. The value set must be the integer that is associated with the priorities, which can be found here.

6. Resetting Users

Sometimes, it may be useful to reset an app user for push notifications. For instance, if a user is logged out in your app, you may want them to stop receiving push notifications. If you wish to turn off push notifications for an app user, it can be done as such:

TaplyticsResetUserListener listener = new TaplyticsResetUserListener() {
  @Override
  public void finishedResettingUser() {
    // Do stuff
  }
};

Taplytics.resetAppUser(listener);

Now, the device that the app is currently running on will no longer receive push notifications until the app user attributes are updated again.

7. Tracking Self Built Notifications

You maybe using Taplytics simply to send push notifications. In the event that you already have a system to build notifications, then when extending the Taplytics BroadcastReceiver, you will see duplicates.

To avoid this problem, first, do not call super.onReceive() where super would be the TLGCMBroadcastReceiver.

Now, Taplytics will not have any push notification tracking if you do this.

To mitigate this, you must use the Taplytics functions provided. In each function, you must pass in the tl_id in the notification attempt.

Push Open

Taplytics.trackPushOpen("tl_id",customKeys);

Where tl_id is retrieved from the notification intent. CustomKeys is the metadata passed into the notification. It is optional/nullable

Push Dismissed

Taplytics.trackPushDismissed("tl_id",customKeys);

Where tl_id is retrieved from the notification intent. CustomKeys is the metadata passed into the notification. It is optional/nullable

Push Received

Taplytics.trackPushReceived("tl_id",customKeys);

Where tl_id is retrieved from the notification intent. CustomKeys is the metadata passed into the notification. It is optional/nullable