Push Templates

Overview

Push templates enable you to craft beautiful notifications within minutes without any coding. Deliver an optimal push experience with rich and personalized notifications that are expressive, exciting, and engaging so that your notifications stand out in the overcrowded notification tray.

MoEngage offers pre-built templates and also allows you to upload custom ones, which are described below. In Step 2 of campaign creation, you can choose a template from either pre-built or custom templates.

Pre-Built Templates

You can create notifications based on the following pre-built templates:

• Basic notification
• Stylized basic notification
• Simple image carousel
• Image banner with text overlay
• Timer
• Timer with Progress bar
• Background Update

1. To get started, you must first integrate with the latest SDK that supports these templates. For more information, refer to the Android and iOS integration docs.
2. Before proceeding, make sure you familiarize yourself with basic push campaign creation.

Use cases

1. Going environment friendly? Send an update with a green background color in your Push notification!
2. Want to bring users back to your app or website? Send out a carousel push notification with images of the product or music, or media last seen by the user.

Create Push Template Notifications

• Push templates are not supported for the Web platform.
• Push templates are supported for all point Push campaign types - One Time, Periodic, Event Triggered, Location Triggered, Device Triggered, and Flows.
• You can select a different template for Android and a different one for iOS.
• You can add different templates for different locales or variations.

To create a template-based Push campaign, select the template of your choice in step 2 of Push campaign creation. The supported platforms for each template are shown below each template tile in the right-side corner.

Android

iOS

Common Push Template Elements

The following elements are common to all the push templates.

Basic Details

The following options are available in the basic details section.

For Android:

Field	Description
Notification Channel	From the drop-down, select the predefined notification channel configured during the integration. This option is available only for Android push notifications.
Message Title	Type or paste the title of the message.
Message	Type or paste the content of the message.
Message Summary	Type or paste a brief description of the message. This option is available only for Android push notifications. Note: The Message Summary text formatting applies only for Android 11 and below versions. For Android 12 and above, only plain text will be displayed.
Image	Do one of the following to an image: Click Image URL and type or paste the URL of the image. Click Upload Image and drag and drop the image or click the upload from the computer the stored image. Note: Images larger than 2–3 MB are not supported. The recommended size is 25 KB to 200 KB. Image scaling behavior Description Basic Android scaling This applies to all basic android notifications. The image is scaled to match the width of the image container, and the height of the notification is adjusted to match the height of the image. For taller images, the image may be center cropped from top and bottom. Fill image container Applicable for all expanded images in all android push templates and the collapsed image in the Image Banner template. Scale the image uniformly (maintain the image’s aspect ratio) so that both dimensions (width and height) of the image will be equal to or larger than the corresponding dimension of the container, such at one dimension is always cropped. Fit inside image container Applicable for all expanded images in all android push templates and collapsed images in the Image Banner template. Scale the image uniformly (maintain the image’s aspect ratio) so that both dimensions (width and height) of the image will be equal to or smaller than the corresponding dimension of the image container such that there is no cropping of the image.
Accessibility Text	Enter a concise, descriptive text that conveys the content or purpose of the image. This text is read aloud by assistive technologies, ensuring visually impaired users understand the image’s content or function. This field is not supported in the simple image carousel template. For more information, refer here.
Default click action	From the drop-down, select one of the following: Navigate to screen: From Take user to a specific screen drop-down, select the screen to which the user needs to navigate. Deeplinking : Type or paste the URL to which the user needs to navigate to. Rich landing : Type or paste the Rich landing page to which the user needs to navigate to.

For iOS:

