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

Custom Code Setup

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


For Advanced Users Only

You should only use custom code if you absolutely need it. Otherwise, we recommend using the Web Push Typical Setup or if using WordPress, see our WordPress Setup.

Step 1. Choose Integration

Select Custom Code if you are adding our Javascript code to your site.

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

Image shows Web Config optionsImage shows Web Config options

Image shows Web Config options

Step 2. Site Setup

Input your default site information.

Image showing Site Setup stepImage showing Site Setup step

Image showing Site Setup step




The default name to call your site used in push notifications.


Your website URL including:

  • http:// or https://
  • www or non-www links (e.g.,

Trying to test locally, see Local Testing Setup


Recommended: Allows push subscribers to automatically resubscribe upon returning to your site without being prompted if they clear their browser data or if you are transferring to OneSignal from another push provider.


Icon used for the Slide Prompt and default for push notifications.

Enter an https icon URL or upload file that is square 256x256 pixels.

The file must be .png, .jpg, or .gif.

My site is not fully HTTPS

Select this checkbox if any apply:

  • you have an HTTP website
  • your site is hosted by




The subdomain label used for push subscription. See Web Push HTTP vs. HTTPS for more details.

Step 3. Advanced Push Settings

Safari - Custom Certificate (Optional)

OneSignal automatically provides the necessary certificates to work with Safari Browsers at no additional cost. If you already have your own Safari Web Push Certificates, toggle on this option to upload your Safari Web .p12 Push Certificate and password.

Step 4. Upload Files

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

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

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

  1. The OneSignal SDK files must be publicly accessible and can be placed at the top-level root of your site. If you want to place them in a subfolder you can! Please see our OneSignal Service Worker Guide for instructions.

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

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

Step 6. Add your first user

Go to your website and you should see the OneSignal Bell Prompt. Click it to see the native browser prompt and subscribe to push. Then send yourself a Push Notification.


Setup Complete!

If you are having difficulty, please check Web Push Troubleshooting or contact [email protected] for assistance.

Updated 3 months ago

Custom Code Setup

OneSignal Web Push Setup Guide for 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.