Frequency Caps set organization-wide limits on how many messages a device can receive across all of your active campaigns. If you set a message cap of five and a device would otherwise receive a sixth message, that sixth message is held, so your most message-heavy weeks never turn into an unsubscribe or an uninstall. You turn on each cap individually and set a message count for it. Anything you leave unchecked is not enforced.
Global caps are separate from the frequency cap you can set on an individual campaign. A campaign-level cap governs only its own campaign and is enforced on the device. Global caps govern every campaign at once and are enforced by Localytics before a message goes out. A device must satisfy every enabled rule, campaign-level and global, to receive a message.
In this topic:
What you can set
- Global cross-channel (all channels, all campaigns): daily and weekly.
- Push (all campaigns): daily and weekly.
- In-App (all campaigns): daily, weekly, and per session.
- Inbox (all campaigns): daily and weekly.
Every cap is independent. You can set only a push cap and nothing else, or a global cap with no channel caps, or any other combination. There is no requirement to set a global cap before setting channel caps.
How enforcement works
Before a message is sent, Localytics checks every enabled cap that applies to it. A push notification, for example, must clear both the push cap and the global cross-channel cap. If any one of those limits has been reached, the message is held. In practice this means the most restrictive of your enabled limits is the one that binds: a global cap of 50 with a push cap of 5 lets at most 5 pushes through.
Caps are enforced in the order messages become eligible to send. Counters on the Localytics side increment as each message goes out, and the message that pushes the counter past the limit is the one that gets held. Eligibility is measured when the message reaches delivery, after scheduling and segmentation, not when you activated the campaign in the dashboard.
What happens to a held message depends on the channel. A held push notification is not sent and is not retried; its send window has passed. In-App and Inbox campaigns keep trying: if the campaign is still active on a later day and the device has room under the cap, the message delivers then. An In-App message held on day one of a two-week campaign will display on day two when the user opens a session, provided the day-two cap has not been reached.
Each channel counts against the caps at a different moment. Push counts when the notification is sent. Inbox counts when the message is delivered to the user's inbox. In-App counts when the user views the message, not when the creative is downloaded to the device, so an In-App message sitting unviewed on a device consumes none of your limit.
Counters are kept per device, not per user across devices. A user with your app on a phone and a tablet has a separate count on each. Daily counters reset at midnight UTC, and weekly counters reset Monday at midnight UTC.
Three kinds of traffic are outside the caps. Campaigns that started before you turned caps on are exempt and do not consume your limits. Campaigns you individually flag on their scheduling page ignore the caps. Pushes sent through the push API (transactional sends) are not counted in this release.
How to set it up
- Open Settings, then Frequency Caps. This requires the app settings permission.
- Choose an app from the app picker, or check "Enable for entire org" to apply the same rules to every app you own. The org-wide option overwrites any per-app values you set earlier, so use it only when every app should share the same limits.
- Tick the checkbox for each cap you want and enter a message count. Leave the rest unchecked; an unchecked cap is not enforced.
- Save. Caps take effect after a short propagation delay of about 30 minutes.
- To let a specific campaign ignore the caps, flag it on that campaign's scheduling page. The campaign's summary page shows whether global caps apply to it.
Good to know
- Enforcement is per device, not per user across devices.
- An unchecked cap is not enforced. Only enabled rules count.
- Campaigns that started before you turned caps on are exempt, so they do not consume your new limits.
- An Inbox message already sitting in a user's inbox stays there even if newer messages hit the cap.
- An Inbox message that a user sees more than once only counts the first time.
- Turning a cap off keeps your numbers, so you can switch it back on without re-entering them.
- If a device cannot reach Localytics servers, messages display as if no cap were set. This is deliberate: between over-delivering and silently dropping your campaign, dropping is the worse failure.
Frequently asked questions
Can my channel caps add up to more than my global cap?
Yes. You can set a global cap of 5 with a push cap of 10, an In-App cap of 7, and an Inbox cap of 3. Every message is checked against both its channel cap and the global cap, and the most restrictive limit is the one that binds. In that configuration, no device receives more than 5 messages total, whatever the mix.
If several campaigns are competing under one cap, which message gets held?
The last one to become eligible for delivery. Counters increment as messages go out, so with a global cap of 5 and 6 messages scheduled across channels in one day, the first 5 to reach delivery are sent and the sixth is held. Eligibility is the moment the message clears scheduling and segmentation and reaches delivery, not the moment you activated the campaign.
Is a held message sent later, once the counter resets?
For push, no. A held push is dropped, not queued. For In-App and Inbox, the campaign keeps trying for as long as it runs: on a later day with room under the cap, an In-App message displays at the user's next session and an Inbox message is delivered.
Does an In-App message count against the cap when it reaches the device, or when the user sees it?
When the user sees it. The count increments on the in-app viewed event the SDK reports, so a creative that is downloaded but never displayed consumes nothing.
Can a user ever see more messages than my cap?
Rarely, and only in two narrow cases. First: an In-App message that reached a device while there was still room under the cap can display after the cap fills, because In-App counts when the user views the message and that message is already on the device waiting. Second: if a device cannot reach Localytics servers, messages deliver as if no cap were set. Both are deliberate. The system is built so a fault or a timing edge produces one extra message rather than a silently dropped campaign.
Are caps counted per user or per device?
Per device. A user with your app installed on two devices has an independent count on each.
When do the counters reset?
Daily counters reset at midnight UTC. Weekly counters reset Monday at midnight UTC.
Do I have to set a global cap to use a channel cap?
No. Each cap is independent. You can cap push alone, or set any other combination, and leave the rest unchecked.
How quickly does a new cap take effect?
After you save, allow about 30 minutes for push, 20 minutes for In-App, and 15 minutes for Inbox while the new limits propagate to delivery.
What does "Enable for entire org" do to caps I already set on individual apps?
It overwrites them. Every app in your org gets the values on the page when you check it, replacing whatever each app had before.
Do pushes sent through the push API count against the caps?
No. Transactional sends through the push API are outside global frequency capping in this release.
Can I exclude one campaign from the caps?
Yes. Flag the campaign on its scheduling page. The campaign's summary page shows whether global caps apply, so you can confirm the setting before launch.
How do global caps interact with a campaign's own frequency cap?
Both apply. The campaign-level cap travels with the creative and is enforced on the device, and it resets if the app is reinstalled. Global caps are enforced by Localytics before delivery. A message must satisfy both to be shown.
Do test sends count against the caps?
Test-mode sends do not count against the caps. Messages sent to real devices in production do count, including sends to your own QA accounts, so heavy internal testing in production can consume an org's limits.