For Advanced Users Only
You should only use custom code if you absolutely need it. Otherwise, we recommend most users set up web push with Web Push Typical Setup or the relevant website builder (e.g. Wordpress, Blogger), rather than custom code.
Recent Change: December 2017
Before December 2017, custom code was required to set up OneSignal. We began offering a dashboard-based configuration in December 2017, which simplifies the setup process and requires no coding. All OneSignal customers that set up web push before December 2017 have been migrated to the 'Custom Code' integration.
To learn more, see these questions:
What happens if I switch from Custom Code to Typical Setup or a Website Builder?
Step 1. Choose Integration
OneSignal supports sending web push notifications from a variety of different web technologies. Select Custom Code to continue:
Step 2. Site Setup
Once you've selected Custom Code as your integration, you must fill out information about your site.
Enter Site URL
This must be the exact URL you see in the browser when you visit the site.
Most users just enter their base site URL for this field (e.g. https://example.com).
If your site is accessible from both www & non-www links (e.g. hexample.com AND www.example.com), please only enter the URL that you wish to send push notifications from. We recommend redirect traffic from one to the other (e.g. users that visit example.com are redirected to www.example.com), so that all your traffic only goes to one.
Auto Resubscribe
Recommended
This feature is only for HTTPS sites and you do not select "My site is not fully HTTPS".
This allows users to automatically resubscribe upon returning to the site without being prompted if they clear their browser cache or if you are transferring to OneSignal from another push provider.
Default Notification Icon URL
Enter a link to an icon file that is at least 80x80 pixels (Recommended size is 192x192). The file must be .png, .jpg, or .gif.
My Site is Not Fully HTTPS
Web Push works best with sites that fully support HTTPS, and we recommend using HTTPS for Web Push when possible. To determine if your site fully supports HTTPS, look for the following:
- Your site URL must begin with
https://, and display a green lock icon on the browser's address bar - Your site must redirect all
http://requests tohttps://requests. In other words, users accessing the site via HTTP will be redirected to the HTTPS version.
If your site does not fully support HTTPS, you should select 'My site is not fully HTTPS':
Once you've selected this, you will need to choose a unique label to be displayed in your notifications. For example, the below image shows notifications are coming from mylabel.os.tc:
Warning: You can only change your label if you have less than 100 web users. Once you have 100+ web users, this setting is disabled.
FAQ
How does OneSignal work differently with HTTP sites?
What if my site is in a subfolder?
Why does my site require a label?
Step 3. Upload OneSignal SDK
Next, you'll need to add the OneSignal SDK files to your site. To do so,
Download the OneSignal SDK files. (You can also download the files here).
Unzip the OneSignal SDK files. There should be two files:
https://yoursite.com/OneSignalSDKWorker.jshttps://yoursite.com/OneSignalSDKUpdaterWorker.js
Upload the OneSignal SDK files to the top-level root of your site directory, making them publicly accessible.
FAQ
How do I upload files?
There are three ways you can upload files to your site:
Option A: FTP
- Use an FTP Server like FileZilla to upload the files to your root directory
- Here is a great step-by-step guide.
Option B: Control Panel
- Use your hosting provider's control panel like cPanel to upload files.
Option C: 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.
How can I tell if I've uploaded the files correctly?
Once you've uploaded the OneSignal SDK files, the following URLs should be publicly accessible (replace yoursite.com with your site's domain):
https://yoursite.com/OneSignalSDKWorker.jshttps://yoursite.com/OneSignalSDKUpdaterWorker.js
Can I host the OneSignal SDK myself?
Can these files be served from a subfolder of my site?
Step 4. Add Code to Site
To enable OneSignal on your site, you will need to write code to initialize OneSignal and add web push prompts. You may also have other code you wish to add.
All code must be placed inside your website's <head>. If you do not have access to modify your site's code, you will need to contact a developer to help you. ]
FAQ
How do I test my site on a local environment?
Troubleshooting: adding code in the right location
Can I customize the OneSignal init code?
Can OneSignal integrate with another service worker on my site or a Progressive Web App?
You're Done!
Next step: Send your first push notification via the OneSignal Dashboard