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

Troubleshooting Web Push

Common setup issues with Web Push (Chrome, Firefox, Safari)

Troubleshooting
For Developers

Please follow each step on this list of common issues and fixes we see for websites. If you are still having issues by the end of this guide, contact support with the information listed at the bottom.

OneSignal prints helpful error messages on your browser's Developer Tools Console. To open the Developer Tools Console, right click on the page, click Inspect, and click the Console tab. Usually we print the direct cause of the error on the console and a link to the solution.

WordPress Users

If you are using our WordPress plugin start with our WordPress Troubleshooting Guide

Common Issues Checklist

Incorrect Site URL

Visit your site and check the URL:

In the onesignal.com dashboard > Settings > All Browsers configuration
Make sure your step 2 Site URL is the same one you see when you visit your site.

Ignore Subdirectories having a subdirectory like /blog does not affect this and can be ignored for setup purposes.

Common issues:

  • www vs non-www For example http://www.yoursite.com is different from https://yoursite.com.
  • HTTP and HTTPS HTTP and HTTPS sites are very different. More details in Web Push HTTP vs. HTTPS

HTTPS Example

HTTP Example

If you selected "My site is not fully HTTPS" and using the Custom Code Setup, make sure you add the Label to your init call the subdomainName parameter like in this example code

Wrong Browser, Viewing Mode, or Browser Version

1 - Make sure you are testing with the latest version of Chrome or Firefox.
2 - Do not use incognito mode, private browser mode or guest browser mode or Firefox's ESR versions. Subscription to push does not work in these modes.
3 - Apple currently still does not support Web Push Notifications on iOS mobile devices like iPhones and iPads. Currently iPhones and iPads can only get notifications from mobile apps, not from websites.
4 - Supported browsers can be viewed in the Web Push Overview.

Browser
Min Version

Chrome

Make sure you are using Chrome 50+.

Chrome v42 is when push started being supported but uses an older payload that is not supported by OneSignal anymore. More information on this here.

Firefox

Make sure you are using Firefox v47+

Firefox v44+ is when push started being supported but uses an older payload that is not supported by OneSignal anymore. More information on this here.

Please visit this webpage and let us know if you see any Supported: false or Errors.

Safari

Make sure you are using Safari 7.1+ on MacOS

Apple does not support Web Push on iOS at this time.

Jump to Safari related troubleshooting

403 & 404 Service Worker Errors - HTTPS sites only

Chrome, Firefox

In your onesignal.com dashboard > Users > All Users page, if you see 403 or 404 Service Worker Errors, that means something is blocking the following files from being publicly accessible:

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

These files must be spelled with the upper case letters and not redirects.
You should be able to visit these pages without any 404 errors or any other pages and see just a white screen with 1 line of code.

If they are not accessible, please upload the files to your site. (Follow the appropriate instructions for your integration: Typical Sites or Custom Code).

No CDN Make sure OneSignalSDKWorker.js and OneSignalSDKUpdaterWorker.js are being served from the same domain of your site. It cannot be served by a CDN or a domain other than the domain the visitor is currently on.

Make sure OneSignalSDKWorker.js and OneSignalSDKUpdaterWorker.js are not being served by a redirect. This is not allowed due to browser restrictions. The file must be served directly. More details on Setting Up OneSignal Service Workers

Service Worker Conflicts

If you are integrating OneSignal into a site with an existing service worker (like a PWA), you may have to merge service workers in order for OneSignal to work correctly. This section of our documentation contains more info on merging service workers.

How do I check if my OneSignal service-worker is configured correctly?

In your browser's development tools, go to the Service Workers section (under "Application" tab in Chrome) and look for "OneSignalSDKWorker.js" as the source for the service-worker for your domain. Detailed Steps to Reproduce.

If you do not see the OneSignal service worker there, you have not configured OneSignal correctly.

If you only see a different service-worker on your site, it may be causing a conflict with OneSignal's service-worker. Try merging the service-workers to resolve the issue.

