Leanplum's user guides and developer documentation.

Leanplum Documentation

Leanplum's user guides, SDK setup, API docs, and more resources are here to help you get the most out of A/B testing, Campaigns, Messaging, and Analytics.

Push notification basics

Push notifications are delivered directly from the server to a user’s device. These notifications appear regardless of whether or not the user is currently using your app.


iOS, unlike Android, requires users to opt-in to enable push, so some of your users will not be able to receive notifications outside of your app. Try using multiple messaging channels, such as email and app inbox, to reach your non-push-enabled users.

Send a push notification

To send a push notification, create a new campaign or add a new action to an existing one. After setting your campaign's goal, conversion, audience, and delivery, you'll reach the Action tab of the Composer. Select Push Notification as your Action type.

Edit your message

Next, you’ll move to the Edit window, where you can edit the content of your push notification. This is where you write your message and alter its settings.


You can customize message content with user attributes and other values using handlebars {{ }}. For example, "Hello, {{user_name}}!" becomes "Hello, Francis!" See Personalize an action for details.

Add an image

Click Choose an image to upload an image to your push notification. JPEG, PNG, and GIF files up to 10MBs are supported.


Android image limitations

  • Android push images require an aspect ratio of 2:1.
  • We use the BigPicture mode for Android notifications. Only one line of summary is shown when the message is expanded in this format, regardless of the image size. Without having a custom layout for the push notification, it is not possible to have a multiline summary with a big picture.
  • With GIFs, Android will only display a static image in the notification.

iOS options

Since push works a little differently with iOS, there are a few additional iOS settings to consider when editing your message. Most of these categories must be set up in your app to work properly in the Leanplum dashboard.

Requires iOS 8 and higher

The category identifier, which is used to display user actions associated with the notification. This requires categories to be set up in your app when registering for push notifications. An example of a category would be SOCIAL, which shows Like and Share buttons.


Places a numeric badge on the home screen app icon when a push notification is sent. It can be any number you chose to set. To clear the badge, leave the message blank and provide 0 for the badge.


The name of the sound file that you would like to play as the alert sound for the notification. The file must first be included in your application for use, and follow Apple's guidelines.

Preload content

If the app has permission to run in the background, this causes the app to wake up and perform any tasks necessary to preload content associated with the notification. It defaults to true. Setting it to false prevents the content from being preloaded.


Adds a short description of the reason for the alert. See Apple's docs for more info.


Adds a secondary description of the reason for the alert. See Apple's docs for more info.

Web options

These settings affect your web push notifications. You can send push notifications to mobile web users via our HTML5 SDK. Note that web push is only available for select browsers and operating systems.


The title of your web push notification.


The icon image file for a web push notification. Click the field to open the image selector.

In this example, the Title of the notification is "Leanplum WebPush Demo!" This notification has an icon at the top left, as well as a main image. This is the Chrome desktop push — notifications on different devices and browsers may look slightly different from one another.

Advanced options


This allows you to send custom key-value pairs with your push notifications. These will be read by your app when the notification is opened. You can also segment the values of the variables you send, which essentially allows you to pass the segmentation to the code in your app.

Variables can be added to the Data group as key-value pairs with a specific object type.

Click the object type (Text) to change it.

You can also edit the name of the object (here, it is "Variable 1") by clicking it and changing the text. The field next to the name is where you enter the value.

Mute inside app

When this box is checked, the push will be muted for users who are already inside your app. This can help you create a seamless user experience and avoid your users feeling spammed.

"Muted" means the push will still deliver, but won't pop up across the screen.

Android: When muted, the push won't pop up at the top of the screen for users who have the app in foreground at the time of send. If mute is not checked, the push will deliver as usual regardless of whether or not the app is foregrounded.

iOS: When mute is checked, the push won't show on the screen if your app is foregrounded (being used).
If mute is not checked and the app is foregrounded, the push still won't display unless the message has a custom open action, such as "open URL" or "deeplink." In these situations, the push may appear as an iOS in-app alert, instead of the usual push format.

Add Open Action

You have the option of adding an Open Action to your push, an app function that's delivered to users immediately after they open your push. For example, you can deep link users to the app store to leave a review.

An Open Action can be a:

  • URL deeplink
  • App rating request

On the Edit screen, click Add Open Action and select which app function you want as your Open Action. The Open Action becomes the next action in your campaign chain.

By default, the Open Action will be delivered immediately, though you can add a delay if you want.

Updated about a month ago

Push notification basics

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.