Template Options for Push Notifications

This document describes configuration options for push notification templates.

# Table of contents

# Creating and editing templates

To learn how to create, edit, clone, preview, and delete templates, read Introduction to Templates.

# Simple Mode

Use the following options to configure a push notification template:

# Template Name

Set a Template Name to provide a name for your template, which can be useful for locating it when creating new campaigns.

# Message Type

Select a Message Type to categorize your message by channel and type. For more information, read Message Channels and Message Types.

# Title

The title text to display at the top of the push notification.

# Push Message

The text to display in the body of the push notification.

# Push Open Action

The action to take when a user taps the push notification:

• Open App - Opens the app associated with the push notification.

• Open URL - Passes the specified URL to the URL handler of the associated mobile app. This URL can deep link to specific content in the app or point to external content to open in a web browser.

# Rich Push

An image or video and action button to associate with the push notification (Android push notifications do not support video). Action buttons sit below push notifications and allow users to take immediate action. Use them to encourage users to make a purchase, write a review, visit a website, share content on social media, unsubscribe from a list or take some other relevant action.

• Rich Media URL - The URL of the image to video to display with the push notification.

• Button Text - The text of the button to display with the push notification.

• Button Press Action - The action to trigger when a user taps the push notification's button:

  • Open App - Opens the app associated with the push notification.

  • Open URL - Passes the specified URL to the URL handler of the associated mobile app. This URL can deep link to specific content in the app or point to external content to open in a web browser. When you select this option, the template editor prompts you to specify a URL.

# Expert Mode

Turn on Expert Mode to enable the options described in the following sections.

# Action buttons

Action buttons sit below push notifications and allow users to take immediate action. Use them to encourage users to make a purchase, write a review, visit a website, share content on social media, unsubscribe from a list or take some other relevant action. Here are some example action buttons on iOS and Android:

• Button Text - The text to display on the button. For example, Buy now!.

• Identifier - A value to include on the track push open event sent from the mobile app to Iterable after the user taps the button. Useful for segmenting on users that have tapped a particular push notification button.

• Button Type (drop-down menu) - The button's type impacts its appearance and the actions available to it. Iterable provides three action button types:

  • Normal Button - A button with black text.

  • Destructive Button - A button with red text.

  • Text Input Button - A button that displays a text input after being tapped. For this type of button, Iterable provides the following options:

    • Placeholder - Placeholder text for the push notification's text input.

    • Submit Button Text - Text to use on the input's submit button.

• Button Action - The action to trigger when tapping on the button. There are four types of button actions:

  • Open App - Opens the app associated with the push notification.

  • Open URL - Opens an external URL or a deep link to content within the app.

  • Custom Action - Passes the specified value to the application's custom action handler (defined in the app's code). Decide in advance with your team's mobile engineers on a list of supported custom actions and what they should do.

    • The Open App option nested under Custom Action causes the app to come to the foreground to execute the action. Unchecking this option executes the action in the background.

    • Track Only - Sends Iterable a track push open event with the associated button identifier, without opening the app or redirecting the user. This option is useful for buttons that dismiss push notifications. This button action is available for destructive buttons and text input buttons.

# iOS-only settings

• Rich Media URL - The URL of an image, video, audio file or animated GIF to display with the push notification. Iterable validates the URL to make sure it can be rendered.

  NOTES

  • In the push notification preview, expand an image by clicking on it.
  • To include images, videos or action buttons with iOS push notifications, have your mobile engineers add a Notification Service Extension to your iOS application. For more information, read about Advanced iOS Push Notifications

• Wake App - On the push notification's arrival, this option causes the app to wake up in the background to perform a background update. Unchecking this option ensures that the user doesn't wake the application and cause it to ping your system's servers.

