Sending Push Notifications

Iterable can create and send push notification campaigns to iOS and Android devices, all from a single message template.

Push notifications can be customized with sounds, images, videos, and action buttons (iOS and Android support different options)—all the elements needed to create engaging and valuable content for your users. Iterable's push notification editor provides live previews as you edit, validates errors, and can be used to integrate data stored on a user's Iterable profile into a message.

This guide describes how to use Iterable to set up your mobile apps to send push notifications, create a push notification template, send a push notification campaign, and use workflows to send push notifications.

# Table of contents

# Setting up your mobile apps

Before sending push notifications, work with your mobile engineers to configure your iOS and Android apps. For more information, take a look at the following resources:

• iOS:

  • Setting Up iOS Push Notifications
  • Iterable's iOS SDK
  • iOS SDK Release Notes

• Android:

  • Setting up Android Push Notifications
  • Iterable's Android SDK
  • Android SDK Release Notes

# Creating a push notification template

To send push notifications with Iterable, first create a push notification template and provide basic details about its name, message type, title, text, push open action, and any associated rich media. Then use expert mode to further customize the template's configuration as necessary.

To create a push notification template, navigate to Content > Templates click Create New Template, and select Push. This brings up the push notification template editor.

# Using the push notification template editor

As you edit the fields in the push template:

# Basic push notification information

When building a push notification template, provide the following basic information:

• Template Name: The template's internal-facing name. Use this to find the right template when building a campaign.

• Message Type: The message type associated with the campaign. Message types categorize messages, allowing users to receive only the content they're most interested in. For more information, read Messages Channels and Types Overview.

• Title: The title text that should appear at the top of the push notification.

• Push Message: The text that should appear in the body of the push notification.

• Push Open Action: The action that should occur when the user taps on the push notification.

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

  • Open URL: Passes a URL to the mobile appliction's URL handler. This URL can deep link to specific content in the app or point to external content to open in a web browser. When this option is selected, the template editor will prompt you to provide a URL.

• Rich Push: An image or video (Android push notifications do not support video) and action button to associate with the push notification. Action buttons sit below push notifications and allow users to take immediate action on their content. 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.

  Options specified in this section apply to both iOS and Android push notifications. To configure platform-specific settings or use more than one action button, use expert mode.

  

  NOTES

  • In the push notification preview, click an image to expand it.
  • The action button shows when the push notification is expanded; if you don't see it, click on the preview.
  • This section allows you to configure a single action button; to use multiple action buttons, see expert mode.
  • 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 Iterable's iOS SDK.

# Expert mode

To further configure the push notification, enable Expert Mode (using the toggle at the top of the template editor). Then, adjust the following settings as necessary:

• Custom Action: The name of a custom action to pass to your mobile application's custom action handler. Work with your team's mobile engineers to decide on a list of custom actions to support. This option is only available when Expert Mode is toggled on.

  

• Action Buttons: Buttons that display below push notifications, allowing users to take immediate action on their content. 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. A push notification can have up to three action buttons.

  

  Example action buttons on iOS and Android:

  

  NOTES

  • Action buttons show when the push notification is expanded; if you don't see them, click on the preview.
  • 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 Iterable's iOS SDK.

  Options for action buttons:

  • Button Text: The text that should 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: The button's type impacts its appearance and the actions available to it (see below). Iterable supports three different types of action buttons:

    • 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. When selected, this type of button provides a Placeholder input for specifying placeholder text for the push notification's text input, and a Submit Button Text input for specifying the 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 provided value to the application's custom action handler, which is defined in the app's code. Decide in advance with your team's mobile engineers on a list of supported custom actions.

      • 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 with the app 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 the push notification. 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. Iterable validates the URL to make sure it can be rendered.

  NOTES

  • In the push notification preview, click an image to expand 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 Iterable's iOS SDK.

• Wake App: Causes the app to wake up in the background to perform a background update. Un-checking this setting ensures that the user doesn't wake the application and cause it to ping your system's servers.

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

  NOTES

  In the push notification preview, click an image to expand it.