Field	Description
Message Title	Type or paste the title of the message. Specifies the main heading displayed in the push notification.
Subtitle	An optional secondary line of text that provides additional context for the notification.
Message	Type or paste the content of the message. This depicts the body of the push notification containing the main content.
Allow app to refresh in background	Select this checkbox to allow the app to update its content while running in the background, ensuring users receive the latest information.
Rich Media	You can choose from the dropdown to include an image, audio, or video in the push notification to enhance its visual appeal and engagement.
Image	Do one of the following to an image: Click Image URL and type or paste the URL of the image. Click Upload Image and drag and drop the image or click the upload from the computer the stored image. These fields are visible when you select Image from the Rich Media dropdown. These fields are visible when you select Image from the Rich Mediadropdown. Note: Images larger than 2–3 MB are not supported. The recommended size is 25 KB to 200 KB.
Accessibility Label	Enter a brief, descriptive label that identifies the Image/GIF’s purpose. This label is read aloud by assistive technologies to help users understand and interact with the element. For more information, refer here. This field applies to the Image/GIF option of the Rich Media dropdown.
Accessibility Hint	Enter additional context or guidance that explains the Image/GIF’s action or expected input. This hint is read aloud by assistive technologies to guide users on how to interact with a UI element. For more information, refer here. This field applies to the Image/GIF option of the Rich Media dropdown.
Audio	Enter the direct link to the audio file that will be played within the notification. This field is visible when you select _Audio_from the Rich Mediadropdown.
Video	Enter the direct link to the video file for display in the notification. This field appears when you select Video from the Rich Media dropdown. The link must reference a video file hosted on a CDN; embedded video links (e.g., YouTube) are not supported. While Apple documentation recommends up to 50 MB, smaller file sizes (1–5 MB) improve the chances of successful display.
Default click action	From the drop-down, select one of the following: Navigate to screen : From Take user to a specific screen drop-down, select the screen to which the user needs to navigate. Deeplinking: Type or paste the URL to which the user needs to navigate to. Rich landing : Type or paste the Rich landing page to which the user needs to navigate to.

Buttons

Click Buttons to add the buttons to the notification. Follow these steps to add buttons to the Android message:

1. Click Add Button

2. Type the name of the button in the Button Name.

3. From the Click action drop-down, select one of the following:

   Drop-down list	Action
   Navigate to screen	From the Take user to a specific screen drop-down, select the screen to which the user needs to navigate.
   Deeplinking	Type or paste the URL to which the user needs to navigate to.
   Rich landing	Type or paste the Rich landing page to which the user needs to navigate to.
   Call	Type or paste the phone number to which the user needs to call.
   Share	Type or paste the text to be shared with the user.
   Copy	Type or paste the text to be copied with the user.
   Set user attribute	Select the user attribute from the drop-down. Type or paste the value for the user attribute.
   Track event	Type or paste the name of the event. Type or paste the value for the event.
   Custom action	Type or paste the custom actions.
   Snooze	Type or click the up and down arrow to select the number of hours the notification is snoozed.
   Remind later	Remind today in Type or click the up and down arrow to select the number of hours in which the notification will be displayed again today. Remind tomorrow in Type or click the up and down arrow to select the number of hours in which the notification will be displayed again tomorrow.

   For more information, refer to Notification Actions.

4. Click New KV Pair

5. In Key value pairs, enter the key and value.

6. Repeat steps 1 to 5 to add more buttons.

7. Click Advanced and follow the steps.

For iOS, you need to configure the Actionable Notifications, For more info, see here.
After you define a category, you can use the MoEngage dashboard to send notifications to the users by following the below-mentioned steps:

1. On the iOS push template, expand the Buttonssection.

2. Click the dropdown and select the preferred category from the list.
   As you can see in the example, Accept, Decline, and May Be actions are grouped into a category, i.e.,“INVITE_CATEGORY”.

   

Advanced

The following advanced options are available for all templates. For Android:

Field	Action
Coupon code	Type or paste the coupon code.
Use large icon in notification (Android)	Use App icon : Click to select the app icon as the icon for the message. Upload image : Type or paste the URL to which the user needs to navigate to. Enter URL : Type or paste the URL of the large icon.
Make notifications sticky	Enable this toggle to ensure the notifications are not dismissed by swiping or by clicking. Once this toggle is enabled, you can specify the button name for the dismiss notification in the Dismiss button text field. Note: Adding Dismiss button text is available only from Android 12 and above. Sticky notifications are available for all templates except the Basic notification template. On a device with Android 14 or higher, the user can dismiss sticky notifications by the swipe action. The notification will remain in the tray if the user performs the Clear all notification action (which helps with accidental dismissals) and the notifications are still dismissible when the phone is locked. Refer to Android 14 documentation here.
Accessibility text (for Android 11 and below)	Add a concise, descriptive text that communicates the ( ) icon’s function, such as Dismiss notification. This text is read aloud by assistive technologies, helping users understand and interact with the icon. For more information, refer here.
Group Key	Enter the group key. This helps identify and categorize related push notifications. Ensure you use the same group key for all push notifications you want to group. For more information, refer here.
Update Key	Enter the update key. This update key helps identify and update related push notifications. Ensure you use the same update key for all push notifications intended to update each other. For more information, refer here.

For iOS:

