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 Setup FAQ

Web Push Integrations

OneSignal used to only be configurable by Custom Code. We began offering a dashboard-based configuration in December 2017, which simplifies the setup process for customers and requires no coding. All OneSignal customers that set up web push before December 2017 have been migrated to the 'Custom Code' integration.

Why should I use Custom Code?

Custom code gives you additional capabilities to control how push notifications are run on your site. These can include:

  • Prompt triggers - You may want special rules for how prompts are triggered
  • Multi-language prompts - If you wish to have different prompts on pages for different languages

What happens if I switch from Custom Code to Typical Setup or a Website Builder?

At any time you may switch your integration from Custom Code to Typical Setup or a Website Builder (e.g. Wordpress, Blogger, etc). Switching integrations away from Custom Code means OneSignal will ignore any code your site uses to control push notifications, including:

  • The prompt(s) you present users
  • When those prompt(s) are triggered
  • Any custom capabilities you may have added to OneSignal such as tags

Because this change may cause unexpected behavior, we recommend staying with 'Custom Code' unless your site configuration is very straightforward or you want to start over.

What browsers does the Web Push Editor configure Web Push for?

The Web Push Editor supports web push for Google Chrome and Mozilla Firefox. It does not configure Safari, which you must edit from Safari Web Push Setup. We will soon add Safari support.

Why does my site require a label?

The Web Push standard adopted by all major web browsers requires notifications to come from an HTTPS address with technologies that support web push (specifically, the ability to upload files to the root directory). OneSignal has developed a work-around since not all sites fully support these technologies - even if the websites themselves support HTTPS.

Our work-around (called the OneSignal HTTP SDK) creates a site that we host for the sole purpose of delivering your notifications. This site (os.tc) creates a unique subdomain based on your label (e.g. yoursite.os.tc) that is displayed to users when they receive your notifications. For example:

The label you select must be unique - if somebody else is already using it, you must choose another.

Why does my website builder require a label?

Several website builders must use of the OneSignal HTTP SDK that requires a label because these technologies do not allow files to be uploaded to the root directory. These include:

  • Blogger
  • Shopify
  • Squarespace
  • Weebly
  • Some Wordpress implementations
  • Some Drupal implementations
  • Some Joomla implementations
  • Some Magento implementations

Why can't I change my label?

OneSignal allows you to experiment with different labels when you have fewer than 100 web users to give you some extra flexibility while you're still deciding how to use push notifications. After your app has 100+ web users, this setting is disabled, and you must start over with a new OneSignal app to use a different label. We do this because changing your label can cause users to receive duplicate notifications.

What if my site is in a subfolder?

Web push is configured at the domain or subdomain level.

If your site is hosted in a subfolder, like example.com/blog (where blog is the subfolder), your web push domain will be example.com.

