Push (aka remote) notifications are the standard for getting your user's attention and sharing important information when they are not actively using your mobile app or website. They can display text, images, buttons, play sounds, and more!

This guide sets up web push notifications. If you have a mobile app, see Mobile Push Setup.

Setup the Web SDK

Please follow our Web SDK Setup to get Web Push Notifications on your website. Share this guide with your developer! We also support WordPress.

Technical Requirements & Browser Support

An HTTPS website with the ability to upload files to the server. Web Push requires a Service Worker to receive push notifications.
Web push notifications are supported across most browsers and devices. See Web Push FAQ for details.
Users cannot subscribe to websites while in incognito or private browser modes.

Ask permission to send push notifications

Users need to subscribe (aka "opt-in") to receive push notifications. This requires setting up and displaying a Web Permission Prompt, then having your users accept.

You can explicitly request permission using our requestPermission method in our Web SDK. However, some browsers like Safari and Firefox do not allow the required permission prompt to be shown without some kind of "user gesture" like clicking a button first before showing the prompt. We provide different Web Permission Prompts to satisfy this requirement and help you increase opt-in rates.

Identify your users & subscriptions

As users subscribe to push notification, they are assigned a OneSignal ID (OneSignal's User ID) and Subscription ID (OneSignal's unique channel/device ID). The user is considered anonymous until you set your own External ID to identify the user across all their subscriptions.

See Users and Subscriptions for more details.

Push notification design

Customize the look of your notifications including the icons, images, action buttons, and more following these guides

1937 — Examples of web push notification layouts for the Google Chrome browser

1. Title

The top-most customizable text of the notification. Push notifications do not support custom fonts or styling such as bold, italics or underlines. The style is set by the operating system.

Around 60-80 character limit.
Supports: Emojis 👍, Message Personalization, Language & Localization
API: headings

2. Message

The localized text the provides the notification's main content. Push notifications do not support custom fonts or styling such as bold, italics or underlines. The style is set by the operating system.

Around 150 characters limit.
Supports: Emojis 👍, Message Personalization, Language & Localization
API: contents

3. Icons

The best way for users to recognize your app. Setup your default icon in the Web SDK Setup and change it when sending messages if desired.

Recommended size is 256x256 pixels.
Supports: PNG, JPG, GIF (not animated).
API: chrome_web_icon , firefox_icon

4. Large image

You can display a custom image on Chrome for Windows and Android only. Chrome on macOS and other browsers like Firefox, Edge and Safari will have this image replace the icon in the payload.

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.
Recommended image size: At least 360x240 pixels with aspect ratio of 3:2
Supports: PNG, JPG, GIF (not animated).
API: chrome_web_image

5. Action buttons

Customizable buttons to perform a custom action. Only supported on Chrome. See Action Buttons for details.

API: web_buttons

6. Badge & browser

The badge is the small icon that shows in the Android status bar and is customizable on some versions of Chrome.

Must be an alpha-channel icon PNG. Example Badge icon.
Size 72x72 pixels
API: chrome_web_badge

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.

More Options: Set by the browser. Includes notification settings and focus assist.

Notification properties and behavior

You can 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.

Display behavior

Web push notifications will pop-up on the screen depending on the user's Operating System's Notification Settings and browser settings. Browsers do not support custom sounds for web push notifications.

Removing notifications from view

Time To Live: How long the push is saved on the FCM/APNS/WNS servers if the subscriber's device is offline. See Remove Notifications and TTL for details.
- API: ttl
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

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_url

Notification payload, background and data notifications

Push notification payloads cannot exceed 4096 bytes of data. 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. See OSNotification Payload for all properties.

Additional Data : Non-visible data that may accompany a message payload and accessed within the SDK.
- API: data

FAQ

Why are notifications not displaying correctly?

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

Can OneSignal send Web Push Notifications in an on-premise closed network?

Our Web Push SDK can work as long as the computers on your closed network have access to the push gateway servers that you want to support:

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.