Field	Action
Coupon code	Type or paste the coupon code.
Sound	Enter the sound file name that will be played when the push notification is delivered to the user’s device. To know how to define custom sound in iOS, see here.
Badge	Select this checkbox to display a badge count on the app icon when a notification is received.
Group Key	Enter the group key. This helps identify and categorize related push notifications. Ensure you use the same group key for all push notifications you want to group. For more information, refer here.
Update Key	Enter the update key. This update key helps identify and update related push notifications. Ensure you use the same update key for all push notifications intended to update each other. For more information, refer here.

Click Next to move to the next step of the Push Notification campaign.

Template Backup

• Backup notifications are displayed initially, followed by an update with template content, except for direct posting in head’s-up notifications. For more information, refer here.
• Core message delivery remains unaffected by asset download or notification update failures. Users always receive the backup text.
• Devices with Android SDK versions below 10.3.00 or iOS versions below 6.2.0 only display the backup text and not the template.
• To leverage the template backup feature, ensure your devices are integrated with the Push template. For more information, refer to the integration guides for Android and iOS.

This option is available for all templates except the Basic notification. The following options are available:

1. You can only configure the fields present in the basic section of the templates. Refer to Common push template elements to configure the Template Backup section.
2. You can copy the backup data from the template section using the Copy template data to backup or add new content.

Previews

You can preview how the notification would get rendered on the user’s device in the Preview section.

Preview Types -The preview type toggle at the bottom of the preview section has the following options:

1. Default - This option shows you the default preview without any personalization.
2. Personalized - This option shows the preview as it would be shown for the user selected. For example, if you have added personalization attributes, they would be fetched for the user selected and displayed in the preview. For example, if you have added the user’s first name in the notification, the first name for the user selected in the personalization preview would be fetched (if the value is not available for the specified user, the fallback chosen would be used. If fallbacks are not specified, the preview will not be shown).

Preview Options - The following preview options are available for previews:

1. For iOS and Android 11 and below
   This section shows the previews for devices that have Android versions 11 and below. There are four preview options here:

   • Dark Mode
   • Light Mode
   • Expand
   • Collapse

   For Android 11 and below:

   

   For iOS:

   

2. Android 12 and above This section shows the previews for devices that have Android versions 12 and above. With Android 12, the notification may appear differently on different devices depending on the OEM and the device’s size. The following options provide you with a glimpse of how the previews would look on various devices and OEMs.

• Min - This preview shows how the notification would be rendered for devices with narrow screen width (360dp width viewport) and follow the Google Pixel design guidelines. Example: Asus Zenfone 9
• Std A- This preview shows how the notification would be rendered for devices with more horizontal whitespace applied on devices with the most common width and follow the Mi Guidelines. Example: Xiaomi Redmi Note 10 Pro
• Std B -This preview shows how the notification would be rendered for devices with the lesser horizontal whitespace applied on devices with the most common width and follow the Mi Guidelines. Example: OnePlus 11R 5G
• Max - This preview shows how the notification would be rendered for devices with large screen width (450dp width viewport or higher - including tablet screens) and follow the Oppo/Vivo guidelines. Example: Oppo pad Air

Min	Std A	Std B	Max

The common push template elements do not apply to the Background Update template.

Push Template Types

Basic notification

To create a default or native Push notification, select the Basic notification template and create the notification as described in Common push template elements.

You can add GIFs to the Basic notification template by following ways:

Select this checkbox to upload a GIF. The GIF with image fallback section open, do one of the following to add a GIF: Click GIF URL and type or paste the URL of the GIF. Click Upload GIF, and drag and drop the GIF or click the upload from the computer to the stored GIF file. Note: Ensure the device runs Android 14 or later to access this feature. For more information, refer here .
Enter descriptive text that conveys the added GIF’s visual narrative and purpose, offering an equivalent experience for users relying on assistive technologies. For more information, refer here .
Do one of the following to add an image or GIF: Click Image/GIF URL and type or paste the URL of the image/GIF. Click Upload Image/GIF and drag and drop the image/GIF or click the upload from the computer the stored image/GIF. These fields are visible when you select Image/GIF from the Rich Media dropdown. Note: The recommended size is 25 KB to 200 KB, and for GIFs, it is up to 500 KB. For more information, refer here .

Android

Expanded

Android 14 & above	Android 12 & 13	Android 11 & below

Collapse

iOS

Expanded\

Collapse

Stylized basic

Create push notifications with background color, text color, and text formatting, and make your notification stand out in the notification tray.

The stylized basic notification is created using SDK custom layout. In non-whitelisted devices, the notification created by stylized basic notification appears with 64dp height. Follow these steps:

Basic details