Still having trouble?

If you're still having trouble, please send us the debug logs from our SDK by following steps 1 and 2 here.


My site isn't working on my mobile phone

iOS - Apple currently still does not support Web Push Notifications on iOS mobile devices like iPhones and iPads. For more information, please read our Blog Post.

Android - Web push works automatically on android mobile devices using a supported browser.

1 - First make sure your site works on Desktop before testing on mobile

2 - You may be subscribed on android web already, but our dashboard does not differentiate mobile web subscribers from desktop web subscribers.

An android web subscriber shows as "Linux armv8l" in the Device column of the "All Users" page.

3 - Check if Notifications are enabled on Chrome in your Android Settings > Application Manager > Chrome. Make sure "Show notifications" is checked like this: https://i.imgur.com/LY810Mj.png on Firefox it will be the same: https://i.imgur.com/a3lB88b.png

4 - Clear your Chrome Cache. If your browser cache is full on mobile, this may not allow further prompting or subscription. Follow Clearing your cache and resetting push permissions based on your browser to test your site again.


Safari Troubleshooting

Safari

1 - Apple currently still does not support Web Push Notifications on iOS mobile devices like iPhones and iPads. For more information, please read our Blog Post.

2 - The icon you uploaded on the OneSignal Dashboard > App Settings > Safari Configuration MUST to be exactly 256X256.

3 - Safari 12.1 created a new rule that users must perform some action on the site before they can get prompted

This is why the slide prompt always shows before native if you use our Typical Setup

If you want to use only the native browser prompt, you will need to setup your own trigger to detect a user action. Then call OneSignal.showNativePrompt(); when you want to show the native prompt.

4 - Finally, try clearing your browser data to see your site as a first time user and try to subscribe again.

Safari Icons Or Site Name Not Changing

Due to Safari's custom web push implementation, your site name and icon image are treated as static resources downloaded and stored locally on the user's computer. New site names and new images are not updated or downloaded.

Unfortunately anyone subscribed with these older resources will need to clear the Safari push permissions and return to the site to resubscribe.


Clearing your cache and resetting push permissions

Even if your settings are configured correctly, if you had previously used incorrect settings, push notifications may not work due to invalid permission or background worker states. These steps will reset your site's notification permissions, clear your site's storage, and remove our background worker.

Chrome (Desktop)

Chrome

  1. Click the icon next your site. Make sure Notifications says Use global default (Ask). If you don't see this -- move on to the next step.

  2. Clear site data - On this same panel click "Show cookies and site data" (Windows) or "# in use" (Mac).

Select all the entries at once and click "Remove". No entries should be left.

  1. If you have selected My Site is not Fully HTTPS in the Web Push Editor or are using a Website Builder that requires you add a label, visit yourlabel.os.tc and repeat steps 1 - 2 for this URL.

  2. Close tabs and windows pointing to your domain or yourlabel.os.tc. This is actually an important step -- don't skip it!

Restart your browser or close tabs to your site

Clearing cookies prevents web storage from working on your site until all tabs/windows to your site are closed, or until your browser is restarted.

This is important -- don't skip it!

  1. Visit chrome://serviceworker-internals/ in a new tab and press the 'Stop' and 'Unregister' buttons under any Scopes that contain yoursite.domain or yourlabel.os.tc. If they won't remove, make sure all tabs or windows pointing to either domain are closed.

Done! Open a new tab to your site and try it out!

Chrome (Android)

Android

If you still have a notification from your site visible in your notification drawer:

  1. Click the gear icon and 'Site Settings'.


  2. Click 'Clear & Reset'.


If you do not have a notification open, open Chrome on Android, tap the 3-dot menu, Settings, Site settings (under Advanced), Notifications, make sure it's set to "Ask before sending (recommended)". Find your site on the list, click the entry, and click Clear and Reset.

Done! Open a new tab to your site and try it out!

Firefox (Desktop)

Firefox

