Push Notification Guide
Overview of Push Notification Customizations.
Push Notifications are "Rich Text" Format messages that get "pushed" from the FCM/APNS/WNS servers to your subscribers. Devices subscribe or "opt-in" to receive push notifications usually through Prompting like on Web Browsers or iOS Mobile Apps. Android Mobile App subscriptions occur as soon as the device downloads and opens the app.
Here are common layout guides to follow for push notifications across all platforms:
| Notification Content | Details |
|---|---|
| Character Limits | How many characters are allowed and recommended per platform. Emoji support is available across all platforms 👍 |
| Images | Large Images that appear with the notification. Supported by iOS, Android and Chrome on Windows/Android. |
| Icons | Supported on all platforms. |
| Sounds | Supported on iOS and Android mobile apps. Not customizable on Web Push. |
| Badges | Red dots with numbers for iOS and Android mobile apps. Web Push badges are the small icons on Chrome for Android. |
| Action Buttons | Custom buttons that can support different actions or links. |
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
| Notification Behavior | Details |
|---|---|
| Deep-links and URLs | When click, send users to a custom url or view within the app. |
| Time To Live | How long the push is saved on the FCM/APNS/WNS servers if the user's device is offline. |
| Collapse Id | Replaces Notifications already present on the user's device if current notification contains this same collapse_id. |
| Notification Persistence | Requiring Web Push Notifications to be interacted with to be removed. Only available on certain platform versions. |
| Background and Data Notifications | Sending notifications without a visual appearance to the user. Mobile only. |
| Additional Data | Custom data sent within a push. |
Content
Because each platform uses a different visual layout for messages, the amount of content that is visible varies.
Character limits
The following are approximations for how many characters in a notification based on platform.
Emojis count as a single character. Simply copy-paste the emoji you want into the message or title. Some limitations on Windows 7 and older Operating Systems.
| Platform | Title | Body |
|---|---|---|
| iOS | ~25-50 (same for Subtitle) | ~150 |
| Android | ~50 | ~150 |
| Windows: Chrome | ~60 (Chrome 68+) ~40 (Chrome 67 and lower) | ~120 (Chrome 68+) ~0 - 150 (Chrome 67 and lower) |
| Windows: Firefox | ~40 | ~140-190 |
| Mac: Chrome, Firefox, Safari | ~20-40 | ~20-80 |
| Best Fit Across All Platforms | ~20 | ~60 |
Web Push Character Limits
Windows
Chrome 68+ do not have any restrictions with images added and show about the same title (~60 characters on screen and ~60-80 in Notification Center) and body (~126 characters on screen and ~120-160) count.
Firefox
Titles support ~40 characters, and bodies support ~140-190 characters:
MacOS
All Mac browsers (except Safari) have the same limits due to the way MacOS treats notifications. The features a notification is sent with (such as Icons and the SDK-only persistNotification) affect the amount of characters visible:
| Title | Body | |
|---|---|---|
| Default | ~40 | ~44 |
| With Icon | ~32 | ~35 |
With persistNotification | ~30 | ~33 |
With persistNotification + Icon | ~21 | ~24 |
| Notification Center Default | ~39 | ~80 |
| Notification Center + Icon | ~30 | ~62 |
Safari
There is not a way to remove or edit the site icon on Safari without changing the default icon set in your OneSignal Dashboard.
| Title | Body | |
|---|---|---|
| Default | ~40 | ~90 |
Additional data
Additional content that is not visible may accompany a message payload. Each platform has different limits and is based on the body, title, and any images or custom data you add.
This is roughly 3500 characters for both Android and iOS.
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 must support the emoji for it to be seen.
App Name or Site URL
The App Name shown on the push can be changed in the following settings. Websites cannot change the Site URL shown on the push, it must always show the site origin the user subscribed to.
| Platform | Settings | |
|---|---|---|
| App Name | iOS | Change Display Name set in Xcode. |
| App Name | Android | Change the <application android:label="YOUR APP NAME"> in the AndroidManifest.xml |
| Site URL | Web | Site Origin User Subscribed. Cannot be changed. |
Images
Adding large images to notifications can be done across iOS and Android Mobile Apps and Chrome Browsers on Windows and Android. Firefox, Safari and Edge do not support big images. Chrome 59+ on MacOS stopped supporting large images. You can find more details about this change in our blog post.
Recommended Image Details
| Web Push | Android | iOS | |
|---|---|---|---|
| Filetypes | png, jpg, webp, gif* | jpg, jpeg, png, gif* | jpg, jpeg, png, gif |
| Resolution | Recommendations: 2:1 aspect ratio landscape Max Width: 2000 pixels Min Width: 300 pixels Common sizes: 512x256px1440x720px | Recommendations: 2:1 aspect ratio landscape Max Width: 2000 pixels Min Width: 300 pixels Common sizes: 512x256px1440x720px | Recommendations: 2:1 aspect ratio landscape Max Width: 2000 pixels Min Width: 300 pixels Common sizes: 512x256px1440x720px |
| Documentation | Web Push Image Guide | Android Big Picture Guide | iOS Rich Media Guide |
| OneSignal API Parameter | chrome_web_image | big_picture | ios_attachments |
gifimage animations not supported on Web Browsers or Android mobile apps.- Adding Action Buttons may affect image sizes, please try testing on your devices to make sure the layout fits your needs.
- Chrome 56+ on macOS does not support images.
- For troubleshooting, see Notification Images Not Showing
Icons
All Push Notifications support some type of icon.
Web Push Icons can be set within your OneSignal Dashboard Settings. Some browsers like Chrome, Firefox and Edge allow you to send notifications with different icons. Safari does not allow custom icons. See Safari Web Push Setup to add the Safari Icon.
Mobile Push Icons are set within your mobile app. Android Mobile App Large icons can use external resource. iOS only uses the main app icon.
| Web Push | Android | iOS | |
|---|---|---|---|
| Sending Push Messages | Web Push Notification Icons Guide | Android Notification Icons Guide | Uses the app's default icon. |
| API Icon Parameters | chrome_web_icon works for Chrome, Firefox and Edge. Safari does not support custom icons. | large_icon | Uses the app's default icon. |
Sounds
OneSignal supports adding custom sounds for any notification sent. To learn more, read our guide on Customizing Notification Sounds.
Badges
Android & iOS - See the Badges Guide
Web Push badges are the small icon you see on the notification. More details in Web Push Notification Icons
Action Buttons
OneSignal supports action buttons on all platforms. See our Action Buttons documentation for more details.
Notification Persistence
Most platforms and operating systems support a Notification Center where notifications will persist until user interaction.
For Web Push, Chrome allows notification persistence (stay on screen) for certain operating systems versions with additional setup. See our Notification Persistence Guide for more details.
Notification Behavior
Learn about how to setup Notification Collapsing, Time to live and understand common Notification Behavior & Payload Information.
FAQ
Can OneSignal send Push Notifications in an On-Premise Closed network?
This can work as long as the computers on your closed network have access to the push gateway servers that you want to support:
- https://support.apple.com/en-us/HT203609
- https://firebase.google.com/docs/cloud-messaging/concept-options#messaging-ports-and-your-firewall
If the network is completely disconnected from the Internet, push notifications cannot be delivered via the standard OS/browser services, which is what we support.
Updated 10 months ago