Overview

The CleverTap Push Templates SDK enhances user engagement through rich, customizable push notification templates that work seamlessly with CleverTap Android SDK v7.3.0 and above.

Prerequisites

To use the CleverTap Push Templates SDK, you must integrate the CleverTap Android SDK version 7.3.0 or above.

Installation

The Android Push Templates SDK supports the following two integration options:

• Out-of-the-box Implementation : Uses CleverTap's default notification handling, where templates are rendered without additional customization or code changes in your app.
• Custom Implementation: Allows you to control how push notifications are received and displayed.

Configure Out-of-the-Box Push Notification Handling

To configure out-of-the-box Push Notification Handling, perform the following steps:

1. Add the dependencies to the build as given in the following code:

implementation "com.clevertap.android:push-templates:2.0.0" // 2.0.0 and above
implementation "com.clevertap.android:clevertap-android-sdk:7.3.0" // 7.3.0 and above

2. Add the following line of code to your Application class:

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

CleverTapAPI.setNotificationHandler(PushTemplateNotificationHandler() as NotificationHandler);

Customize Push Notification Handling

To customize the Push Notification handling, 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)
    }
}

Supported Push Templates

You can implement the following customizable push notification templates using the CleverTap Android Push Template Library SDK. The templates can be broadly classified as follows:

Basic Templates

• Standard Push Template
• Advanced Push Template

Carousel Templates

• Auto Carousel Template
• Manual Carousel Template

Advanced Templates

• Timer Template
• Text over Image Template
• Five Icons Template
• Rating Template
• Product Catalog Template
• Input Box Template

Standard Push Template

Standard Template is a default template for push notifications received on apps that supports a simple layout with title, message, image, and optional buttons, ideal for quick, informative alerts. For example, an e-commerce business might want to inform customers that their order is on the way.

Advanced Push Template

This template supports rich media, deep links, and enhanced customization for more engaging messages. It is ideal for interactive, visually appealing messages. For example, businesses can use it to build excitement for new product drops, early access offers, or feature rollouts that benefit from strong visuals and clear Call to Action (CTAs).

For template outputs Android 11 and below, refer to Push Templates on Android v11 and below.

Template Keys

Auto Carousel Template

Auto Carousel is an automatic revolving carousel push notification that automatically cycles through multiple cards or slides within a single notification. Each card typically includes an image, title, description, and a CTA button, allowing users to view multiple offers, messages, or product highlights without leaving their device’s notification tray.

Template Keys

Manual Carousel Template

Manual Carousel is an interactive push notification format that allows users to browse through multiple cards or slides at their own pace. Each card typically features rich content such as images, titles, short descriptions, and a CTA. Navigation is user-controlled, with arrows or swipe gestures enabling the transition between cards.

If only a single image is available for download, this template falls back to the Basic Template.

Template Keys

Five Icons Template

The Five Icons template is a sticky push notification with no text, just five icons, and a close button that can help your users go directly to the functionality of their choice with a button click.

The library does not notify if at least three icons are not retrieved. The bifurcation of each CTA is captured in the event Notification Clicked within the property wzrk_c2a.

By default, if the user clicks on any notification area except the five and close icons, an activity intent launches.

Template Keys

Timer Template

Timer template is a dynamic and time-sensitive push notification template designed to display a live countdown timer directly within the notification. This format is ideal for creating urgency around limited-time offers, flash sales, upcoming events, or deadlines. You can update the new message, title, or background image automatically once the countdown expires, keeping the notification relevant and engaging after expiry.

Timer notification is only supported for Android version 8 and above. For Android versions below 8, the library falls back to the Basic Template.

Template Keys

Text over Image Template

Text over Image template is a visually immersive push notification format designed to maximize the use of imagery. In this layout, the background image spans the entire surface area of the notification, creating an edge-to-edge visual experience. All accompanying text such as the title, message, and call-to-action is seamlessly overlaid on top of the image, ensuring the message is prominent while maintaining a clean, modern aesthetic.

The library falls back to the Advanced Template if the image cannot be downloaded.

Template Keys

Rating Template

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

Template Keys

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:

Template Keys

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.

Ensure 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

Template Variations

Users can preview and render different variations of outputs for each Push template type based on the following factors:

• Version-based Output: Notifications render differently for Android version 12 and above and version 11 and below. Key considerations include the following:
  • Android 13 and above: Use images no larger than 450x450 px for optimal rendering.
  • Android 12 and above: Center-align any text within images is centered for to ensure better visibility.
  • Android 11 and 12: Use image file size below 100 KB to prevent rendering issues.
  • Android 11 and below: Use images of under 3 MB or lower is recommended for better to maintain optimal performance.
• CTA-based Output: Notification renders based on whether CTA buttons are included in the payload.

Dark Mode

Push templates automatically adapt to the device's theme settings, rendering notifications in dark or light mode.

Theme Setting	Notification Appearance	Sample Output
Dark mode enabled	Notification renders with a dark background
Dark mode disabled	Notification renders with a light background.

📘

Custom Color Definitions

Templates support custom color definitions that adapt to both themes for visual consistency.

🚧

SDK Version Requirement

To use the Dark mode feature, ensure you are using Push Templates SDK version 2.0.0 and above.

Image Scaling

Android supports various image scaling options to control how images appear in push notifications. CleverTap optimizes image rendering to maintain visual consistency across devices while leveraging Android native scaling behavior. To handle scaling in a Push template, you must add the key pt_scale_type key and the value is set as fit_center or center_crop based on the requirement.

The following table lists the different scaling settings in Push templates:

Image Scaling Type	Description	Sample Output
Keep Original	Applies to all expanded images in Android push templates. The image is scaled proportionally (maintaining the aspect ratio) to ensure that both its width and height fit within the boundaries of the image container. This ensures the entire image is visible without any cropping.
Scale to Fill	Applies to all expanded images in all Android push templates. The image is resized uniformly while preserving the aspect ratio. If necessary, it is scaled down so that both width and height fit within the image container. This ensures the full image is displayed without any part being cropped.

🚧

SDK Version Requirement

To use the Image scaling feature, ensure you are using Push Templates SDK version 2.0.0 and above.

Image Specifications

The following are the image specifications and guidelines for the Push Templates:

Image Guidelines

Ensure images for the following templates meet the specified size guidelines:

For Text over Image Template, ensure the text is center-aligned within the image for devices running OS version 12 and above.

FAQs

For FAQs, refer to Push Templates FAQs.