If you have selected My Site is Not Fully HTTPS and have chosen a label for your site (e.g. mylabel.os.tc), you will need to follow these steps for your label's URL (e.g. mylabel.os.tc), not for your site's normal URL.

  1. Click the "i" or "lock" icon next to your site URL.
  2. Next to Receive Notifications under Permissions select the "X" button next to Allowed
  1. On the same dialog, at the bottom select Clear Cookies and Site Data...
  1. On the popup dialog that opens, click "OK"

HTTP or HTTPS sites with os.tc subdomain

Repeat the above process on the subdomain with os.tc

Firefox (Android)

Please follow this Firefox guide to clear all your browser data.

Safari (Mac OS X Desktop)

Safari

On the top menu bar, go to Safari -> Preferences -> Websites -> Notifications and remove your site's entry. Then in the same preferences dialog, go to the Privacy tab and click Clear Website Data.

On the top menu bar, go to Safari -> Preferences -> Websites -> Notifications and remove your site's entry.
Under Websites -> Pop-up Windows if present, make sure your site shows Allow if present.
Then in the same preferences dialog, go to the Privacy tab and click Clear Website Data.

Done! Just refresh your site.


Debugging using Browser Developer Tools

The browser's developer tools can be used to interact with the web SDK on your webpage and enable logging or easily send test notifications to yourself.

1. Access the Browser Developer Tools Console

Chrome - Right click on the page, click Inspect, and click the Console tab of the popup window that opens up.

Firefox - Right click on the page, click Inspect element, and click the Console tab of the popup window that opens up.

Safari - Go to Safari -> Preferences -> Advanced and make sure Show Develop menu in menu bar is checked. Then, on your webpage, right click, click Inspect element, and click the Console tab of the popup window that opens up.

Chrome on Android - Debugging on Chrome on Android is more complicated, and requires a USB cable to connect your Android phone to your computer. Please follow this guide to remotely access your mobile Chrome's Developer Tools console.

Firefox on Android - Debugging on Firefox on Android is more complicated, and requires a USB cable to connect your Android phone to your computer. Please follow this guide to remotely access your mobile Firefox's Developer Tools console.

2. Enable web SDK logging

You should be able to run commands in the developer tools Console now.

Execute the following code:

OneSignal.log.setLevel('trace');

You should see undefined as the result.

If you see:

Uncaught ReferenceError: OneSignal is not defined(…) or ReferenceError: OneSignal is not defined, then OneSignal is not active on your webpage, or you need to switch to the top frame context (see above screenshot at the beginning of this section).

Now that our web SDK's debug logging is enabled, please close the tab and open a new tab to the same page (refreshing the page is not enough to trigger some of our SDK events). You should see a lot of output in the Console.

You can always disable this additional logging by entering this code:

OneSignal.log.setLevel('warn');

3. Check if you are subscribed

Run in the Console:

function isPushNotificationsEnabledVerbose() {
    console.log('isPushNotificationsEnabledVerbose()');
    Promise.all([
            OneSignal.isPushNotificationsEnabled(),
            OneSignal.getUserId(),
            OneSignal.getRegistrationId(),
            OneSignal.getNotificationPermission(),
            OneSignal.isOptedOut(),
            OneSignal.context.serviceWorkerManager.getActiveState()
        ])
        .then(([isSubscribed, userId, registrationId, notificationPermission, optedOut, serviceWorkerActive]) => {
            console.log('Is Completely Subscribed:', isSubscribed);
            console.log('');
            console.log('What is our OneSignal user ID?', userId);
            console.log('What is our push subscription token?', registrationId);
            console.log('What is the notification permission status?', notificationPermission);
            console.log('Are you manually opted out?', optedOut);
            console.log("Is a service worker registered and active? (should be false on Safari, otherwise should be 'Worker A (Main)')?", serviceWorkerActive);
            console.log('What is the current URL of this page?', location.href);
            console.log("What environment does OneSignal think it's in?", OneSignal.sdkEnvironment.getWindowEnv());
        })
        .catch(e => {
            console.error("Issue determining whether push is enabled:", e);
        });
}
isPushNotificationsEnabledVerbose();