• Interruption level - (Only affects users running iOS 15 and higher.) Specifies how and when Iterable should alert users about the incoming push notification. There are four options:

  • Passive - Don't alert the user. Deliver the notification silently to the Notification Center, without playing a sound/vibration or lighting up the screen. Do not override a scheduled delivery (Notification Summary), break through a Focus, or override the ring/silent switch.

  • Active (default) - Alert the user about the push notification, playing a sound/vibration and lighting up the screen as allowed by device settings. Don't override a scheduled delivery (Notification Summary), break through a Focus, or override the ring/silent switch.

  • Time Sensitive - Alert the user about the push notification, playing a sound/vibration and lighting up the screen as allowed by device settings. Also, since the message is urgent, override a scheduled delivery (Notification Summary) and break through a Focus if needed (unless the user has blocked the app from doing so).

    IMPORTANT

    • Before you can send Time Sensitive notifications, your engineering team will need to add the Time Sensitive Notifications capability to your app in Xcode, and then release a new version.
    • Be careful with this option, since users can block your app from sending Time Sensitive notifications if they decide you are misusing them.

  • Critical - Highly invasive. Only for urgent messages related to personal health and public safety. Play a sound and vibration, regardless of system settings and the ringer switch. This option is disabled by default, since it requires a special entitlement from Apple. If you need to use it, talk to your Iterable customer success manager

  For more information about interruption levels, read the Notifications section of Apple's Human Interface Guidelines.

• Relevance score - (Only affects users running iOS 15 and higher.) Relevance scores help iOS determine which of your push notifications to display when featuring your app in a Notification Summary:

  • When iOS features your app in a Notification Summary, it displays the push notification (for your app) with the highest relevance score.

  • Otherwise, the relevance score determines how iOS sorts your app's push notifications in the non-featured section of the Notification Summary (push notifications with higher relevance scores sort to the top).

  If you don't select a relevance score, it's equivalent to choosing the lowest possible relevance score (0.0).

# Android-only settings

Rich Media URL - The URL of a hosted image. Iterable validates the URL to make sure it can be rendered. Google recommends using an aspect ratio of 2:1 for rich media push messages.

# Advanced Options

• Custom Sound - The name of the sound file to play when the push notification arrives. For the sound file to play, your mobile engineers must bundle it in your mobile application. For more information, read the following Setting Up iOS Push Notifications and Setting up Android Push Notifications.

• Enable Template Generation Using Data Feeds - Data feeds query external web services at send time, providing the results to Iterable so it can customize the messages sent by a campaign. This option enables data feeds in the push notification template. For more information about using data feeds in Iterable, read Personalizing Templates with Data Feeds.

  Selecting this option causes a few other data feed-related options to appear:

  • Cache Data Feed Response... - This option causes Iterable to cache responses to the data feeds referenced by the template (to reduce load on the servers that host them). For each recipient, Iterable determines the data feed URL to query by substituting parameters from their Iterable profile into the data feed's pre-defined URL. If Iterable has a cached response for that URL from within the past hour, it will use that data. Otherwise, it will query the URL.

  • Merge the Data Feed and User Contexts - Allows the template to reference data feed data with double curly braces ({{productName}}) instead of double square brackets ([[productName]]). Doubly curly braces can still be used to reference user profile data, too. If the same field exists on both the user profile and the data feed, Iterable uses the value from the user profile. With this option enabled, a merge parameter can prefer user profile data but otherwise revert to data feed data.

  • Use Data Feed Alias - Allows the template's content to reference data feeds by their aliases. Using aliases can make templates easier to read and maintain, especially when they reference multiple data feeds. To learn how to define data feed aliases, read Editing a data feed's alias. To learn how to use data feed aliases to reference data, read Using aliases to reference data feed data.

# Custom Metadata

Custom metadata is additional JSON data to send along with the push notification. When the push notification arrives, this data is available for your apps to process.

Custom metadata can be used to control the state of your application. For example, a push notification that congratulates a user on reaching a VIP status of some sort might also include custom metadata that tells the app about this status. The app might use this information to change its styling or to unlock additional functionality.

# Deprecated push notification fields

Iterable has deprecated the following fields, which are no longer available for new templates:

• iOS Deep Link
• Android Deep Link
• iOS Category

Instead, use the Rich Push, Push Open Action and Action Buttons options discussed above.

# Additional options

Below the push notification's configuration options, there are various additional options:

• To see the template's revision history, click See Revisions.
• To clone the template to the same project, click Clone Template.
• To send a proof of the template to yourself (with your own data), as random users (to yourself, but using data from random contacts in your project), to an internal list or to someone else, click Send Proof and select an option. For more information, read Sending Proofs. In-app message and push notification proofs ignore Selective In-App or Selective Push settings (unless they're sent while creating or editing a campaign).
• To preview the template with user data, click the Preview With Data button.
• To save the template, click Save Template.

# Further reading

• Template Options for Email
• Template Options for In-App Messages
• Template Options for SMS
• Template Options for Web Push Notifications