1. In the Background color, select the message background color.
2. In-App name color(Android only), select the color of the app’s name.
3. In the Notification control color(Android only), click Light or Dark to control the notification’s color.
4. Turn on the Apply background color in text editor toggle to apply the chosen background color to the text editor fields -Title, Message, and Summary. This should help you with visibility when using the lighter-colored font.
5. Follow the steps described in Common push template elements.
6. Make sure to check the preview in both light and dark modes to ensure that the notification looks good and is readable in both modes.
7. In Image section, for iOS:
   • Select Image/GIF URL and type or paste the URL of the image/GIF.
   • Click Upload Image/GIF and drag and drop the image/GIF or click the upload from the computer the stored image/GIF. The recommended size is 25 KB to 200 KB, and for GIFs, it is up to 500 KB. For more information, refer here.

Advanced

1. Follow the steps described in Common Push template elements.
2. Enable Auto Dismiss Notification by turning on the Auto-dismiss notification toggle. You can select the time duration after which the notification will automatically be removed from the user’s notification tray after the push notification is delivered to the user. The time duration can be chosen in minutes, hours, and days. The maximum value allowed is 1 day. This is only applicable to Android devices.

Android

Expanded

Collapsed

iOS

Expanded

Collapsed

Simple image carousel

A carousel or slide show consisting of two to five images is created using this template. Some important features of the image carousel:

• The image slide show can be set to auto-play oron-demand.
• The images can be personalized.

To create a carousel template, do the following:

1. Follow the steps described in the Stylised Basic Notification.

2. In Simple Carousel Content, do the following:

   Field	Description
   Slider transition	Click Manual to make the transition between images by clicking on the image. OR Click Automatic to make the transition between images automatically. Only supported up to Android 10. For Android 11 and higher, slider transition will always be manual irrespective of the option selected
   Image	Do one of the following: Click Image URL and type or paste the URL of the image. Click Upload Image and drag and drop the image or click the upload from the computer the stored image. Image Scaling Options: Select Crop image to see a center-cropped image on the device and in the preview. Select Fit to container to center the image inside the container. Note: Image Scaling is available only for Android 12 and above.
   Image click action	From the drop-down, select one of the following: Navigate to screen: From the Take user to a specific screen drop-down, select the screen to which the user needs to navigate. Deeplinking :Type or paste the URL to which the user needs to navigate to. Rich landing: Type or paste the Rich landing page to which the user needs to navigate to.
   Default click action	From the drop-down, select one of the following: Navigate to screen : From the Take user to a specific screen drop-down, select the screen to which the user needs to navigate. Deeplinking: Type or paste the URL to which the user needs to navigate to. Rich landing: Type or paste the Rich landing page to which the user needs to navigate to.
   KV Pair	Follow these steps to create a Simple Image banner and Text overlay on the image push template: Click New KV Pair In Key value pairs, enter the key and value.

3. Click Advanced and follow the described steps in Advanced.

4. Click Template backup and follow the described steps in Template Backup.

Android

Expanded

Collapsed

iOS

Expanded

Collapsed

Image banner with text overlay

Create push notifications with a large banner image covering the entire notification area and overlay text on top of the image with the Image Banner with Text Overlay template. Such templates can be used for adding the brand’s logo and colors to the notification being sent.

Ensure that you have integrated the MoEngage Android SDK. For more information, refer to Android SDK.

To create a Text overlay on Image notification, follow these steps:

1. In step 2 of Push campaign creation, select template type as Image banner with text overlay notification.
2. Fill in the following fields described in the Common push template elements section:
3. Notification Channel
4. Message
5. Title Message
6. Default Click Action
7. Turn on the Include App name and time toggle to include the app name and time in the notification.
8. Select the color name for the App name using App name color. You can also choose the ‘system default’ for the App name color.
9. Select either the ‘Light’ or ‘Dark’ mode in the Notification controls color toggle.
10. To add a banner image to the notification, do the following:
11. Click on the ‘Image URL’ option to type or paste the URL of the image.
12. The image URL can also be personalized by typing ’@’ in the field. This will invoke the personalization UI and
13. Click on the ‘Upload Image’ option to drag and drop the image or click the upload from the computer to upload a stored image. The recommended image size is around 25 KB, and the recommended aspect ratio is 2:1 (width: height).
14. Collapsed Push Notification: Select one of the following to choose the image to be displayed when the push notification is collapsed.
15. Keep same as template backup: In the collapsed mode, the text would remain the same as the template backup’s message. Only the text would be shown here, and the image wouldn’t be shown.
16. Show collapsed image: This option allows you to add a separate image to be displayed when the notification is collapsed. When this option is chosen, you can also scale the image.
    • Image Scaling Options: Select Crop image to see a center-cropped image on the device and in the preview. Select Fit to container to center the image inside the container. Note: Image Scaling is available only for Android 12 and above.

