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    Support

Troubleshooting Web Push

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

Troubleshooting
For Developers

My site isn't working in WordPress

WordPress

  1. In the Configuration tab of our WordPress plugin, did you set the Label to be the value you chose on our dashboard platform setting? See WordPress Setup Guide > Chrome & Firefox Push > Step 8.

  2. Did you manually add our JavaScript web SDK to your site? Our WordPress plugin provides all the necessary code; please make sure you're not including our SDK twice, or initializating OneSignal twice.

My site isn't working in Firefox

Firefox

  1. Make sure you are using Firefox v44+.

  2. Make sure you are not using Firefox's Private Browsing mode. Notifications do not work in this mode.

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

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 in Chrome

Chrome

Chrome on Android Users: See the section right below this.

  1. Make sure you are using Chrome v42+.

  2. Make sure you are not browsing in Incognito mode or Guest browsing mode. Notifications are disabled in Incognito mode, and Guest browsing mode is the same as Incognito mode.

  3. Make sure you are not using Chrome in full screen mode. In full screen mode, Chrome hides notifications.

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 (Chrome on Android)

Android

iOS - web push does not work on iOS devices (iPhone and iPads) because Safari for iOS does not support web push notifications. Apple only supports native app notifications at this time. Read more here

Android - To get push notifications, please make sure you are running Chrome on Android, and:

  • The version is v42+
  • You are not in Incognito / Private Browsing mode
  • You have notifications enabled.

To check whether notifications are enabled in Chrome on Android, tap the 3-dot menu --> Settings --> Site settings (under Advanced) --> Notifications, and make sure it's set to "Ask before sending (recommended)". On the same menu, go to "All sites", find your site and make sure notifications aren't blocked.

Done! Your site should be working again.


My HTTPS site isn't working

Typical Sites, Custom Code

If you use a Website Builders like Wordpress, Blogger, or Shopify, this is not applicable.

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.

  1. Make sure you are using a supported browser. iOS web push is not supported. Microsoft Edge, Internet Explorer, and Safari 5.1 on Windows are not supported.

  2. Make sure you are not using Private Browsing mode / Incognito mode, and make sure your Chrome browser is not full screen (this hides notifications).

  3. Make sure the following URLs are publicly accessible:


    https://site.com/manifest.json
    https://site.com/OneSignalSDKWorker.js
    https://site.com/OneSignalSDKUpdaterWorker.js


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


  4. Copy the contents of your https://site.com/manifest.json. Visit jsonlint.com and paste the contents in. Click the Checkbox to validate. Make sure it passes. If it does not pass, try to follow the instructions to fix the error. Usually the errors are:
    - Missing comma at the end of the line (except last line)
    - Missing quotes around text
    - Using curly smart quotes instead of plain text quotes


  5. Make sure the contents of your https://site.com/manifest.json has a gcm_sender_id value with numbers only.


  6. 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.


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


Done! Notifications on your HTTPS site should now be working.


My HTTP site isn't working

Note: We print helpful error messages on the 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.

  1. Make sure you are using a supported browser. iOS web push is not supported. Microsoft Edge, Internet Explorer, Safari 5.1 on Windows is not supported.

  2. Make sure you are not using Private Browsing mode / Incognito mode, and make sure your Chrome browser is not full screen (this hides notifications).

  3. Make sure your Site URL is correct.

Notifications on your HTTP site should now be working!


My WordPress site isn't working

HTTP Site Users

Make sure the Label value on the OneSignal Web Push Editor settings matches the Label textbox in our WordPress plugin Configuration tab.

Web Push Editor

Wordpress Plugin Configuration Tab

Make sure the beginning of the Site URL value on our dashboard's platform settings is the same as the URL you're using to access your site. If the Site URL is http://example.com, then you must access your site from http://example.com.

Notifications on your Wordpress site should now be working!


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 icon next to your site.


  2. Reset your notification permissions from Allow to Always Ask.



  3. On the same dialog, click the > button and then click More Information.




  4. On the popup dialog that opens, click the Permissions tab, find the Maintain Offline Storage section, and click Clear Storage.


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.

Done! Just refresh your site.


WordPress CDN Support

Using caching plugins with CDN support can cause files required to be served from your domain to be served from the CDN instead. Here's how to use the appropriate settings:

WP Super Cache

  1. Log in to your WordPress admin panel and visit Settings > WP Super Cache.

  2. Click the CDN tab.

  3. Make sure the Exclude if substring tab has at least the following contents: .php, onesignal-free-web-push-notifications. You can have more than this, but you must have at least these two entries.

  4. Click the Contents tab.

  5. Click the Delete Cache button.

  6. The required files should now be served from your domain. Refresh your site page.

