Push Notifications - GCM

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

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.+")

If you are using Firebase in your project as well, you must match the google play services version to the Firebase version.

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:

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:

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. Rich Push Notifications

Implementing rich push notification support can help improve user engagement with your push notifications with image content attached. We currently support JPEG and PNG images sent from the Taplytics dashboard or API.

Android will automatically crop all images to be a 2:1 aspect ratio, scaling if necessary.

The max image size that can be uploaded is 10mb. Note that images are not downscaled and if an image is sent, the full file size of the crop will be used.

Here is an example of a push notification with an image:

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

5. 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, replace 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" />

If you are handling push notifications with custom payloads, the custom data key/values will be added to the custom_keys object as seen below in an example push payload:

{
  "data": {
    "message": "Test Push",
    "tl_id": "",
    "custom_keys": {
      "custom_data_key": "custom_data_value"
    },
    "image_url": ""
  }
}

6. Special Push Options (title, priority, icon)

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.

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

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