Depending on whether you are subscribed, you should see:

Is Completely Subscribed: true

What is our OneSignal user ID? b7b14773-e053-44b6-8eee-1a8fe58c53ba
What is our push subscription token? fwJQA8TYCTk:APA91bFbQyYR9kVvgmxHGV7fKr7sktzh4v2fEXad2KRlqq_zupfUexqbPscpcQ4Iru3IAOQ9sIrrt1TtlUySK1Jy2Vg7lzwpGHCRLBqa-er2cuQ6T79AG9l4MWKrwTfehWcBTDj_BdGD
What is the notification permission status? granted
Are you manually opted out? false
Is a service worker registered and active? true
What is the current URL of this page? https://example.com
What environment does OneSignal think it's in? host

4. Send yourself a test notification

Only if you are subscribed (see above section), you can send yourself a test notification. This notification will only go to you and your other users will not receive this notification. In the console, run:

OneSignal.sendSelfNotification()

You should see something similar to Promise {[[PromiseStatus]]: "pending", [[PromiseValue]]: undefined}, and you should receive a web push notification shortly after. Make sure you aren't using Private Browsing Mode / Incognito mode on Chrome or Chrome's full screen mode as this can hide and disable notifications.

Debugging not receiving Chrome notifications

Note: Please complete these steps in order.

  1. Please see My site isn't working in Chrome. You can't receive notifications in full screen mode, for example.

  2. Please follow steps 1 - 4 in the section Debugging using Browser Developer Tools to try receiving a test notification.

    • For step #3, are you subscribed? If not, stop here, completely clear your site data following these specific instructions, and then re-subscribe to your site in order to receive notifications. Run step #3 again after to verify you're actually subscribed. When following the clear site data instructions, please do remember to close all tabs to your site or restart your browser, since Chrome prevents the site's storage from being accessed until all existing tabs to your site are closed.

    • For step #4, do you receive a test notification? If you do, you're done!

  3. If you're subscribed but you did not receive a test notification, please visit your OneSignal dashboard, visit the Sent Messages page, and click "Viewing: API Notifications" to view the test notifications you've sent yourself. Are they colored red (Invalid)? If they are colored red and Invalid, your web push keys are most likely mismatched. Please let us know on support about this.

  4. If you're subscribed, did not receive a test notification, but you see the message has been delivered (colored green), please open Chrome to chrome://gcm-internals. Click the "Start Recording" button on the top left. Follow step #4 above to send yourself a test notification. Do you see a "Data msg received" like in the below screenshot (make sure to click "Start Recording" first)?

    • If you don't see a "Data msg received", then your Chrome browser is not receiving the notification at all. Please let us know on support about this.

    • If you see "Data msg received" but you still didn't receive a notification, proceed to step #5.

  1. Visit chrome://serviceworker-internals.

    If your site is an HTTPS site like https://example.com, search for Scope: https://example.com.

    If you selected My Site is Not Fully HTTPS and chose a label for your site, search for Scope: https://mylabel.os.tc where mylabel is the label you chose for your site.

    Click Inspect, or Start -> Inspect, like below. A Chrome Developer Tools popup will appear.

  1. On the Chrome Developer Tools popup to our service worker, click the Console tab, and run OneSignalWorker.log.setLevel('trace');. It should return undefined. Any messages from our service worker should now appear in this pop

  2. Switch away from the worker's Dev Tools popup, and back to your main page's Developer Tools console (where you followed step 2). Please send yourself another test notification. You should a lot of output here with an error since you did not see the notification. Please on support about this error. You can right click on the Console -> Save as ... and copy the file contents to our chat support.


Troubleshooting Web Push


Common setup issues with Web Push (Chrome, Firefox, Safari)

Troubleshooting
For Developers

Suggested Edits are limited on API Reference Pages

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