Android Push Templates

Learn how to implement and customize Push Notification for your Android device.

Overview

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

Prerequisites

To use the CleverTap Push Templates SDK, you must integrate the CleverTap Android SDK version v7.4.1 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.2.0" // 2.0.0 and above
implementation "com.clevertap.android:clevertap-android-sdk:7.8.0" // 7.3.0 and above
  1. Add the following line of code to your Application class:
CleverTapAPI.setNotificationHandler(PushTemplateNotificationHandler() as NotificationHandler);
CleverTapAPI.setNotificationHandler((NotificationHandler)new PushTemplateNotificationHandler());

Customize Push Notification Handling

To customize the Push Notification handling, add the following code in your custom FirebaseMessageService class:

class MyFcmMessageListenerService : FirebaseMessagingService() {
    override fun onMessageReceived(message: RemoteMessage) {
        super.onMessageReceived(message)
            CTFcmMessageHandler()
                .createNotification(applicationContext, message)
    }
}
public class PushTemplateMessagingService extends FirebaseMessagingService {
    @Override
    public void onMessageReceived(RemoteMessage remoteMessage) {
        CTFcmMessageHandler()
                .createNotification(getApplicationContext(), remoteMessage);
    }
}

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

Carousel Templates

Advanced Templates

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.

Standard Push Template

Standard Push Template

GIF Support Across Templates

You can use GIFs in templates to make notifications more dynamic and engaging. CleverTap supports GIF playback in push notifications starting from Android SDK version 7.5.0 on devices running Android 14 and above.

GIF Support Example

GIF Support Example

Supported Templates

GIFs are supported in the following templates:

Template NameKey ParameterSupported FromNotes
Standard Templatewzrk_gifSDK v7.5.0Android 14+ only; size limits below do not apply
Advanced Templatept_gifSDK v7.5.0Supports optional pt_gif_frames
Timer Templatept_gifSDK v7.5.0GIF continues until timer expiry
Text over Image Templatept_gifSDK v7.5.0Supports pt_gif for expanded and pt_gif_collapsed for collapsed view
Rating Templatept_gifSDK v7.5.0Optional; static fallback if unsupported
Vertical Image with CTApt_gifSDK v7.5.0Supports GIFs in expanded (pt_gif) and collapsed (pt_gif_collapsed) views
📘

Note:

For templates other than Standard Push Template, Refer to the GIF Size Guidelines for smooth rendering.

GIF Size Guidelines

To ensure optimal performance across devices:

GIF SizeRecommended Number of Frames
180 x 120 px15
240 x 160 px10
300 x 200 px6

You can use Ezgif Tool to resize or optimize your GIFs.

Limitations

  • Devices running Android 13 and below display the first frame as a static image.
  • Some OEMs may not support GIF rendering even on Android 14+.
  • On certain devices, the heads-up notification may show only the first frame until expanded.
  • GIFs may not loop smoothly if the frame count is high or the file size exceeds 1 MB.

Example: Standard Push Template with GIF

To use a GIF in a Standard Push Template, include the following payload key:

{
  "wzrk_gif": "https://example.com/your-gif-url.gif"
}

For templates using pt_gif, specify the key as:

{
  "pt_gif": "https://example.com/your-gif-url.gif"
}

SDK Requirements

RequirementMinimum Version
CleverTap Android SDKv7.5.0
Push Templates SDKv2.2.0
Android OS14 and above for animation playback

GIF Support in Standard Push Template

CleverTap supports GIFs in standard push templates from SDK version 7.5.0 on devices running Android 14 and above. This allows you to add animated media to push notifications, enhancing user engagement through dynamic visuals. To use a GIF in a standard push template, pass the key wzrk_gif with the value set to the URL of the GIF image.

GIF Support Example

GIF Support Example

Specifications and Design Guidelines

  • Supported on Android 14+ with SDK v7.5.0 and above.
  • Applies only to the Standard push template
  • For older Android versions or SDKs, CleverTap shows the first frame of the GIF as a static image
  • Use the recommended aspect ratio for the selected template to avoid cropping or distortion
  • Keep file size under 1MB for smooth rendering
  • Opt for looped, visually clear GIFs that work well even if partially cropped

Limitations

  • Devices running Android 13 and below do not support GIF playback; a static fallback image is shown
  • Some OEMs may not fully support GIF rendering, even on Android 14 and above
  • On certain devices, the heads-up notification may display only the first frame, while the full GIF appears when the notification tray is expanded.