On the other hand, if your site uses a subdomain (e.g. https://blog.example.com), your web push domain will be blog.example.com.

OneSignal SDK Files & Code

Can I host the OneSignal SDK myself?

No, you should use the CDN URL supplied in the Web Push Settings instead.

Troubleshooting: adding code in the right location

https://cdn.onesignal.com/sdks/OneSignalSDK.js and manifest.json must be located in the <head> of all pages. This ensures all pages can subscribe for notifications, and that session count can be accurately counted.

What if there is already a manifest on my site?

Web browsers only support sites with one manifest (e.g: <link rel="manifest" ... ), located in the <head> tag of your site. If your site already has a link tag with a manifest, you can do one of two things:

1. Copy the following parameters into your existing manifest (recommended)

  "gcm_sender_id_comment": "For OneSignal Web Push Notifications, Do Not Change ID",
  "gcm_sender_id": "482941778795"

2. Be sure to put the onesignal manifest before the other manifest in your page.

Note that this will disable any functionality associated with the other manifest.

Can OneSignal SDK files be served from a subfolder of my site?

manifest.json

  • This file can be served from anywhere (from any origin, not just your site's) and any subfolder and the file can be named however you would like. Just be sure to include the file with the correct path and filename. This file only affects Chrome; Safari and Firefox do not use a manifest.json for push notifications.

OneSignalSDKWorker.js & OneSignalSDKUpdaterWorker.js

These files should not be renamed and the files should be served from the top-level root. The service worker being pointed to must be on the same origin. Pointing to a service worker on a different origin is not allowed. If you cannot serve them from the top-level root, your options are:

1. HTTP Header

These two files can be served from a sub-directory only if these two files are served with an additional HTTP header "Service-Worker-Allowed: /".

These two files make up our service worker, a background web worker to display notifications. Parts of our web SDK depend on the service worker being registered properly: it should be served with the HTTP header "Service-Worker-Allowed: /" if served from a subfolder, otherwise it should be served at the top-level root of your site.

2. Subscribe Under a Subdirectory

If you are not able to add an HTTP header, you can add the service worker files to a subdirectory like:

  • yoursite.com/subdirectory/OneSignalSDKWorker.js
  • yoursite.com/subdirectory/OneSignalSDKUpdaterWorker.js

However, you can only initialize OneSignal on pages within your "subdirectory" like yoursite.com/subdirectory. You will not be able to subscribe users on your main page yoursite.com

To setup the service worker files in a subdirectory on Typical Setup under step 5 Advanced, toggle the "Service Workers" switch and add the path, filenames and registration scope.

To setup the service worker files in a subdirectory on Custom Code Setup. Setup your init call similar to this:

<link rel="manifest" href="/manifest.json" />
<script src="https://cdn.onesignal.com/sdks/OneSignalSDK.js" async=""></script>
<script>
   var OneSignal = window.OneSignal || [];
    var initConfig = {
        appId: "YOUR_APP_ID",
        notifyButton: {
            enable: true
        },
    };
    OneSignal.push(function () {
        OneSignal.SERVICE_WORKER_PARAM = { scope: '/subdirectory/' };
        OneSignal.SERVICE_WORKER_PATH = 'subdirectory/OneSignalSDKWorker.js'
        OneSignal.SERVICE_WORKER_UPDATER_PATH = 'subdirectory/OneSignalSDKUpdaterWorker.js'
        OneSignal.init(initConfig);
    });
</script>

The path and scope should look similar to /subdirectory/ also add the names of the service workers OneSignalSDKWorker.js and OneSignalSDKUpdaterWorker.js unless you changed the names, then add the new name.

3. My site is not fully HTTPS

The final option is to go into the OneSignal dashboard configuration and select "My site is not fully HTTPS" and add a 'Label" aka a subdomain. Then press "Save" and continue the setup.

Can OneSignal integrate with another service worker on my site or a Progressive Web App?

Note: This only applies if your site has another service worker. If you are developing a Polymer site or a Progressive Web App, you most likely have another service worker.

Attention WordPress Users Only

The most common PWA plugin is Super PWA, all PWAs have an issue with our service worker that requires a bit of extra setup.

Please see Super PWA's guide to resolving this issue

Our service workers OneSignalSDKWorker.js and OneSignalSDKUpdaterWorker.js overwrite other service workers that are registered with the topmost (site root) service worker scope. The solution is to merge all other service worker scripts into our service worker scripts using importScripts() and to register the merged service worker instead of the original worker.

Both OneSignalSDKWorker.js and OneSignalSDKUpdaterWorker.js contain the following code:

importScripts('https://cdn.onesignal.com/sdks/OneSignalSDKWorker.js');

Please modify both OneSignalSDKWorker.js and OneSignalSDKUpdaterWorker.js to import your other service worker scripts, like:

importScripts('https://site.com/my-other-service-worker.js');
importScripts('https://cdn.onesignal.com/sdks/OneSignalSDKWorker.js');

We recommend the above approach instead of importing our service worker into another file because our web SDK replaces other workers that are registered on the root scope.

Additionally, please be sure to modify your site's code to register OneSignalSDKWorker.js instead of your own worker. You can do this with code like:

navigator.serviceWorker.register('/OneSignalSDKWorker.js');

More about service workers can be read here.

Can I customize the OneSignal init code?

You can customize the OneSignal init code only if you've selected the Custom Code integration. If you select Typical Site or Website Builder, any init code you add will be ignored by the OneSignal SDK.

How do I test my site on a local environment?

If you have a main production site and also a local test site, please create a separate development app for testing locally.

Web push apps can only be used on the Site URL specified in your OneSignal dashboard. If you have an existing production app pointing to https://your-site.com, you can't simultaneously use this app on https://localhost. Additionally, apps with more than 100 users cannot change the Site URL, so you can't change your app's Site URL to point to https://localhost.

Treating http://localhost as HTTPS

Chrome treats http://localhost and http://127.0.0.1 as secure origins, allowing HTTPS integrations even on HTTP. Please note these HTTP origins are the only exceptions, and HTTP production sites will not have a working HTTPS integration. OneSignal only supports this if you add:

  • For Custom Code integrations: allowLocalhostAsSecureOrigin: true to your OneSignal init options (top level, on the same level as appId).
  • For Typical Site integrations: Enable "Treat HTTP localhost as HTTPS for testing" in the Advanced options section of the web config editor.

Additionally, if you're testing localhost on HTTPS with a self-signed certificate, you may have to ask Chrome to ignore invalid certificates for testing with: --allow-insecure-localhost. Firefox and Safari provide built-in mechanisms to add exceptions for security certificates.

Prompts

Why does my Prompt keep showing up?

The Slide Prompt is automatically shown when:

  • Your OneSignal JavaScript initialization settings contains the autoRegister: true property.
    • Custom Code - this automatically triggers the browser's native permission prompt. See Initialization Examples for a code example of where to place the autoRegister property.
  • The user visited your page in a new browser tab or window. Users navigating between links on the same browser tab or refreshing the same page will not trigger the drop-down prompt
  • All of the reasons listed below in "Why isn't my Permission Message showing up?" (next section) must not occur. If any of those reasons are true as well, we do not show the Slidedown Permission Message.

When the first two conditions are true (and none of the conditions listed in the next section are true), the slidedown pre-permission message will slide down from the top as soon as the page loads, covering other page elements. On a mobile browser, the message will slide up from the bottom.

Why isn't my Prompt showing up?

Slide Prompt

Even if you trigger showHttpPrompt(), it may not always show the message. The message will not be shown if any of the following are true:

  • The user previously dismissed the message by clicking the "No Thanks" button
  • The user has blocked notifications for your-label.os.tc
  • The user is already successfully subscribed to notifications
    A user who is already subscribed does not need to re-subscribe.
  • You have manually opted out the user via our setSubscription(false) API

If you've intentionally disabled a user's permissions by calling setSubscription(false), you must manually opt the user back in by calling setSubscription(true); our drop-down prompt will not show.

If the prompt is not shown, the showHttpPrompt() method returns a Promise that resolves to a string value briefly describing the reason the prompt was not shown. You may also enable debug logging for the SDK via OneSignal.log.setLevel('trace'); to see explanations of why the prompt is not shown.

Why isn't my Browser Permission Request showing up?

A browser's permission request may not show when triggered if one of the three conditions is true:

  • The user has already allowed notifications
  • The user is already subscribed
  • The user blocked notifications

Why use .push in the SDK?

See: http://stackoverflow.com/a/38466780/555547

You may have noticed the need to wrap your OneSignal calls with OneSignal.push(function() { ... })

OneSignal.push(function() {
  /* ... */
});

The OneSignal SDK is loaded asynchronously on your page, e.g.:

<script src="https://cdn.onesignal.com/sdks/OneSignalSDK.js" async"></script>

You can read more about the async attribute here and here.

Basically, a script without an async attribute stops the loading of the rest of the page while it is fetched and executed, but async scripts allow the rest of the page to load, while it is eventually fetched and executed. This presents a problem for page scripts that depend on the OneSignal existing. If the OneSignal variable does not yet exist, how can OneSignal be used?

Most of the OneSignal code examples begin with:

var OneSignal = window.OneSignal || [];

This says: create a OneSignal variable, and if OneSignal is loaded already assign it to the loaded instance, otherwise let OneSignal equal the empty array [].

All arrays have a .push() function, so at this point, the OneSignal variable is simply an array of functions we're pushing on to it.

When the SDK finally loads, the SDK processes all the functions pushed so far and redefines .push().


Web Push Setup FAQ


Suggested Edits are limited on API Reference Pages

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