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

Typical Setup

OneSignal Web Push Setup Guide for typical websites. Works with all Web Push Supported Browsers (Chrome, Firefox, Safari, and more!)

🚧

Not for WordPress

If you are using our WordPress plugin do not follow this guide. Please see our WordPress Setup Guide instead.

This guide will walk you through how to set up web push on a Typical Site with Javascript.

Generally, if you can add Javascript to your site, you can add OneSignal. However, not all sites allow Service Workers to be added. If you cannot upload our Service Workers to your site, please follow the HTTP Setup Integration below to be compatible.

HTTPS Typical Setup Video

HTTP Typical Setup Video


Step 1. Choose Integration

Select Typical Site if you are adding our Javascript code to your site.

If you are using our WordPress plugin, see our WordPress Setup Guide.

Step 2. Site Setup

Once you've selected Typical Site as your integration, you must fill out information about your site.

Site Name

This will be the default Title of your push notifications if one is not provided.

Site URL

This must be the exact URL (site origin) you see in the browser when on the site (e.g. https://example.com).

🚧

Site URL Must be Correct

If your site is accessible from both www & non-www links (e.g. https://example.com AND https://www.example.com), only enter one URL that you wish to send push notifications from.

We recommend redirecting traffic from one to the other (e.g. users that visit https://example.com are redirected to https://www.example.com), so that all your traffic only goes to one origin.

Auto Resubscribe

Recommended: This feature is only for HTTPS sites and if 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 image file for your site. Recommended size is 192x192 pixels. Minimum 80x80 pixels. The file must be .png, .jpg, or .gif.

My Site is Not Fully HTTPS

This option is for HTTP websites or HTTPS websites that cannot add files to the server. To determine if your site fully supports HTTPS, look for the following:

  • Your site URL must begin with https://
  • Your site must redirect all http:// requests to https:// 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:

🚧

Site URL and Label Should Never Change

You can only change your Site URL or Label if you have less than 100 web users. Once you have 100+ web users, this setting is disabled.

How does OneSignal work differently with HTTP sites?

What if my site is in a subfolder?

Why does my site require a label?

Why can't I change my label?


Step 3. Permission Prompt Setup

To send push notifications to users, you first must ask them for permission using a Prompt. You must have at least one Prompt on your site for web push to work. Click Add a Prompt to open the permission prompt selector.

Permission Prompt Editor

In the Permission Prompt Editor, you can select which prompts you wish to use, and style them as you like. Once you have edited the prompt to your liking, click Save.

Prompt Type

Description

Subscription Bell

A small bell icon at the corner of your page that users can interact with to subscribe and unsubscribe.

Native Prompt (HTTPS-only)

A small modal required by the browser to subscribe users to notifications. Must not have selected "My site is not fully HTTPS" to use this modal.

Slide Prompt

A modal presented before the Native Browser Prompt and asks if users are interested in signing up.

HTTP Pop-Up Prompt (HTTP-only)

A pop-up window that appears after other prompts that is required for HTTP sites.

Custom Link prompt

A button or link which you can place anywhere on your pages and users can interact with to subscribe.

Step 4. Welcome Notification

Optional: Welcome notifications an optional way to thank users after subscribing to your site. Users will see a welcome notification as soon as they subscribe. You can edit or disable them here.


Step 5. Advanced Options

Optional: Most sites will not have to edit anything in Advanced options. See Web Push Advanced Options to learn more about each option.


Step 6. Upload OneSignal SDK

🚧

HTTPS Only

This option will not be necessary if you selected My Site is Not Fully HTTPS Skip to Step 7.

If you are using our WordPress Plugin, please use our WordPress Setup Guide instead.

Next, you'll need to add the OneSignal SDK files to your site. To do so,

  1. Download the OneSignal SDK files. (You can also download the files here).

  2. Unzip the OneSignal SDK files. There should be two files:

  • https://yoursite.com/OneSignalSDKWorker.js
  • https://yoursite.com/OneSignalSDKUpdaterWorker.js
  1. 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.js
  • https://yoursite.com/OneSignalSDKUpdaterWorker.js

Can these files be served from a subfolder of my site?


Step 7. Add Code to Site

To enable OneSignal on your site, you will need to paste the code from Web Push Settings into 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?

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

Updated 29 days ago



Typical Setup


OneSignal Web Push Setup Guide for typical websites. Works with all Web Push Supported Browsers (Chrome, Firefox, Safari, and more!)

Suggested Edits are limited on API Reference Pages

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