Messaging FAQ

General

How is Optimal Time calculated?

Optimal Time is calculated based on users' previous sessions, country information, and default timezone.

❗️

Avoid message send failures with Optimal Time

Users who don't have previous app session data (such as newly-imported users) may not receive Optimal Time campaigns, since Leanplum won't have enough data to calculate their Optimal Time.

To avoid message send failures:
* Contact your CSM to set a default timezone for users with 0 sessions.

• Schedule campaigns with UTC Time for the first month you use Leanplum.

What if a user's Optimal Time has passed?

If you schedule a same-day campaign, some users' Optimal Times may have already passed. In this case, the message will send immediately (unless Quiet Hours are enabled). We recommend sending optimal time campaigns at least one full day in advance for this reason.

Keep in mind, emails must be scheduled at least one hour in advance.

Why didn't my message send correctly?

When a message isn't sent to one or more of your targeted users, it may have been suppressed because of your settings in Leanplum. The Message Suppressed event will appear in a user's profile if they don't receive a message for one of the following reasons:

• The user has exceeded their message frequency cap. See more on message caps.
• The user unsubscribed from this type of email after the message was scheduled, but before it was sent. See Manage email subscriptions for more.
• Rules set up in the message's jinja template prevented the message from being sent.

The Message Suppressed metric is always tracked with a parameter "reason" that indicates why the message did not go out to the specific user. To explore the reasons why your messaging campaign did not reach your userbase, go to Analytics and generate a "Group by" report with parameter "reason."

If your message was not suppressed, there are a few other possible reasons for message send failure. Your targeting may not be going to the right group, or some of your personalized elements may be formatted incorrectly.

See Push notification troubleshooting for a checklist of potential push issues.

Are messages stored and sent locally or are they sent from the server?

Some message types are stored on the device for later delivery and some types are sent directly from Leanplum servers.

All in-app message types are synced on app start and displayed at the specified point in the experience. If a user meets the targets for an in-app message, it is then synced to their device and will be shown at the specified Display when trigger event which is defined in the message set up. These messages do not count towards Message Caps, though you can set limits on how many times they can be triggered. See Limit how often a user can receive messages for more.

📘

Note: Locally triggered messages (like in-app messages or locally triggered push notifications) do not work with our Quiet Hours feature. This is because the send is controlled by the local trigger, and not Leanplum's servers.

Some message types are triggered and sent directly from our server. These message types include Triggered Push, Webhook and email. Targets for these messages are evaluated at the time of trigger and at the time of send. The user must match the targets at both of these evaluations. Sending these from our server allows us to cancel the send in the case that the user triggers an unless event (in other words, a reverse trigger).

In-app messages

Why are my users still seeing the in-app message I paused/finished?

In-App messages are evaluated and retrieved on Start or Force Content Update. As a result, there can be situations where the user qualified for the message and retrieved it on Start. If shortly after that the message is finished or paused, the user still has a copy of it on their device because there has not been a new Start or Force Content Update call. In this case, if the user performs the message trigger, the In-App message will be shown. The message will be removed at the next instance of Start of Force Content Update.

Can I trigger multiple in-app messages off the same "Display when" event?

If a user triggers and qualifies for multiple In-app messages at the same time, Leanplum will display one
of those messages at random. If you'd like to choose specifically which message shows, consider using In-app message prioritization.

Why aren't my in-app messages triggered by "Event triggers when parameter" displaying?

Using the delivery "Event triggers when parameter" will display a message when the event occurs and the parameter is set to the value you specify. But, if multiple parameters of a single event trigger in-app messages, only one of those messages can display at a time. So if multiple parameters are tracked at once, only one of the associated messages will display.

For example, let's say you have a gaming app where the trigger event "Finish level 2" has two parameters, "Collect coin" and "Defeat boss," and each of these parameters is supposed to fire an in-app message.

Upon finishing level 2, if the user defeated the boss, but didn't get the coin, they would get the "Boss defeated!" message. If the user got the coin but didn't defeat the boss, they would get the "Coin collected!" message. But, if they defeated the boss and collected the coin, they would only get one message. (In general, the message that shows is the one associated with whichever parameter is listed first in your app.)

Can I send in-app messages through the API?

No, in-app messages cannot be sent through the API — only Push Notifications.

How do in-app message limits work? Could a user ever get the message more than the limit allows?

The limit rules for in-app messages are per device and per install, so if a user has 10 devices, they may get the message 10 times, even if the rule said limit to 1 time ever. (This depends on how your user profiles are set up, and when the user looked at each device. )

These limit rules are stored locally on the device, which is why when the app is reinstalled or installed on another device, the rules don't persist. If a user reinstalls the app 10 times on 1 device, they may get a message 10 times.

Why is my background image getting cropped? Why doesn't my image look right?

