Push Templates by CleverTap

CleverTap Push Templates SDK helps you engage with your users using fancy push notification templates built specifically to work with CleverTap Android SDK v4.4.0 and above.

Installation

Out of the box

1. Add the dependencies to the build.gradle:

implementation "com.clevertap.android:push-templates:1.2.4"
implementation "com.clevertap.android:clevertap-android-sdk:7.0.3" // 4.4.0 and above

2. Add the following line to your Application class

CleverTapAPI.setNotificationHandler((NotificationHandler)new PushTemplateNotificationHandler());

CleverTapAPI.setNotificationHandler(PushTemplateNotificationHandler() as NotificationHandler);

Custom Handling Push Notifications

Add the following code in your custom FirebaseMessageService class:

public class PushTemplateMessagingService extends FirebaseMessagingService {
    @Override
    public void onMessageReceived(RemoteMessage remoteMessage) {
        CTFcmMessageHandler()
                .createNotification(getApplicationContext(), remoteMessage);
    }
}

class MyFcmMessageListenerService : FirebaseMessagingService() {
    override fun onMessageReceived(message: RemoteMessage) {
        super.onMessageReceived(message)
            CTFcmMessageHandler()
                .createNotification(applicationContext, message)
    }
}

Migration from v0.0.8 to v1.0.0 and above

Remove the following Receivers and Services from your AndroidManifest.xml and follow the steps given above:

<service
    android:name="com.clevertap.pushtemplates.PushTemplateMessagingService">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT"/>
    </intent-filter>
</service>

<service
    android:name="com.clevertap.pushtemplates.PTNotificationIntentService"
    android:exported="false">
        <intent-filter>
            <action android:name="com.clevertap.PT_PUSH_EVENT"/>
        </intent-filter>
</service>

<receiver
    android:name="com.clevertap.pushtemplates.PTPushNotificationReceiver"
    android:exported="false"
    android:enabled="true">
</receiver>

<receiver
    android:name="com.clevertap.pushtemplates.PushTemplateReceiver"
    android:exported="false"
    android:enabled="true">
</receiver>

Dashboard Usage

While creating a Push Notification campaign on CleverTap, just follow the steps below:

1. On the WHAT section, pass the desired values in the title and message fields.

📘

Key-value pair

We prioritize title and message provided in the key-value pair - as shown in step 2, over these fields.

2. Click on Advanced and then click on _Add pair _to add the Template Keys.

3. You can also add the above keys into one JSON object and use the pt_json key to fill in the values

4. Send a test push and schedule.

Template Types

Basic Template

Basic Template is the basic push notification received on apps.

Auto Carousel Template

Auto carousel is an automatic revolving carousel push notification.

Manual Carousel Template

This is the manual version of the carousel. The user can navigate to the next image by clicking on the arrows.

If only one image can be downloaded, this template falls back to the Basic Template.

Filmstrip Variant

The manual carousel has an extra variant called filmstrip. This can be used by adding the following key-value -

(Expanded and unexpanded example)

Rating Template

Rating template lets your users give you feedback. This feedback is captured in the event Rating Submitted within the property wzrk_c2a.

Product Catalog Template

The product catalog template lets you showcase different product images (or a product catalog) before the user can click on the BUY NOW option, which can take them directly to the product via deep links. This template has two variants.

Vertical View

Linear View

Use the following keys to enable the linear view variant of this template:

Five Icons Template

The Five Icons template presents a push notification without text, featuring only five icons. With a single click, users can conveniently access their preferred functionality. If at least three icons are not retrieved from the source, the library does not render any notification.

The details of each Call-to-Action (CTA) are captured in the Notification Clicked event within the property wzrk_c2a. If the user clicks on any notification area except the five icons, an activity intent is launched by default.

Timer Template

This template features a live countdown timer. You can even choose to show different titles, messages, and background images after the timer expire.

Timer notification is only supported for Android N (7) and above. For OS versions below N, the library falls back to the Basic Template.

Zero Bezel Template

The Zero Bezel template ensures that the background image covers the entire available surface area of the push notification. All the text is overlayed on the image.

The library will fall back to the Basic Template if the image can't be downloaded.

Input Box Template

The Input Box Template lets you collect any input, including feedback from your users. It has four variants.

With CTAs

The CTA variant of the Input Box Template uses action buttons on the notification to collect input from the user.

To set the CTAs, use the Advanced Options when setting up the campaign on the dashboard.

📘

Display the Notification in the tray (for Android 12 and above)

To keep the notification in the notification tray even after clicking the CTA, set the value for the pt_dismiss_on_click payload key as false and add the dismissNotification function to your code.

Following is a sample code for adding the dismissNotification function:

fun dismissNotification(intent: Intent?, applicationContext: Context){
        intent?.extras?.apply {
            var autoCancel = true
            var notificationId = -1

            getString("actionId")?.let {
                Log.d("ACTION_ID", it)
                autoCancel = getBoolean("autoCancel", true)
                notificationId = getInt("notificationId", -1)
            }
            /**
             * If using InputBox template, add ptDismissOnClick flag to not dismiss notification
             * if pt_dismiss_on_click is false in InputBox template payload. Alternatively if normal
             * notification is raised then we dismiss notification.
             */
            val ptDismissOnClick = intent.extras!!.getString(PTConstants.PT_DISMISS_ON_CLICK,"")

            if (autoCancel && notificationId > -1 && ptDismissOnClick.isNullOrEmpty()) {
                val notifyMgr: NotificationManager =
                    applicationContext.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
                notifyMgr.cancel(notificationId)
            }
        }
    }

CTAs with Remind Later option

This variant of the Input Box Template is advantageous if the user wants to be reminded of the notification after some time. Clicking on the remind later button raises an event to the user profiles, with a custom user property p2, whose value is a future timestamp. You can have a campaign running on the dashboard that will send a reminder notification at the timestamp in the event property.

To set one of the CTAs as a Remind Later button, set the action id to remind from the dashboard.

Reply as an Event

This variant raises an event capturing the user's input as an event property. The app is not opened after the user sends the reply.

To use this variant, use the following values for the keys.

Reply as an Intent

This variant passes the reply to the app as an Intent. The app can then process the reply and take appropriate actions.

To use this variant, use the following values for the keys.

To capture the input, the app can get the pt_input_reply key from the Intent extras.

Template Keys

Basic Template

Auto Carousel Template

Manual Carousel Template

Rating Template

Product Catalog Template

Five Icons Template

Timer Template

Zero Bezel Template

Input Box Template

📘

Note

pt_title and pt_msg in all the templates support HTML elements like bold <b>, italics <i> and underline <u>

Developer Notes

• Using images of 3 MB or lower is recommended for better performance under Android 11.
• A silent notification channel with importance: HIGH is created every time on an interaction with the Rating, Manual Carousel, and Product Catalog templates with a silent sound file. This prevents the notification sound from playing when the notification is re-rendered.
• The silent notification channel is deleted whenever the notification is dismissed or clicked.
• For Android 11 and Android 12, please use images that are less than 100kb else notifications will not be rendered as advertised.
• Due to Android 12 trampoline restrictions, the Input Box template with auto open of deep link feature will fall back to simply raising the event for a reply.

Image Specifications

📘

Template Rendering

The templates render differently depending on the device and the version of the operating system.

The following are the image specifications for the Push Templates:

Additional Guidelines

• Auto and Manual Carousel: Images must not exceed 850x425 pixels for Android 11 and Android 12 devices and have a 2:1 aspect ratio.
• Basic, Auto, and Manual Carousel: Images must not exceed 400x200 for Android 13+ devices.
• Five Icons: Images must not exceed 300x300 for Android 13+ devices.
• Zero Bezel: If the image contains text, it must be centered for optimal display on Android 12+ devices.
• Product Catalog: Images must have a 1:1 aspect ratio and a file size of 80 KB or less.
• Recommendation for Android 12+ Devices: Ensure any text within images is centered for better visibility.

Android 12 Trampoline restrictions

With Android 12, the Rating and Product Display template push notifications do not get dismissed once the deep link is opened.

To handle this, you'll have to add the following code to the onActivityResumed or onNewIntent of your app

Bundle payload = activity.getIntent().getExtras();
    if (payload.containsKey("pt_id")&& payload.getString("pt_id").equals("pt_rating"))
    {
        NotificationManager nm = (NotificationManager) activity.getSystemService(Context.NOTIFICATION_SERVICE); 
        nm.cancel(payload.getInt("notificationId"));
    }
    if (payload.containsKey("pt_id")&& payload.getString("pt_id").equals("pt_product_display"))
    {
        NotificationManager nm = (NotificationManager) activity.getSystemService(Context.NOTIFICATION_SERVICE); 
        nm.cancel(payload.getInt("notificationId"));
    }

val payload = activity.intent?.extras
        if (payload?.containsKey("pt_id") == true && payload["pt_id"] =="pt_rating")
        {
            val nm = activity.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
            nm.cancel(payload["notificationId"] as Int)
        }
        if (payload?.containsKey("pt_id") == true && payload["pt_id"] =="pt_product_display")
        {
            val nm = activity.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
            nm.cancel(payload["notificationId"] as Int)
        }

Android 12 Screenshots

Refer to the renditions of all the Push Templates on Android 12 devices.