Mobile Push Notifications
Overview of Push Notification Customizations.
Major Release: User Model Beta
We are in the process of migrating to a new user-centric data model. To learn more check out the User Model Beta Overview
Version 9 of our documentation is now out of date. Version 11 of our documentation has been updated for this change.
Overview
Push Notifications are Rich Text Format messages that get "pushed" from a server and are then received on displayed on your user's device, even if the app is not open.
The purpose of this guide is to give you a general overview of push notification content and best practices. If you are developing a website, we have a separate guide for Web Push Notifications.
Examples of mobile push notification layouts for iOS and Android
How push notifications work
Push notifications are banner-style messages that can contain text, images, buttons, and sometimes more functionality (depending on the device's operating system).
Devices subscribe or "opt-in" to receive push notifications, usually through a prompt on iOS mobile apps. Android mobile app subscriptions occur as soon as the device downloads and opens the app.
Design Guide
Below is a brief outline of options you can configure for your mobile push notifications in OneSignal. Each mobile operating system supports push notifications differently.
For more in-depth platform-specific details, see our Push Notification Design blog post.
| Notification Content | Details | |
|---|---|---|
| 1 | Title | Restricted to 50 characters. API: headings propertySupports: Emojis 👍 Message Personalization Language & Localization |
| 2 | Content | Restricted to 150 characters. API: contents propertySupports: Emojis 👍 Message Personalization Language & Localization |
| 3 | Icons | Android provides Small and Large Icons. Both of which can be customized following Android: Notification Icons. API: small_icon & large_icon propertyiOS sets the icon based on the App's default icon. |
| 4 | Large Image | 1440x720 or 2:1 aspect ratio. PNG, JPG, GIF (iOS only supports animated GIF Android GIF frozen on first frame).API: ios_attachment & big_picture property |
| 5 | Action Buttons | Customizable buttons to perform a custom action. API: buttons property |
| 6 | Timestamp | Set by device. When the message was received. |
| 7 | App Name | iOS: The Display Name in Xcode. Android: The <application android:label="YOUR APP NAME"> in the AndroidManifest.xml |
Additional Content Support
| Additional Content | Details |
|---|---|
| Sounds | Supported on iOS and Android mobile apps. Android uses Android: Notification Channel Categories. API: ios_sound & android_channel_id property |
| Badges | Red dots with numbers for iOS and Android mobile apps. Android uses Android: Notification Channel Categories. API: ios_badgeType & ios_badgeCount property |
Notification Behavior & Interruption
You can also control some aspects of the Notification's Behavior & Payload, such as how long the push will be held by FCM/APNS when the device is offline, collapsing notifications, and more.
| Behavior | Details |
|---|---|
| Deep-links and URLs | When clicked, sends subscribers to a custom URL or view within the app. API: url property |
| Pop-up display and Interruption | Android: Notification Channel Categories sets the Importance of the notification to display as a "heads up" or "banner" type or go straight to Notification Center. iOS: Focus Modes and Interruption Levels sets the Interruption level of the notification to display as a "heads up" or "banner" type or go straight to Notification Center. |
| Time To Live | How long the push is saved on the FCM/APNS/WNS servers if the subscriber's device is offline. API: ttl property |
| Collapse Id | Replaces Notifications already present on the subscriber's device if the current notification contains the same collapse_id.API: collapse_id property |
| Background and Data Notifications | Sending notifications without a visual appearance to the subscriber. Mobile only. |
| Additional Data | Additional content that is not visible may accompany a message payload. See below FAQ for "How much data can a push notification hold?". API: data property |
Character Limits
Because each platform uses a different visual layout for messages, the amount of content that is visible in a notification can vary. The following are approximations for how many characters in a notification based on platform.
Emojis count as a single character.
| Platform | Title | Body |
|---|---|---|
| iOS | ~25-50 (same for Subtitle) | ~150 |
| Android | ~50 | ~150 |
| Best Fit Across All Platforms (Including Web) | ~20 | ~60 |
Emojis
You can copy and paste emojis directly into the Title, Subtitle, and Message of the notification. Any standard emoji will work, and you can use http://getemoji.com/ for more.
Emoji Limitations
Emojis are controlled by the operating system that is receiving the notification, and the operating system must support emoji for the emoji characters to be seen.
FAQ
How much data can a push notification hold?
Push notification payloads cannot exceed 4096 bytes of data.
Push notification additional data cannot exceed 2048 bytes of the 4096 bytes allowed.
Each platform has different data limits. The total character limit is based on the body, title, and any images or custom data you add. Generally, the limit can be 3500 characters.
Updated 23 days ago