Our SDK does a lot of work behind the scenes to fit your uploaded image to the in-app message template on a wide array of devices. For Center Pop-up and Push Pre-Permission messages, that means fitting the entire image to the message template itself (the pop-up) with some shrinking or stretching. For Interstitials, however, it means fitting the image to the size of the device's screen. In this case, the image may be cropped to fit the user's screen.

To prevent cropping, we recommend using segments with your Interstitial background image to target different devices (and therefore screen sizes). This way, you can get the image to display perfectly on both iPhone and iPhone Plus, for example.

To add a segment to your background image setting:

1. Hover over the background image label
2. Click the +
3. Create a segment by selecting Technology > Device model from the dropdown menu
4. Enter in the device you want to target for this image file (e.g. "iPhone 7")

Push notifications

Why isn't my device receiving the push notification?

There are a few different reasons your device might not receive a push notification. Check the following possible causes to troubleshoot a push that doesn't seem to be sending:

Targeting issues

• Your device or user info does not match the Target phrase for the message.
• Your device was switched to a different user who is not eligible for the push and/or was not eligible at the time the message sent.

Push token issues

• Your device doesn’t have push enabled.
• Your device’s push token was added after the message was scheduled to send.
• Your device does not have a push token, either because of an uninstall or because the push token migrated to another device.

Delivery issues

• Messages can take up to 15 minutes to be delivered through Leanplum. It’s possible that the message is still in the pipeline and will come through shortly.
• Optimal time delivery takes several hours to analyze before scheduling the message delivery, so push notifications with same-day optimal time delivery may not send until later in the day or the following day.
• If your push notification delivery has a certain amount of delay, it won’t send right away unless you are using the preview button with a registered test device.
• You may have set a global message/push notification limit for your app. If you’ve reached the daily limit, you won’t be able to receive any more messages unless those messages are marked as Caps Exempt. Limits can be adjusted in your app settings > Keys and settings > Messaging.

iOS specific

• The app was open when the push notification was delivered to the device (only iOS users).
• Your bundle ID used to generate certificates is not correct (e.g. you used 'TicTacToe' but should have used 'com.example.you.TicTacToe'). You'll need to regenerate certs after correctly setting your bundle ID in your app.

Android specific

• You have the wrong Google API key.
• AndroidManifest may be missing necessary code.
• build.gradle dependencies using Google Cloud Messaging or Google Cloud Location version is less than the minimum v8.3.0 (if you installed via Gradle).

Other issues

• The app was uninstalled on the device.
• For messages with personalized text (Jinja), your message won’t send if the custom term or attribute text isn’t correct. Example: The if the message “Welcome, {{ userAttribute['First name'] | default('user') }}” didn’t run correctly, it won't send.

If you are still having problems with push notifications, contact your CSM for assistance.

Why isn't my push notification's Open URL working? Why aren't any Open Actions being tracked?

If the URL is incorrect, it's possible that the Open Action won't be tracked. Make sure there is no hidden space at the end of the URL (e.g. "www.leanplum.com/example ").

Can I set a daily/weekly push message limit for users?

Navigate to your app's Keys & Settings in the dashboard and click on the Messaging tab. There you can set weekly/daily push message caps for your users.

See Limit how often a user can receive messages for more on messaging limits in general.

How do I customize my Android push?

The push notifications on Android can be customized using the LeanplumPushService.setCustomizer. For a full sample, check this HowTo article: Customize your push notifications - Android sample.

You can also customize the titles displayed in Android pushes using Data under Advanced Options.

Email

Why are my email metrics off?

See Top reporting metric issues.

Why isn't my email sending correctly?

Check the following causes to troubleshoot an email that doesn't seem to be sending:

Targeting issues

• Your device or user info does not match the Target phrase for the email message.
• Your device was switched to a different user who is not eligible for the email and/or was not eligible at the time the message sent.

Delivery issues

• Messages can take up to 15 minutes to be delivered through Leanplum. It’s possible that the message is still in the pipeline and will come through shortly.
• Optimal time delivery takes several hours to analyze before scheduling the message delivery, so push notifications with same-day optimal time delivery may not send until later in the day or the following day.
• If your email delivery has a Delay set, it won’t send right away unless you use the preview button with a registered test device.

Message content issues

• If your message contains a user attribute or other custom text somewhere, e.g. {{"first_name" value}}, users who do not have a value set for this attribute will not receive the message.
• If the template of the message is not valid the message will not be sent. Make sure the template markup of the message is valid.

Preview issues

• Make sure that the email set to receive your preview hasn't unsubscribed.

Unsubscribes

• The user has unsubscribed from marketing emails and this is a marketing email. If email categories aren't enabled, all emails are treated as marketing emails. With categories enabled, you can specify an email as transactional, which bypasses the unsubscribe status.

Spam

• The email is in spam. This could be because the user reported emails from your domain as spam in the past or because the domain/IP has other issues.