Expanded

Collapsed

Timer

Create push notifications with a timer and a message. Such notifications can be used to display the countdown for flash sales or sales/offers that are time bound. Marketers employ these options for higher customer engagement.

1. Ensure that you have integrated the MoEngage Android SDK.
2. Ensure that you have integrated the Push templates SDK 4.0.0 version.
3. For more information, refer to Android SDK.

To create a Timer with message notifications, follow these steps:

1. In step 2 of Push campaign creation, select template type as Timer.
2. Add information to the fields present in the Basic details, buttons, and advanced as mentioned in the common push template elements section above.
3. In the Timer section, you can configure how long the notification will be displayed on the user’s device. For example, if the duration is set as 4 hours in the timer section, the notification will be displayed for four hours from when the notification gets sent successfully to the user’s device. At the end of four hours, the notification will be dismissed automatically.
4. Select the timer duration using the ‘Timer ends at’ field.

Duration

Duration

Enter the time duration for which the notification will be displayed to the user.

Personalization

Select the ‘Personalise value’ toggle to enable personalization as shown below. The personalized value should be entered should be in minutes.

For example, to display the timer for one hour, enter 60. The maximum duration is 12 hours and the minimum is 15 minutes.

You can also choose any User Attribute, Content Block or Product Set, or Content API by typing ’@’ and invoking the personalization UI. Click here for more information on the personalization of push notifications.

At a specific Time in User timezone

At a specific Time in User timezone

Enter the specific time at which the timer will end. This time will be calculated based on the user’s time zone and the countdown timer will end at the occurrence of the specified time in the next 24 hours of sending the notification.

For example, if this value is set at 10:30 AM for the user’s timezone and the notification reaches the user at 10 AM, the timer will end at 10:30 AM and the user won’t see the notification post that time.

Note: Since this notification is dependent on the user’s time zone, in case the notification is scheduled or triggered at 11 AM today and the timer has been set for 10:30 AM in the user’s timezone, the notification will be scheduled to end at 10:30 AM the next day. However, this exceeds the 12-hour limit for the expiry of timer notifications and thus, this notification will not be delivered.

Personalization

Select the ‘Personalise value’ toggle to enable personalization as shown below. The personalized value should be in the 12 hours format without the time zone. For example, 11:30 AM or 4:00 PM.

You can also choose any user attribute, content block or product set, or content API by typing ’@’ and invoking the personalization UI. Click here for more information on the personalization of push notifications.

At a Specific Time in Campaign timezone

At a Specific Time in Campaign timezone

This is similar to the user zone field only the timezone in consideration would be the campaign’s timezone rather than the user’s timezone. Enter the specific time at which the timer will end. This time will be calculated based on the campaign’s time zone and the countdown timer will end at the occurrence of the specified time in the next 24 hours of sending the notification. Thus, this notification will end at the same time for all the users in the campaign irrespective of their timezone.

Personalization

Select the ‘Personalise value’ toggle to enable personalization as shown below. The personalized value should be in the 12 hours format without the time zone. For example, 11:30 AM or 4:00 PM.

Note: The minimum value that can be added here is 15 minutes, and the maximum value is 12 hours.

Duration At a specific Time in User timezone At a Specific Time in Campaign timezone

5. Select the Timer Text Colorusing the ‘Select color’ option, as shown below. There is the option to choose the ‘System default’, too, if you do not wish to customize the color for the timers.

Expanded

Collapsed

Timer with progress bar

• Ensure that you have integrated the MoEngage Android SDK.
• Ensure that you have integrated the Push templates SDK 4.0.0 version.
  For more information, refer to Android SDK.
• Schedule Exact Alarm Permissions
  The SDK uses Alarms to periodically update the progress in the progress bar. Starting Android 12, additional permission is required to use exact alarms. To set the required permission, refer to the Push templates developer documentation.
  If the application does not have the permission above, the Timer with a Progress Bar template will not be shown to the user; instead, a backup template will be displayed to the user which will have the Timer but not the progress bar.

The Timer with the progress bar template is similar to the timer with the message template. An additional progress bar is displayed in the case of a timer with the progress bar as shown below. Refer to the Timer section above for details about the other sections.

The same Progress bar color would be applied to all Timer with Progress Bar campaigns for an app. Different colors can be set based on light/dark mode by setting the attribute values invalues.xmlfor light mode andvalues-night.xmlfor dark mode on the rich push SDK.