# 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 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 Rendering Templates with Data Feeds.

# Custom Metadata

Additional JSON data to send with the push notification. This data will be available for your apps to process as necessary.

This data can be used to control the state of your application. For example, if a user reaches VIP status and a push message is congratulating them for this achievement, the notification might contain custom data telling the app that the user is now a VIP. The app could process this custom metadata and accordingly change the home screen or app colors.

# Deprecated push notification fields

The following fields have been deprecated and are no longer available for new templates. Instead, use the Rich Push, Push Open Action, and Action Buttons options discussed above.

• iOS Deep Link
• Android Deep Link
• iOS Category

Templates that already use these fields will continue to display them and work as expected

# Saving the push notification template

After configuring the push notification template, save and view a preview:

1. Save the template by clicking Save Template.

2. Preview the template by clicking Send Proof or Preview With Data.

   On the Preview with Data screen, enter an email address and click Load User Data to view how that user's profile data impacts the rendering of the push notification.

3. Back in the template editor, make changes as necessary.

# Creating a push notification campaign

After configuring your mobile apps to work with push notifications and creating a push notification template, you can send a push notification campaign. Follow these steps:

1. Navigate to Messaging > Campaigns and click Create New Campaign.

   

2. Fill in the necessary details for the campaign (name, custom converstion metric, labels), and choose a campaign type: Blast or Triggered.

3. For Message Medium, select Push.

4. Enable Selective Push, if necessary.

   

   If you have multiple mobile apps only a subset should receive the push notification campaign, enable Selective Push and select the mobile apps to include.

   If you do not enable selective push, Iterable sends the push notification campaign to all push integrations defined in the project, regardless of whether or not they are assigned to mobile apps.

   NOTE

   Define mobile apps in Settings > Mobile Apps. For more details, see Setting Up iOS Push Notifications and Setting Up Android Push Notifications.

5. Select send and suppression lists.

   In order for users to receive ush notification campaigns from Iterable, their user profiles must have a device token associated with your mobile app. Iterable's mobile SDKs (iOS, Android) populate these tokens when the app is run.

6. Click Continue to Templates.

7. Select and edit a template, or create a new one. Read Creating a push notification template for more information.

8. After editing, saving, and previewing the template, click Save & Continue To Review.

9. To activate a triggered campaign, click Activate Campaign. To send a blast campaign, click Send Campaign Right Now or Schedule Campaign for Later.

10. After launching the campaign, you'll see its Campaign Analytics screen, where you can view statistics about the campaign. For more information about these analytics, read Push Campaign Metrics.

# Using a workflow to send a push notification

To use an Iterable workflow to send push notifications, follow these steps:

1. Navigate to Messaging > Workflows.

   

2. Select an existing workflow or click Create New Workflow to create a new one.

3. Set up up the workflow as necessary.

4. At the point in the workflow where you'd like to send a push notification, drag a Send Push node onto the workflow canvas and connect it to another node.

   

5. Configure the new Send Mobile Push node by double-clicking on it.

   

6. Provide a Campaign Name, select a custom conversion metric if necessary, and add Labels.

7. Select a template and click Update Node.

   Alternatively, edit an existing template before selecting it:

   • Right-click the name of a template and open it in a new browser tab.
   • Edit the push notification template as necessary.
   • Click Save Template.
   • Back in the original browser tab, close the workflow node.
   • Double-click the Send Mobile Push node to re-open it.
   • Select the edited template and click Update Node.

8. Back on the workflow canvas, click Save.

9. Enable the workflow with the toggle in the upper-left corner of the workflow canvas.

# Further reading

• Iterable's iOS SDK
• iOS SDK Release Notes
• Setting Up iOS Push Notifications
• Advanced iOS Push Notifications.
• Iterable's Android SDK
• Android SDK Release Notes
• Setting up Android Push Notifications
• Rendering Templates with Data Feeds.
• Testing a Workflow.
• Messages Channels and Types Overview.
• Snippets Overview