OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Discussions

Web Push Advanced Options

Most customers should not need to make changes in the Advanced section of the Web Push Editor. The Advanced section is only for customers who have particular configurations or desire very specific notification behavior.

Webhooks

See Webhooks.

Service Workers

HTTPS only - by default, Service Workers should be stored in the root folder of your site. Unless you have a web configuration that requires changing these, we highly recommend keeping this as default.

🚧

Only change these during initial setup

When you change service worker paths and filenames, any users that have signed up for push notifications will no longer be able to receive notifications, unless users manually browse to your site again.

Therefore, OneSignal prevents sites from changing service worker paths and filenames as soon as more than 100 users sign up for notifications from your site.

For more information, please see our FAQ on how to integrate your own service worker with OneSignal

Click Behavior

Chrome, Firefox. Not supported on Safari.

OneSignal supports several different possible browser behaviors when users click on your notifications. If you would like to learn more about the Launch URL and options like not doing anything when the user clicks the notification, see Deep-links and URLs.

If users do not have your site open on any browser tabs, and click on a notification that takes them to your site, the browser will open a new tab and navigate to the notification's URL.

If users have your site open on one or more browser tabs, and click on a notification that takes them to your site, there are several possible ways the browser can behave that you can configure:

  • Exact Navigate (default) - If the notification's exact URL (e.g. example.com/product) matches a tab that the browser already has open, the browser will navigate to the notification's URL in that tab.
  • Origin Navigate - If the notification's origin (e.g. example.com) matches a tab that the browser already has open, the browser will navigate to the notification's URL in that tab.
  • Exact Focus - If the notification's exact URL (e.g. example.com/product) matches a tab that the browser already has open, the browser will focus on that tab, but not refresh the page.
  • Origin Focus - If the notification's origin (e.g. example.com) matches a tab that the browser already has open, the browser will focus on that tab, but not refresh the page.

HTTP sites - due to limitations on HTTP sites, browsers behave slightly differently than the above in these cases:

  • If multiple stale tabs are open to your site, a clicked notification sharing an identical URL to an existing tab may not focus the tab and may instead open a new tab.
  • When using Origin, if multiple stale tabs are open to your site, a different tab than the matching tab may be focused.

Local Testing

If you are not a developer, you will not have to worry about setting this option.

HTTP sites - This setting has no effect.

HTTPS sites - For customers with HTTPS sites, we recommend setting up secure development environments that support navigating to https://localhost. This way, the development environment will accurately reflect how the site will function. However, sometimes this is difficult for customers, so we support a workaround. By enabling Local Testing, developers can use http://localhost as though it is a secure connection when using the Chrome browser. However, this setting may not reflect the exact behavior of notifications in all cases, which is why we recommend setting up your local environment with HTTPS.
To do this you can follow our How do I test my site on a local environment guide.

Notification Persistence

Default behavior of notifications is they show to users for roughly 5 seconds before they are moved to the Notification History where they are kept for 1 week before removed by the operating system.

You can persist notifications for longer on the screen for Chrome browser subscribers. This means the notification will stay on the screen until the user interacts with it.

Notification Persistence does affect how notifications appear to users. More details in our Notification Appearance Guide.

Triggering Notification Persistence on Chrome

If changing this setting, current subscribers will need to return to the site with the updated option to see the change.

Typical Setup - Use the "Persistence" toggle to turn on/off.

WordPress Plugin - Under "Sent Notification Settings" > "Hide notifications after a few seconds"

Custom Code - With our Web Push SDK, use the persistNotification property.

ChromeWindows 10Mac*
persistNotification Not SetNotification sent to history after ~5 secondsNotification sent to history after ~5 seconds
persistNotification: trueNotification PersistsNotification sent to history after ~5 seconds
persistNotification: falseNotification sent to history after ~5 secondsNotification sent to history after ~5 seconds
  • ​MacOS 10.15+ will not persist notifications on Chrome. Read more on the Chromium Bug Report.

Firefox, Safari - Setting has no effect

Because persistent notifications stay around, users may find it annoying that every notification you send sticks around. Therefore, we recommend keeping this disabled site-wide unless your site delivers high importance notifications (such as a task management app). Users can always mouse over the notification which will keep it on screen to read it's full contains.

How to Upload Files

Once you've downloaded the OneSignal SDK Files from Web Push Settings, you will need to upload them to the top-level root of your site directory, making them publicly accessible. There are three ways you can upload files to your site:

Option 1: FTP

  • Use an FTP Server like FileZilla to upload the files to your root directory
  • Here is a great step-by-step guide.

Option 2: Control Panel

  • Use your hosting provider's control panel like cPanel to upload files.

Option 3: Contact your hosting provider

  • Most hosting providers will be more than happy to assist you in uploading files to your site.
  • Just send them the zip file above and ask them to unzip it in your site's root directory.

👍

Done

Once you've uploaded the OneSignal SDK files, the following URLs should be publicly accessible:

  • https://yoursite.com/OneSignalSDKWorker.js
  • https://yoursite.com/OneSignalSDKUpdaterWorker.js

(replace yoursite.com with your site's domain)

Updated 6 months ago


Web Push Advanced Options


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.