The Progress bar’s progress that indicates may not be in sync with the actual time. Check out our FAQs for more information.

Expanded

Collapsed

Background Update

The Background Update template allows you to deliver custom data payloads directly to your application without displaying a visible notification to the user. This is ideal for background synchronization, app state management, and triggering a silent application logic. This template is supported on Android and iOS only. It is not available for Web platforms.

• Ensure your application is integrated with the MoEngage SDK version 14.06.00 (Android), 1.5.0 (BOM), and 10.10.0 (iOS).
• Enable the Remote notifications background mode in your Xcode project on the Signing & Capabilities tab.
• For detailed integration steps, refer to the Android SDK and iOS SDK.

Create a Background Update Notification

In Step 2 of your push campaign creation, select the Background Update tile.

1. The primary input for this template is a Key-Value (KV) Pair interface. These pairs are sent at the root level of the push payload. The backend handles value serialization differently depending on the target OS:
   • Android: To comply with FCM Data Message standards, the backend stringifies all values (numbers, booleans, and objects).
   • iOS: Valid JSON strings entered in the value field are sent as proper JSON objects. Non-valid JSON is sent as a string.
2. Unlike standard push notifications, the Background Update template is designed to be silent. The delivery mechanism adapts to each operating system’s background processing requirements:
   • On Android: The payload is delivered as a high-priority Data Message. The MoEngage SDK intercepts this and passes the raw data to your app without showing a notification in the tray.
   • On iOS: MoEngage uses the content-available flag to wake your app in the background for up to 30 seconds. This allows your app to refresh content or sync data without alerting the user.
     In both cases, your developers must implement a specific SDK callback to “listen” for these payloads and trigger the desired app logic.

• To avoid conflicts with SDK functionality, MoEngage restricts keys starting with MO, gcm, aps, or apns, and you cannot use them as custom keys.
• Most SDK technologies require Boolean keywords to be lowercase (for example, true). While standard JSON payloads usually handle this correctly, issues can arise when using Personalization or conditional logic, as these values are delivered as strings.
  • The Risk: If a personalized attribute returns a string like “True” (capitalized), your app logic may not recognize it as a boolean, leading to false negatives.
  • Recommended Action: If a developer knows a certain key is expected to be a boolean, they should add a code-level check to convert the string to lowercase (for example, convert “True” to “true”) before executing business logic.

In Step 3 of your push campaign creation, a new targeting option, Background Update Targeting is available in the Advanced section. This option appears only if the Background Update template is selected for all platforms, locales, and variants. For more information, refer to Create Push Campaigns.

Analytics and Info

Analytics

• Metrics such as Sent and Delivered are tracked normally.
• Because there is no system UI, Impressions and Clicks are not automatically recorded.
• If the background update triggers a custom local notification or a UI change, developers must manually call the trackPushClick SDK method to attribute those interactions to the campaign.

Campaign Info

After you publish a campaign, you can verify your configuration on the Campaign Info tab.

• All configured keys and values are displayed in a read-only format.
• If a value was entered as a valid JSON object, it will be displayed as a formatted JSON block for easier readability.
• Use the preview panel to visualize the final JSON structure as it appears to the device, including system-injected tracking keys.

Sample Payloads

The following examples illustrate how the MoEngage backend structures the final delivery payload. Note that any custom keys added via the Background Update template are appended to the root level of the payload, co-existing alongside standard MoEngage metadata.

1. String Value

   key1: User1
   

2. Valid JSON Object

   JSON

   key2: {
   "k1": "v1"(string),
   "k2": true/false(boolean),
   "k3": 200(number)
   }
   