GIF Size Guidelines

To use GIFs in the Push Templates, ensure you are using Push Templates SDK version 2.2.0 and above. Also, make sure GIFs meet the specified size guidelines. You can use Ezgif tool to resize the GIF.

GIF SizeRecommended Number of Frames
180 x 120 px15
240 x 160 px10
300 x 200 px6

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.

Advanced Push Template

Advanced Push Template

Template Keys

Advanced Template KeysRequiredDescription
pt_idRequiredIndicates the type of template, for example, pt_basic.
pt_titleRequiredMaps to the campaign title, the main headline of your notification must be concise and attention-grabbing, defining the exact purpose of your campaign.
pt_msgRequiredMaps to the campaign message, the body text of your notification. The message should clearly convey the purpose of your campaign.
pt_msg_summaryRequiredMessage line when Notification is expanded.
pt_subtitleOptionalSubtitle
pt_bgRequiredBackground color of your push notification. You can use it to match your brand theme or draw visual attention to the notification. It accepts HEX codes or color pickers.
pt_bg_darkOptionalBackground color of your push notification in dark mode
pt_big_imgOptionalImage
pt_big_img_alt_textOptionalAlt Text for Image
pt_gifOptionalGIF
pt_gif_framesOptionalNumber of frames to extract from the GIF
pt_icoOptionalLarge Icon
wzrk_hide_large_iconOptional

