Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
248 lines (166 sloc) 10.6 KB

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 Image Push
4 Custom Data and Tracking Push Interactions
5 Special Push Options (title, priority, icon)
6 Manual Token Registration (Optional)
7 Tracking Self Built Notifications
8 Troubleshooting

Google has changed the way push notifications work from using GCM to FCM, migrate ASAP!

1. Setup

Set up your Firebase certificate on Taplytics by following these docs.

Android Studio

Follow these instructions to add firebase to your project. Then, add the following to your dependencies in your build.gradle:

implementation com.google.firebase:firebase-messaging:17.+

Android Manifest

If you wish to use Push Notifications on Taplytics, you must add the following to your AndroidManifest.xml file under the application tag:

<service
    android:name="com.taplytics.sdk.fcm.TLFirebaseMessagingService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

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

image

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

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

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": ""
  }
}

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

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_priority integer Set the priority of the push notification. For more info see the section 'Correctly set and manage notification priority' here. The value set must be the integer that is associated with the priorities, which can be found here.
tl_image_icon boolean Will not show a preview image as the notification icon when set to false. Defaults to true.
tl_large_icon boolean Will show the app icon in the notification when set to true. Defaults to false.

6. Manual Token Registration (Optional)

If you already have a system to receive Firebase push tokens, you can use TLFirebaseMessagingServiceLite instead of TLFirebaseMessagingService. Instead of overriding onNewToken and saving the token to our system automatically, all TLFirebaseMessagingServiceLite does is process the push notification. You must also use the start option manualPushToken and set it to true to bypass saving the token automatically.

options.put("manualPushToken", true);
Taplytics.startTaplytics(this, "YOUR_API_KEY", options);

You then must use Taplytics.savePushToken("PUSH_TOKEN") to enable push notifications through Taplytics.

7. Tracking Self Built Notifications

You may be using Taplytics simply to send push notifications. If you already have a system to build notifications, then extending the Taplytics BroadcastReceiver will cause you to 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.

The tl_id is the push notification id from Taplytics and is part of the overall notification payload.

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

8. Troubleshooting

Using the shake menu, you can copy the token to your clipboard, force to save the token to Taplytics, or renew the token.

Taplytics.showMenu(); // Shows the shake menu, exposing some useful items like the push token

image

You can’t perform that action at this time.