Android Push Templates

Learn how to implement CleverTap push templates.

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.2" // 4.4.0 and above
  1. 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.

982

Configure What Section

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

Add Key Value Pairs

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

Add Key into JSON Object

  1. Send a test push and schedule.

Template Types

Basic Template

Basic Template is the basic push notification received on apps.

624

Basic Push Notification Template

Auto Carousel Template

Auto carousel is an automatic revolving carousel push notification.

624

Auto Carousel Template

Manual Carousel Template

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

624

Manual Carousel Template

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 -

Template KeyRequiredValue
pt_manual_carousel_typeOptionalfilmstrip

(Expanded and unexpanded example)

624

Filmstrip Variant

Rating Template

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

624

Rating Template

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

624

Product Catalog Template-Vertical View

Linear View

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

Template KeyRequiredValue
pt_product_display_linearOptionaltrue
624

Product Catalog Template-Linear View

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.

Sample Five Icon Template

Five Icons Template

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.

618

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

618

Zero Bezel Template

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.

618

Input Box Template-With CTAs

Template KeyRequiredValue
pt_dismiss_on_clickOptionaltrue (Dismisses the notification without opening the app).

📘

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.

Template KeyRequiredValue
pt_event_nameRequiredfor e.g. Remind Later,
pt_event_property_<property_name_1>Optionalfor e.g. <property_value>,
pt_event_property_<property_name_2>Optionalfuture epoch timestamp. For e.g., \$D_1592503813
pt_dismiss_on_clickRequiredValue should be true. It dismisses the notification without opening the app and raises a required event to the user profile, needed to send a reminder notification.
618

Input Box Template-CTAs with Remind Later option

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.

Template KeyRequiredValue
pt_input_labelRequiredfor e.g., Search
pt_input_feedbackRequiredfor e.g., Thanks for your feedback
pt_event_nameRequiredfor e.g. Searched,
pt_event_property_<property_name_2>Requiredfixed value - pt_input_reply
pt_event_property_<property_name_1>Optionalfor e.g. <property_value>,
618

Input Box Template-Reply as an Event

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.

Template KeyRequiredValue
pt_input_labelRequiredfor e.g., Search
pt_input_feedbackRequiredfor e.g., Thanks for your feedback
pt_input_auto_openRequiredfixed value - true

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

618

Input Box Template-Reply as an Intent

Template Keys

Basic Template

Basic Template KeysRequiredDescription
pt_idRequiredValue - pt_basic
pt_titleRequiredTitle
pt_msgRequiredMessage
pt_bgRequiredBackground Color in HEX
pt_msg_summaryRequiredMessage line when Notification is expanded
pt_subtitleOptionalSubtitle
pt_big_imgOptionalImage
pt_icoOptionalLarge Icon
pt_dl1OptionalOne Deep Link (minimum)
pt_title_clrOptionalTitle Color in HEX
pt_msg_clrOptionalMessage Color in HEX
pt_small_icon_clrOptionalSmall Icon Color in HEX
pt_jsonOptionalAbove keys in JSON format

Auto Carousel Template

Auto Carousel Template KeysRequiredDescription
pt_idRequiredValue - pt_carousel
pt_titleRequiredTitle
pt_msgRequiredMessage
pt_dl1RequiredDeep Link (Max one)
pt_img1RequiredImage One
pt_img2RequiredImage Two
pt_img3RequiredImage Three
pt_bgRequiredBackground Color in HEX
pt_msg_summaryOptionalMessage line when Notification is expanded
pt_subtitleOptionalSubtitle
pt_imgnOptionalImage N
pt_icoOptionalLarge Icon
pt_title_clrOptionalTitle Color in HEX
pt_msg_clrOptionalMessage Color in HEX
pt_small_icon_clrOptionalSmall Icon Color in HEX
pt_jsonOptionalAbove keys in JSON format

Manual Carousel Template

Manual Carousel Template KeysRequiredDescription
pt_idRequiredValue - pt_manual_carousel
pt_titleRequiredTitle
pt_msgRequiredMessage
pt_dl1RequiredDeep Link One
pt_img1RequiredImage One
pt_img2RequiredImage Two
pt_img3RequiredImage Three
pt_bgRequiredBackground Color in HEX
pt_msg_summaryOptionalMessage line when Notification is expanded
pt_subtitleOptionalSubtitle
pt_dl2OptionalDeep Link Two
pt_dlnOptionalDeep Link for the nth image
pt_imgnOptionalImage N
pt_icoOptionalLarge Icon
pt_title_clrOptionalTitle Color in HEX
pt_msg_clrOptionalMessage Color in HEX
pt_small_icon_clrOptionalSmall Icon Color in HEX
pt_jsonOptionalAbove keys in JSON format
pt_manual_carousel_typeOptionalfilmstrip

Rating Template

Rating Template KeysRequiredDescription
pt_idRequiredValue - pt_rating
pt_titleRequiredTitle
pt_msgRequiredMessage
pt_default_dlRequiredDefault Deep Link for Push Notification
pt_dl1RequiredDeep Link for first/all star(s)
pt_bgRequiredBackground Color in HEX
pt_msg_summaryOptionalMessage line when Notification is expanded
pt_subtitleOptionalSubtitle
pt_dl2OptionalDeep Link for second star
pt_dl3OptionalDeep Link for third star
pt_dl4OptionalDeep Link for fourth star
pt_dl5OptionalDeep Link for fifth star
pt_icoOptionalLarge Icon
pt_title_clrOptionalTitle Color in HEX
pt_msg_clrOptionalMessage Color in HEX
pt_small_icon_clrOptionalSmall Icon Color in HEX
pt_jsonOptionalAbove keys in JSON format
pt_big_imgOptionalImage

Product Catalog Template