WP Engine

In your WP Engine plugin > General Settings > HTML Post-Processing

add the below URLs replacing "YOURSITEHERE" with your website:

#https?://(www\.)?(YOURSITEHERE\.com|mywpenginehandleHere.wpengine.com|wpengineCDNpathHere.wpengine.netdna-(ssl|cdn).com)/wp-(content|includes)# => https://wpengineCDNpathHere-wpengine.netdna-ssl.com/wp-$4
#https://wpengineCDNpathHere-wpengine.netdna-ssl.com/plugins/onesignal-free-web-push-notifications/# => https://mywebsiteHere.com/wp-content/plugins/onesignal-free-web-push-notifications/
#https://wpengineCDNpathHere-wpengine.netdna-ssl.com/wp-content/plugins/onesignal-free-web-push-notifications/# => https://mywebsiteHere.com/wp-content/plugins/onesignal-free-web-push-notifications/

If you don't have this option or need further assistance, you'll have to contact WP Engine. Here's a support ticket you can use:

Hi!

My site runs the OneSignal web push notifications plugin and we are having some issues with WPEngine serving certain files over its CDN. The OneSignal plugin team would like to request a CDN exception on URLs including the string "onesignal-free-web-push-notifications".

Could you please add the above string to the exception list?

Thanks!

W3 Total Cache

  1. Log in to your WordPress admin panel and click Performance on the left sidebar.

  2. Click the CDN tab.

  3. Find the textbox for "Rejected files".

  4. Add an entry for {plugins_dir}/onesignal-free-web-push-notifications/sdk_files/*

  5. Click Save all settings.

CDN Enabler

  1. Log in to your WordPress admin panel and click Settings -> CDN Enabler on the left sidebar.

  2. Find the "Exclusions" textbox.

  3. Add "onesignal-free-web-push-notifications".

    Your textbox might look like ".php,onesignal-free-web-push-notifications".

  4. Click Save Changes.

The required files should now be served from your domain! Just refresh your site page.

WordPress 403 Forbidden Error

Sucuri

Sucuri provides an option in its settings to whitelist files. Please see Sucuri's Whitelist File or Folder guide.

iThemes Security plugin

Disable the "PHP in Plugins" option under "System Tweaks"

Defender Security plugin

Make sure you do not "Prevent PHP execution" in your settings

Example .htaccess

<Files *.php>
Order allow,deny
Deny from all
</Files>
<Files OneSignalSDKWorker.js.php>
Allow from all
</Files>
<Files OneSignalSDKUpdaterWorker.js.php>
Allow from all
</Files>
<Files manifest.json.php>
Allow from all
</Files>

My Safari notification icons aren't showing up

If you uploaded your own Safari notification icons but they aren't showing up on your site, it's probably because for each visitor, the Safari icons set at the time the permission prompt is shown for the visitor are the icons the visitor will see. When the permission prompt is shown, the icons are downloaded locally to your system. Unless the permission is revoked, your visitor will not see your updated icon set.

To see your updated icon set, simply remove notification permissions for your Safari site. On Safari's top menu bar, go to Safari -> Preferences -> Websites -> Notifications and remove your site's entry. Then visit your site again and subscribe to notifications. The moment you see the permission prompt, the new icons will be downloaded to your system and you should see them right away on the permission prompt.


My Safari icons or site name are wrong

Users will always receive notifications with the site name and icons that you set at the moment they signed up, even if you change those at a later time.

For instance:

  • On Monday, you set up your site name 'My Site (testing)'.
  • On Tuesday, user1 subscribes to your site.
  • On Wednesday, you change the site name to 'My Site'.
  • On Thursday, user2 subscribes to your site.
  • On Friday, you send your users a push notification

Result:

  • user1 will receive the notification from 'My Site (testing)'
  • user2 will receive the notification from 'My Site'

This is due to the way Safari handles web push notifications - upon users subscribing to your Safari notifications, Safari stores the site name and icons that are in your OneSignal configuration locally to the user's computer.

How to Fix

The only way for users to receive your updated site name and icons is to have them re-subscribe. to change is if your users open Safari and go to Preferences > Websites > Notifications, then select your site from the list, and remove it. The next time they come to your site they will be prompted to subscribe again. If they subscribe, they will get notifications with the new icon and site name.

Recommendation

We recommend you figure out what icon and site name you wish to use with Safari before launching your site. Changing it after means you will have some users with the old content.


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