Web push notifications are Rich Text Format messages that get "pushed" from a server and are then received and displayed on your subscriber's desktop or mobile device after they have opted-in through a prompt on your website. The purpose of this guide is to give you a general overview of web push notification content and best practices. The details on this guide also work for Windows and macOS desktop notifications.

If you are developing a mobile app, we have a separate guide for Mobile Push Notifications.

Browser Support

Web push notifications are supported across most browsers and devices. For a full list of browsers that support web push, see our Web Push FAQ.

Design Guide

Below is a brief outline of options you can configure for your web push notifications in OneSignal. Each operating system and browser combination supports web push notifications differently. For more in-depth platform-specific details, see our Push Notification Design blog post.

1. Title: The top-most customizable text of the notification.
   1. About 60-80 character limit
   2. API: headings property
   3. Supports: Emojis 👍, Message Personalization, Language & Localization
   4. Push notifications do not support custom fonts or styling such as bold, italics or underlines. The style is set by the operating system.
2. Message: The localized text the provides the notification's main content.
   1. About 150 characters limit.
   2. API: contents property
   3. Supports: Emojis 👍, Message Personalization, Language & Localization
   4. Push notifications do not support custom fonts or styling such as bold, italics or underlines. The style is set by the operating system.
3. Icons: The best way for users to recognize your app.
   1. Recommended size is 256x256 pixels.
   2. Supports: PNG, JPG, GIF (not animated).
   3. See Web Push Icons & Images for details.
   4. API: chrome_web_icon & firefox_icon property
4. Large Image: The expanded icon on macOS and custom image on Windows and Android.
   1. Custom large images only supported on Windows and Android. macOS doesn't support large images since Chrome 59 and only expands the large icon. See Chrome Developer Docs imageUrl for details.
   2. Recommended image size: 1440x720 pixels or 2:1 aspect ratio.
   3. Supports: PNG, JPG, GIF (not animated).
   4. See Web Push Icons & Images for details.
   5. API: chrome_web_image property
5. Action Buttons: Customizable buttons to perform a custom action.
   1. See Action Buttons for details.
   2. API: web_buttons property
6. Badge & Browser:
   1. The badge is customizable on Android Chrome only and is a72x72 or larger PNG. We recommend using white graphics with a transparent background.
   2. API: chrome_web_badge property
7. Domain: Set by the browser. The website origin to which the device is subscribed.
8. Timestamp & Dismiss Buttons: Set by the device when the message was received.
9. More Options: Set by the browser. Includes notification settings and focus assist.

Additional Content Support

• Sounds: Browsers do not support custom sounds for web push notifications.
• Additional Data : Non-visible data that may accompany a message payload. See below FAQ for "How much data can a push notification hold?".
  • API: data property

Notification Behavior & Interruption

You can also control some aspects of the notification's display behavior such as how long the push will be held by FCM/APNS when the device is offline, collapsing notifications, and more.

• Click Behavior: By default, clicking a notification will open your website. You can set this to open any URL you desire. You can further customize behavior within the
  • More details in Advanced Options.
  • If you do not want to link to any page or url, you can add ?\_osp=do_not_open to the end of a URL like this https://yoursite.com/page?_osp=do_not_open as the launch url, this will prevent the push from going to any url upon click and will just dismiss the push.
  • API: url or web_urlproperty
• Notification Persistence: The amount of time the notification stays on the screen. Default is around 5 seconds. This is customizable for only certain browsers
  • More details in Advanced Options.
• Time To Live: How long the push is saved on the FCM/APNS/WNS servers if the subscriber's device is offline.
  • See Web Push Topic & Collapsing for details.
  • API: ttl property
• Topics & Collapsing: By default, newer web push notification will replace (aka collapse) older web push notifications for your origin that have not been clicked. You can display multiple notifications for your site by setting different web_push_topic.
  • See Web Push Topic & Collapsing for details.
  • API: web_push_topic property

Notification Payload and Methods

See OSNotification Payload for all properties and Web SDK Methods for additional notification events.

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.

Why are notifications not displaying correctly?

If notifications are not displaying at all, see Notifications Not Shown - Web Push troubleshooting guide.

If notifications look slightly different, this is because the device's browser and operating system determines how the notifications are displayed. Specifics like character counts, images, and behavior can change in different versions. For example, Chrome version 59 released several large updates to how notifications look and behavior. In 2020, macOS Big Sur (11.0) also made some large updates. These are examples of large updated, but push notifications are constantly changing, the way they look and behave may differ based on browser and operating system versions.

How do I prompt users to receive push notifications?

See Prompting for all available options and details.

Can OneSignal send Web 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, web push notifications cannot be delivered via the standard operating system and browser services, in which case they cannot be sent by OneSignal.