Hide the large icon in Android notifications
Values:

  • hide = true to hide the icon
  • hide = false to show the icon (Default)
  • pt_dl1OptionalOne Deep Link (minimum)
    pt_title_clrOptionalTitle Color in HEX
    pt_title_clr_darkOptionalTitle Color in HEX in dark mode
    pt_msg_clrOptionalMessage Color in HEX
    pt_msg_clr_darkOptionalMessage Color in HEX in dark mode
    pt_small_icon_clrOptionalSmall Icon Color in HEX
    pt_small_icon_clr_darkOptionalSmall Icon Color in HEX in dark mode
    pt_scale_typeOptionalSpecify the image scaling type for notifications. Available values:
  • fit_center
  • center_crop

  • For more information on how it works, refer to Image Scaling .
    pt_stickyOptionalShould the notification be sticky? ("true"/"false")
    pt_dismissOptionalAuto dismiss the notification after a set time (value in seconds)
    pt_jsonOptionalAbove template keys in JSON format

    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.

    Auto Carousel Template

    Auto Carousel Template

    Template Keys

    Auto Carousel Template KeysRequiredDescription
    pt_idRequiredIndicates the type of template, for example, pt_carousel.
    pt_titleRequiredMaps to the campaign title, the main headline of your notification must be concise and attention-grabbing, defining the exact purpose of your campaign.
    pt_msgRequiredMaps to the campaign message, the body text of your notification. The message should clearly convey the purpose of your campaign.
    pt_msg_summaryOptionalMessage line when Notification is expanded.
    pt_subtitleOptionalSubtitle
    pt_dl1RequiredDeep Link (Max one)
    pt_img1RequiredImage One
    pt_img2RequiredImage Two
    pt_img3RequiredImage Three
    pt_imgnOptionalImage N
    pt_bgRequiredBackground Color in HEX
    pt_bg_darkRequiredBackground Color in HEX in dark mode
    pt_icoOptionalLarge Icon
    wzrk_hide_large_iconOptional

    Hide the large icon in Android notifications
    Values:

  • hide = true to hide the icon
  • hide = false to show the icon (Default)
  • pt_title_clrOptionalTitle Color in HEX
    pt_title_clr_darkOptionalTitle Color in HEX in dark mode.
    pt_msg_clrOptionalMessage Color in HEX
    pt_msg_clr_darkOptionalMessage Color in HEX in dark mode
    pt_small_icon_clrOptionalSmall Icon Color in HEX
    pt_small_icon_clr_darkOptionalSmall Icon Color in HEX in dark mode
    pt_stickyOptionalShould the notification be sticky? ("true"/"false")
    pt_dismissOptionalAuto dismiss the notification after a set time (value in seconds)
    pt_jsonOptionalAbove keys in JSON format

    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.

    Manual Carousel Template

    Manual Carousel Template

    Template Keys

    Manual Carousel Template KeysRequiredDescription
    pt_idRequiredIndicates the type of template, for example,pt_manual_carousel
    pt_titleRequiredMaps to the campaign title, the main headline of your notification must be concise and attention-grabbing, defining the exact purpose of your campaign.
    pt_msgRequiredMaps to the campaign message, the body text of your notification. The message should clearly convey the purpose of your campaign.
    pt_msg_summaryOptionalMessage line when Notification is expanded
    pt_subtitleOptionalSubtitle
    pt_dl1RequiredDeep Link One
    pt_dl2OptionalDeep Link Two
    pt_dlnOptionalDeep Link for the nth image
    pt_img1RequiredImage One
    pt_img2RequiredImage Two
    pt_img3RequiredImage Three
    pt_imgnOptionalImage N
    pt_bgRequiredBackground Color in HEX
    pt_bg_darkRequiredBackground Color in HEX in dark mode
    pt_icoOptionalLarge Icon
    wzrk_hide_large_iconOptional

    Hide the large icon in Android notifications
    Values:

  • hide = true to hide the icon
  • hide = false to show the icon (Default)
  • pt_title_clrOptionalTitle Color in HEX
    pt_title_clr_darkOptionalTitle Color in HEX in dark mode
    pt_msg_clrOptionalMessage Color in HEX
    pt_msg_clr_darkOptionalMessage Color in HEX in dark mode
    pt_small_icon_clrOptionalSmall Icon Color in HEX
    pt_small_icon_clr_darkOptionalSmall Icon Color in HEX in dark mode
    pt_stickyOptionalShould the notification be sticky? ("true"/"false")
    pt_dismissOptionalAuto dismiss the notification after a set time (value in seconds)
    pt_jsonOptionalAbove keys in JSON format
    pt_manual_carousel_typeOptionalfilmstrip
    pt_gifOptionalGIF
    pt_gif_framesOptionalNumber of frames to extract from the GIF

    Icons Template

    The Icons template is a sticky push notification with a maximum of 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.

    📘

    Private Beta

    This feature is released in Private Beta. For more information about this feature, contact your Customer Success Manager or CleverTap Support.

    Icons Template

    Template Keys

    Five Icons Template KeysRequiredDescription
    pt_idRequiredIndicates the type of template, for example,pt_five_icons
    pt_img1RequiredIcon One
    pt_img2RequiredIcon Two
    pt_img3RequiredIcon Three
    pt_img4OptionalIcon Four
    pt_img5OptionalIcon Five
    pt_dl1RequiredDeep Link for first icon
    pt_dl2RequiredDeep Link for second icon
    pt_dl3RequiredDeep Link for third icon
    pt_dl4OptionalDeep Link for fourth icon
    pt_dl5OptionalDeep Link for fifth icon
    pt_bgRequiredBackground Color in HEX
    pt_small_icon_clrOptionalSmall Icon Color in HEX
    pt_small_icon_clr_darkOptionalSmall Icon Color in HEX in dark mode
    pt_stickyOptionalShould the notification be sticky? ("true"/"false")
    pt_dismissOptionalAuto dismiss the notification after a set time (value in seconds)
    pt_jsonOptionalAbove keys in JSON format

    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.

    Timer Template

    Timer Template

    Template Keys

    Timer Template KeysRequiredDescription
    pt_idRequiredIndicates the type of template, for example, pt_timer
    pt_titleRequiredMaps to the campaign title, the main headline of your notification must be concise and attention-grabbing, defining the exact purpose of your campaign.
    pt_title_altOptionalTitle to show after timer expires
    pt_msgRequiredMaps to the campaign message, the body text of your notification. The message should clearly convey the purpose of your campaign.
    pt_msg_altOptionalMessage to show after timer expires
    pt_msg_summaryOptionalMessage line when Notification is expanded
    pt_subtitleOptionalSubtitle
    pt_dl1RequiredDeep Link
    pt_big_imgOptionalImage
    pt_big_img_altOptionalImage to show when timer expires
    pt_gifOptionalGIF
    pt_gif_framesOptionalNumber of frames to extract from the GIF
    pt_bgRequiredBackground Color in HEX
    pt_bg_darkRequiredBackground Color in HEX in dark mode
    pt_chrono_title_clrOptionalColor for timer text in HEX
    pt_chrono_title_clr_darkOptionalColor for timer text in HEX in dark mode
    pt_timer_thresholdRequiredTimer duration in seconds (minimum 10)
    pt_timer_endOptionalEpoch Timestamp to countdown to (for example, $D_1595871380 or 1595871380). Not required if pt_timer_threshold is specified.
    pt_title_clrOptionalTitle Color in HEX
    pt_title_clr_darkOptionalTitle Color in HEX in dark mode
    pt_msg_clrOptionalMessage Color in HEX
    pt_msg_clr_darkOptionalMessage Color in HEX in dark mode
    pt_small_icon_clrOptionalSmall Icon Color in HEX
    pt_small_icon_clr_darkOptionalSmall Icon Color in HEX in dark mode
    pt_scale_typeOptionalSpecify the image scaling type for notifications. Available values:
  • fit_center
  • center_crop

  • For more information on how it works, refer to Image Scaling .
    pt_render_terminalOptionalDetermines whether terminal notification is rendered
    Value- true or false
    pt_msg_summary_altOptionalSummary to display once the timer expires
    pt_stickyOptionalShould the notification be sticky? ("true"/"false")
    pt_dismissOptionalAuto dismiss the notification after a set time (value in seconds)
    pt_jsonOptionalAbove keys in JSON format

    Chronometer Styling Keys

    KeyRequiredDescription
    pt_chrono_styleOptionalControls styling mode. Available values: solid (default), gradient_linear , gradient_radial
    pt_chrono_bg_clrOptionalBackground color (HEX). Required if style = solid
    pt_chrono_border_clrOptionalBorder color (HEX). No border if absent
    pt_chrono_grad_clr1OptionalGradient start color (HEX)
    pt_chrono_grad_clr2OptionalGradient end color (HEX)
    pt_chrono_grad_dirOptionalAngle in degrees (String). Default "90"
    pt_chrono_border_radiusOptionalCorner radius in dp (Density-independent Pixels) (Default: 6)
    pt_chrono_border_widthOptionalBorder width in dp. No border if absent, even if pt_chrono_border_clr is set.
    pt_chrono_title_clrOptionalCountdown text color (falls back to pt_title_clr)

    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.

    Text over Image Push Template

    Text over Image Push Template

    Template Keys

    Text over Image Template KeysRequiredDescription
    pt_idRequiredIndicates the type of template, for example, pt_zero_bezel.
    pt_titleRequiredMaps to the campaign title, the main headline of your notification must be concise and attention-grabbing, defining the exact purpose of your campaign.
    pt_msgRequiredMaps to the campaign message, the body text of your notification. The message should clearly convey the purpose of your campaign.
    pt_msg_summaryOptionalMessage line when Notification is expanded.
    pt_subtitleOptionalSubtitle
    pt_big_imgRequiredImage
    pt_gifOptionalGIF
    pt_gif_framesOptionalNumber of frames to extract from the GIF
    pt_small_viewOptionalSelect text-only small view layout (text_only)
    pt_dl1OptionalDeep Link
    pt_title_clrOptionalTitle Color in HEX
    pt_title_clr_darkOptionalTitle Color in HEX in dark mode
    pt_msg_clrOptionalMessage Color in HEX
    pt_msg_clr_darkOptionalMessage Color in HEX in dark mode
    pt_small_icon_clrOptionalSmall Icon Color in HEX
    pt_small_icon_clr_darkOptionalSmall Icon Color in HEX
    pt_scale_typeOptionalSpecify the image scaling type for notifications. Available values:
  • fit_center
  • center_crop

  • For more information on how it works, refer to Image Scaling .
    pt_big_img_collapsedOptionalImage for the collapsed view
    pt_gif_collapsedOptionalGIF for the collapsed view
    pt_gif_frames_collapsedOptionalNumber of frames to extract from the GIF for the collapsed view
    pt_big_img_collapsed_alt_textOptionalAlt Text for Image in the collapsed view
    pt_scale_type_collapsedOptionalScaleType for the image in the collapsed View ("center_crop"/"fit_center")
    pt_stickyOptionalShould the notification be sticky? ("true"/"false")
    pt_dismissOptionalAuto dismiss the notification after a set time (value in seconds)
    pt_icoOptionalLarge Icon
    wzrk_hide_large_iconOptional

    Hide the large icon in Android notifications
    Values:

  • hide = true to hide the icon
  • hide = false to show the icon (Default)
  • pt_jsonOptionalAbove keys in JSON format

    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

    Product Catalog Template- Vertical View

    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
    Product Catalog Template-Linear View

    Product Catalog Template-Linear View

    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 sends a reminder notification at the timestamp in the event property.

    Prerequisites

    To enable the Remind Later functionality with the CTA template, perform the following steps:

    1. Configure Manifest File
      Ensure to include the following service in the AndroidManifest.xml file of your app. This is required to automatically dismiss the notification without launching the app.
    > <service
    >     android:name="com.clevertap.android.sdk.pushnotification.CTNotificationIntentService"
    >     android:exported="false">  
    >     <intent-filter>  
    >         <action android:name="com.clevertap.PUSH_EVENT" />  
    >     </intent-filter>  
    > </service>
    1. Ensure to set one of the CTAs as a Remind Later button.
    2. Set the action ID for the button to remind, from the dashboard.
    3. Ensure the following mandatory template keys are configured for the CTA with Remind Later functionality:
    Template KeyRequiredValue
    pt_input_feedbackRequiredFeedback
    pt_dl1RequiredDeep Link
    pt_event_nameRequiredFor example: Remind Later
    pt_eventproperty<property_name_1>RequiredFor example: <property_value>
    pt_dismiss_on_clickRequiredMust 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_eventproperty<property_name_2>Requiredfixed value - pt_input_reply
    pt_eventproperty<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

    Rating Template

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


    Rating Template

    Rating Template

    Template Variations

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

    • Version-based Rendition- 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 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 Rendition - Notification renders based on whether CTA buttons are included in the payload.

    Vertical Image with CTA Template

    The Vertical Image with CTA template is designed for displaying portrait-oriented creatives without cropping or resizing. It preserves the original layout of vertical assets, making it ideal for campaigns such as product showcases, posters, or reel-style creatives.

    This template ensures that vertical-first designs appear exactly as intended, reducing the need to redesign assets for square or landscape formats. It supports expanded and collapsed views on Android. You can also include additional text fields for richer layouts and an optional CTA button with customizable styles.

    Vertical Image with CTA Template

    Template Keys

    Vertical Image Template KeysRequiredDescription
    Base
    pt_idRequiredMust be pt_vertical_img
    pt_title / wzrk_ntRequiredNotification title
    pt_msg / wzrk_msgRequiredNotification message
    pt_msg_summaryOptionalMessage summary (expanded view)
    pt_subtitleOptionalSubtitle below title
    pt_title_clrOptionalTitle text color (HEX)
    pt_msg_clrOptionalMessage text color (HEX)
    pt_bgOptionalNotification background color (HEX)
    pt_meta_clrOptionalMeta / timestamp color (HEX)
    pt_icoOptionalLarge icon URL
    pt_default_dlOptionalDefault deep link on notification tap
    pt_stickyOptionalKeep notification persistent (true/false)
    pt_dismissOptionalAuto-dismiss after specified time
    Expanded Media
    pt_big_imgRequiredExpanded image URL
    pt_big_img_alt_textOptionalAlt text for expanded image
    pt_gifOptionalExpanded GIF URL (overrides image if provided)
    pt_gif_framesOptionalNumber of GIF frames (default: 10)
    pt_scale_typeOptionalImage scaling type (for example, fit_center, center_crop)
    Expanded Text
    pt_text1OptionalFirst overlay text on expanded image
    pt_text1_clrOptionalColor for first overlay text
    pt_text2OptionalSecond overlay text on expanded image
    pt_text2_clrOptionalColor for second overlay text
    Collapsed Media
    pt_big_img_collapsedOptionalCollapsed image URL
    pt_big_img_collapsed_alt_textOptionalAlt text for collapsed image
    pt_gif_collapsedOptionalCollapsed GIF URL (overrides image if provided)
    pt_gif_frames_collapsedOptionalNumber of collapsed GIF frames
    pt_scale_type_collapsedOptionalScaling type for collapsed image
    Expanded Button
    pt_btn_nameOptionalCTA button label
    pt_btn_dlOptionalCTA button deep link
    pt_btn_styleOptionalStyle: solid, gradient_linear, gradient_radial
    pt_btn_clrOptionalButton background color (HEX)
    pt_btn_border_clrOptionalButton border color (HEX)
    pt_btn_text_clrOptionalButton text color (HEX)
    pt_btn_grad_clr1OptionalGradient start color
    pt_btn_grad_clr2OptionalGradient end color
    pt_btn_border_radiusOptionalCorner radius for button
    pt_btn_border_widthOptionalBorder width
    Collapsed Button
    pt_btn_name_collapsedOptionalCTA label (collapsed)
    pt_btn_id_collapsedOptionalButton identifier
    pt_btn_dl_collapsedOptionalCTA deep link (collapsed)
    pt_btn_style_collapsedOptionalStyle for collapsed CTA
    pt_btn_clr_collapsedOptionalButton background color
    pt_btn_border_clr_collapsedOptionalButton border color
    pt_btn_text_clr_collapsedOptionalButton text color
    pt_btn_grad_clr1_collapsedOptionalGradient start color
    pt_btn_grad_clr2_collapsedOptionalGradient end color
    pt_btn_grad_dir_collapsedOptionalGradient direction in degrees
    pt_btn_border_radiusOptionalCorner radius for button
    pt_btn_border_widthOptionalBorder width
    📘

    Note

    The minimum SDK version required for the Vertical Image with CTA Template is Push Templates SDK v2.4.0.

    Dark Mode

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

    Theme SettingNotification AppearanceSample Output
    Dark mode enabledNotification renders with a dark background
    Dark mode disabledNotification renders with a light background.
    📘

    Custom Color Support

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

    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 TypeDescriptionSample 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 this feature, ensure you are using Push Templates SDK version 2.0.0 and above.

    Image Specifications

    The following table shows image specifications, including both standard aspect ratios and CTA-specific variations. Aspect ratios may differ when Call-to-Action buttons are included in the payload.

    TemplateOS VersionAspect Ratio (Without CTA)Aspect Ratio (With CTA)Max File Size
    StandardAndroid 11 & below5:32:1-
    Android 12+3:22:1-
    AdvancedAndroid 11 & below5:32:1500 KB
    Android 12+3:22:1500 KB
    Auto CarouselAndroid 11 & below5:32:186 KB
    Android 12+3:22:186 KB
    Manual CarouselAndroid 11 & below5:32:186 KB
    Android 12+3:22:186 KB
    Five IconAndroid 11 & below1:1N/A50 KB
    Android 12+1:1N/A50 KB
    Text over ImageAndroid 11 & below2:14:3500 KB
    Android 12+1:14:3500 KB
    TimerAndroid 11 & below5:32:1326 KB
    Android 12+3:22:1326 KB
    RatingAndroid 11 & below5:3N/A500 KB
    Android 12+3:2N/A500 KB
    Product Catalogue (Linear)Android 11 & below2:1N/A86 KB
    Android 12+3:2N/A86 KB
    Product Catalogue (Vertical)Android 11 & below1:1N/A86 KB
    Android 12+3:4N/A86 KB
    Input BoxAndroid 11 & below5:3N/A500 KB
    Android 12+3:2N/A500 KB
    Vertical Image with CTAAndroid 11 & below2:32:3500 KB
    Android 12+2:32:3500 KB

    Image Guidelines

    Ensure images for the following templates meet the specified resolution and file size guidelines:

    Template NameRecommended ResolutionAdditional Guidelines
    Standard Template-No specific guidelines; single image template
    Auto Carousel Template400 x 300 pxFile size per image: 86 KB max
    Manual Carousel Template240 x 180 pxFile size per image: 86 KB max
    Five Icon Template300 x 300 pxSquare aspect ratio (1:1); 5 icons total; file size per icon: 50 KB max
    Product Catalogue Template225 x 225 pxFile size per product: 86 KB max; Vertical variant uses 3:4 aspect ratio (Android 12+)
    Standard Template with GIF240 x 140 px5 frames max; Android 14+ recommended; size limits do not apply to Standard template GIFs
    Text over Image Template-Center-align text within image for Android 12+; no specific guidelines for single image template
    📘

    Note

    • These are recommended aspect ratios and file size limits.
    • Number of lines of text in msg_summary affects how an image renders for a particular aspect ratio. Adjust aspect ratios and layout accordingly based on message length.
    • Resolution limits do not change based on whether the push has CTA buttons or not.
    • Templates other than Auto Carousel, Manual Carousel, and Five Icons do not require specific image resolution guidelines as they use a single image.

    FAQs

    For FAQs, refer to Push Templates FAQs.


    Did this page help you?
    Suggest Edit
    CleverTap Ask AI Widget (CSP-Safe)