3. Non-Valid JSON

   JSON

   key2: {
   "k1": User,
   "k2": True,
   "k3": 200
   

   • iOS Output

     JSON

     {
     "Key1ios": 200,
     "k2ios": true,
     "k3ios": "Praxxxn",
     "k4ios": "{\\n\\"k1\\": User,\\n\\"k2\\": True,\\n\\"k3\\": 200"
     }
     
     • Ensure your input is a valid JSON, because the backend treats invalid JSON inputs as malformed strings. If your input is not a valid JSON, your integration must include the logic to handle non-structured string data.
     • In the above output, the non-valid JSON is treated as a malformed string: "k4ios": "{\\n\\"k1\\": User,\\n\\"k2\\": True,\\n\\"k3\\": 200"

   • Android Output

     JSON

     {
     "message": {
     "data": {
     "Key1Android": "200",
     "k2android": "true",
     "k3android": "Praxxxn",
     "k4android": "{\n\"k1\": User,\n\"k2\": True/False,\n\"k3\": 200"
     }
     }
     

Recommendations

Here are some of the important guidelines to be followed while using push templates:

• Check the preview in both light and dark modes when you apply a background color or text color. This will ensure that your notification looks proper in both device modes.
• Check the preview in both collapsed and expanded modes using the button, present on the left side of the device preview in the dashboard.
• For the carousel, make use of the play/pause buttons present at the bottom of the device to check the transitions.
• Use the SDK method setNotificationColor() to add color to the small icon present on the top left of the Push notification. However, the same color will be applied to the icon in basic Push notifications as well.
• Create images such that the content is center aligned. This would ensure that the main content isn’t truncated, even if some cropping is happening around the margins.

####Things to Note

• Push Amp+ is not supported via Templates. This means that the devices targeted via Push Amp+ will receive a notification. However, these notifications will be simple Push containing backup data & not the template data.
• Due to templates data, if payload size exceeds 4kB, the only backup payload will be sent so delivery will not be impacted.
• In iOS, the system doesn’t allow showing custom formatting in collapsed view. Hence in a collapsed view, the notification will look like a basic notification with simple text and image. However, when opened in expanded mode, the custom view of the templates will be shown with the text/color formatting applied.
• Strikethrough is not supported on Android 7 or lower versions.
• You can personalize your templates the same way as Basic push notifications.
• The automatic carousel is not supported on Android 11 and above due to system limitations. If you configure an auto carousel, it will be rendered with the manual transition.
• Due to battery optimization done by the Android OS and the OEM, auto-dismissed sometimes may not be triggered or be triggered with a delay.

For more information about rendering issues associated with Push templates, refer to Rendering issues associated with Push templates in Android.

Custom Templates

Custom templates are uploaded to MoEngage using the Push Custom Template API. For more information, refer to Push Template API. This option helps you have a pre-defined set of templates that are created outside the MoEngage ecosystem. You can reuse these templates, preview them on the dashboard and use them for sending campaigns to your customers.

You can do the following in the custom templates section:

1. Select a template - Click on a template to select it.
2. Sort templates - Click the icon to sort the templates in ascending or descending order of the last modified time of the template.
3. Search templates- Type the template name in the search box to the top right corner of the custom templates section to search for a specific template.
4. Preview a template - You can preview a template by hovering over it and clicking the icon that appears, as shown below.

Once you select a custom template, it will be loaded in the UI with details of all the fields in the template. You will be able to view the fields but only edit them if you have the ‘Edit Templates’ permission.

• Any user with the following roles will be able to edit the templates: Default Admin, Manager, and Marketer.
• To enable edit access for other users, they need to be given the ‘Edit Templates’ permission.
• Custom templates do not apply to Background Update template.

You can see a preview of how the template will look once you send the campaign to your users. You can also test the campaign using the Test Campaign option to see a real-time preview of how it will look on a specific device.

Frequently Asked Questions

What are the changes specific to Android 14 with Push templates?

With Android 14, Android has introduced changes that affect Push templates:

• Timer with Progress Bar template
  The SDK uses Alarms to periodically update the progress in the progress bar. Starting Android 14, the Alarm permission is off by default. So you need to ask for explicit Alarm permission if you want to show Timer notifications apart from adding a line in your manifest file. For more information, refer to Push Templates.
  If the application does not have the permission above, the Timer with Progress Bar template will not be shown to the user; instead, a backup template will be displayed to the user which will have the Timer but not the progress bar.
• Sticky notifications
  On a device with Android 14 or higher, the user can dismiss sticky notifications by the swipe action. The notification will remain in the tray if the user performs the Clear all notification action (which helps with accidental dismissals) and the notifications are still dismissible when the phone is locked. Refer to Android 14 documentation here.

Why is automatic copy backup not working on clicking the Next button?

Verify the following:

1. All the backups in all variants are empty.
2. All the mandatory fields are filled.
3. The backup is not filled.

Why is Auto copy backup not working after copying content?

Copy Content copies the Default Click Action Type (dropdown) in iOS. Because of this Backup is not empty anymore, which prevents Auto Copy Backup. Remove the Default CTA type in iOS backups to enable auto-copy backup.

Why are errors not displayed in Carousel Slides?

1. Errors start displaying only after you try to switch between the pages or try to do a test notification
2. Error is also displayed in the slide when you open the slide’s tab.

Why Carousel Slides having errors are not opening?

1. Error for the carousel slide is displayed in the toaster along with the name of the slide that has the error.
2. The sliding tab which has an error will not be automatically opened at the moment. (Some tech challenges in that implementation).

How to add Fallback for Personalization?

• Both Template and Backup have an inline fallback for Personalization
• While adding the personalization attribute, you can select the ‘replace text’ option to add an inline Fallback
• To add the fallback, use the following Jinja template:

Sample personalization with Fallback:

• Example: first name user attribute
• Template message: ‘Hi John, Welcome to MoEngage. To proceed further, click here.’
• Fallback message: ‘Good Morning. To proceed further, click here.’

Sample

{% set firstName = {{UserAttribute['First Name']}} %}
{% if firstName %}Hi {{ firstName }}, Welcome to MoEngage
{% else %}Good Morning
To proceed further, click here
{% endif %}

Unable to add multiple lines in the Title and Summary field in Templates

Title and Summary are single-line inputs only.

Why is there a lag in my progress bar's time?

Battery optimization could be running, and this could cause issues in updating the progress bar.

What is the ideal aspect ratio for images?

Due to the changes in Android 12, there are varying UI specifications for different OEMs, resulting in differences in how images are displayed on Android devices. The appearance of an image may vary depending on the device-width and the device OEM. The ideal aspect ratio for push notifications is detailed below.

Ideal Aspect Ratio for Images

For Android

Type A Devices

Pixel, Xiaomi, and Asus phones are classified as Type A devices. The ideal aspect ratio for images is detailed in the following table for various push templates.

Template Type	Screen Size	Ideal Image Size/Aspect Ratio
Stylized basic, Carousel, Timer (With button present in the Push Template)	Small width screens	2.33
	Most common screen size	2.85
	Large screens, Tables, Foldables	3.11
Stylized basic, Carousel, Timer (Without button present in the Push Template)	Small width screens	1.77
	Most common screen size	2.17
	Large screens, Tables, Foldables	2.37
Timer with progress bar (With button present in the Push Template)	Small width screens	2.00
	Most common screen size	2.45
	Large screens, Tables, Foldables	2.67
Timer with progress bar (Without button present in the Push Template)	Small width screens	1.58
	Most common screen size	1.93
	Large screens, Tables, Foldables	2.11
Image banner (With button present in the Push Template)	Small width screens	1.26
	Most common screen size	1.55
	Large screens, Tables, Foldables	1.69
Image banner (Without button present in the Push Template)	Small width screens	1.06
	Most common screen size	1.3
	Large screens, Tables, Foldables	1.42

Type B Devices

Template Type	Screen Size	Ideal Image Size/Aspect Ratio
Stylized basic, Carousel, Timer (With button present in the Push Template)	Small width screens	2.61
	Most common screen size	3.13
	Large screens, Tables, Foldables	3.39
Stylized basic, Carousel, Timer (Without button present in the Push Template)	Small width screens	2.24
	Most common screen size	2.69
	Large screens, Tables, Foldables	2.91
Timer with progress bar (With button present in the Push Template)	Small width screens	1.42
	Most common screen size	1.7
	Large screens, Tables, Foldables	1.84
Timer with progress bar (Without button present in the Push Template)	Small width screens	1.99
	Most common screen size	2.38
	Large screens, Tables, Foldables	2.58
Image banner (With button present in the Push Template)	Small width screens	1.76
	Most common screen size	2.12
	Large screens, Tables, Foldables	2.29
Image banner (Without button present in the Push Template)	Small width screens	1.19
	Most common screen size	1.43
	Large screens, Tables, Foldables	1.55

Samsung, OnePlus, Oppo, Vivo, Realme, and other phones are classified as Type B devices. The ideal aspect ratio for images is detailed in the following table for various push templates.

For iOS: It is recommended to use 2:1 (landscape orientation) for Images. iOS automatically scales the notification area to fit the image aspect ratio.

How can I ensure my Push Notification images display correctly across different devices without being cropped?

Since creating multiple images for different devices is not possible, MoEngage recommends adopting the following image scaling approaches to ensure that your Push Notifications appear consistent across various devices.

1. When your creatives should not be cropped

   Create your Push Notification by following the aspect ratio specified for Device Type A with the most common screen size. Use the Fit inside image container in the Image scaling section during template creation to ensure that your creative is not cropped. You may see white spaces horizontally or vertically.

   

2. When your creative does not have meaningful content in the extremities (10% margin from each side)

   Use the Fill image container option in the Image scaling section during template creation and add a margin to your image. This will ensure that even in extreme cases, your meaningful content will never be cropped, even if you see some margin cropping.