Product Catalog Template KeysRequiredDescription
pt_idRequiredValue - pt_product_display
pt_msgRequiredMessage
pt_titleRequiredTitle
pt_img1RequiredImage One
pt_img2RequiredImage Two
pt_img3RequiredImage Three
pt_bt1RequiredBig text for first image
pt_bt2RequiredBig text for second image
pt_bt3RequiredBig text for third image
pt_st2RequiredSmall text for second image
pt_st1RequiredSmall text for first image
pt_st3RequiredSmall text for third image
pt_dl1RequiredDeep Link for first image
pt_dl2RequiredDeep Link for second image
pt_dl3RequiredDeep Link for third image
pt_price1RequiredPrice for first image
pt_price2RequiredPrice for second image
pt_price3RequiredPrice for third image
pt_bgRequiredBackground Color in HEX
pt_product_display_actionRequiredAction Button Label Text
pt_product_display_action_clrRequiredAction Button Background Color in HEX
pt_subtitleOptionalSubtitle
pt_product_display_linearOptionalLinear Layout Template ("true"/"false")
pt_title_clrOptionalTitle Color in HEX
pt_msg_clrOptionalMessage Color in HEX
pt_small_icon_clrOptionalSmall Icon Color in HEX
pt_jsonOptionalAbove keys in JSON format

Five Icons Template

Five Icons Template KeysRequiredDescription
pt_idRequiredValue - pt_five_icons
pt_img1RequiredIcon One
pt_img2RequiredIcon Two
pt_img3RequiredIcon Three
pt_dl1RequiredDeep Link for first icon
pt_dl2RequiredDeep Link for second icon
pt_dl3RequiredDeep Link for third icon
pt_bgRequiredBackground Color in HEX
pt_img4OptionalIcon Four
pt_img5OptionalIcon Five
pt_dl4OptionalDeep Link for fourth icon
pt_dl5OptionalDeep Link for fifth icon
pt_small_icon_clrOptionalSmall Icon Color in HEX
pt_jsonOptionalAbove keys in JSON format

Timer Template

Timer Template KeysRequiredDescription
pt_idRequiredValue - pt_timer
pt_titleRequiredTitle
pt_msgRequiredMessage
pt_dl1RequiredDeep Link
pt_bgRequiredBackground Color in HEX
pt_timer_thresholdRequiredTimer duration in seconds (minimum 10)
pt_title_altOptionalTitle to show after timer expires
pt_msg_altOptionalMessage to show after timer expires
pt_subtitleOptionalSubtitle
pt_msg_summaryOptionalMessage line when Notification is expanded
pt_big_imgOptionalImage
pt_big_img_altOptionalImage to show when timer expires
pt_chrono_title_clrOptionalColor for timer text in HEX
pt_timer_endOptionalEpoch Timestamp to countdown to (for example, $D_1595871380 or 1595871380). Not needed if pt_timer_threshold is specified.
pt_title_clrOptionalTitle Color in HEX
pt_msg_clrOptionalMessage Color in HEX
pt_small_icon_clrOptionalSmall Icon Color in HEX
pt_jsonOptionalAbove keys in JSON format

Zero Bezel Template

Zero Bezel Template KeysRequiredDescription
pt_idRequiredValue - pt_zero_bezel
pt_titleRequiredTitle
pt_msgRequiredMessage
pt_big_imgRequiredImage
pt_msg_summaryOptionalMessage line when Notification is expanded
pt_subtitleOptionalSubtitle
pt_small_viewOptionalSelect text-only small view layout (text_only)
pt_dl1OptionalDeep Link
pt_title_clrOptionalTitle Color in HEX
pt_msg_clrOptionalMessage Color in HEX
pt_small_icon_clrOptionalSmall Icon Color in HEX
pt_icoOptionalLarge Icon
pt_jsonOptionalAbove keys in JSON format

Input Box Template

Input Box Template KeysRequiredDescription
pt_idRequiredValue - pt_input
pt_titleRequiredTitle
pt_msgRequiredMessage
pt_big_imgRequiredImage
pt_input_labelRequiredLabel text to be shown on the input
pt_input_feedbackRequiredFeedback
pt_dl1RequiredDeep Link
pt_msg_summaryOptionalMessage line when Notification is expanded
pt_subtitleOptionalSubtitle
pt_big_img_altOptionalImage to be shown after feedback is collected
pt_event_nameOptionalName of Event to be raised
pt_event_property_<property_name_1>OptionalValue for event property <property_name_1>
pt_event_property_<property_name_2>OptionalValue for event property <property_name_2>
pt_event_property_<property_name_n>OptionalValue for event property <property_name_n>
pt_input_auto_openOptionalAuto open the app after feedback
pt_title_clrOptionalTitle Color in HEX
pt_msg_clrOptionalMessage Color in HEX
pt_small_icon_clrOptionalSmall Icon Color in HEX
pt_icoOptionalLarge Icon
pt_dismiss_on_clickOptionalDismiss notification on click
pt_jsonOptionalAbove keys in JSON format

📘

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:

TemplateAspect RatiosFile TypeMaximum File Size
Basic4:3 or 2:1.JPG500 KB
Auto Carousel2:1 (Android 11 and 12) and 4:3 (Below Android 11).JPG86 KB
Manual Carousel2:1 (Android 11 and 12) and 4:3 (Below Android 11).JPG86 KB
Manual Carousel-FilmStrip1:1.JPG86 KB
Rating4:3 (Android 11 and 12) and 2:1 (Below Android 11).JPG5 MB
Product Catalog1:1.JPG80 KB
Five Icon1:1.JPG or .PNG50 KB
Zero Bezel4:3 or 2:1.JPG500 KB
Timer4:3 or 2:1.JPG326 KB
Input Box4:3 or 2:1.JPG500 KB

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.