Complete guide for setting up OneSignal Web Push notifications using custom code integration. Configure JavaScript SDK, service workers, and Safari certificates for Chrome, Firefox, Safari, and other web browsers.
Only use this Custom Code setup if you need advanced configuration or programmatic control. For most users, we recommend the:
If this is not your first app with OneSignal, click New App/Website. Otherwise, you’ll proceed directly to the setup.
OneSignal dashboard showing the initial app creation screen
Name your app something descriptive (matching your website name is recommended), then select Web from the platform list. Click Next: Configure Your Platform.
Note: You can add additional platforms (iOS, Android, etc.) later in your app’s settings.
Platform selection screen showing Web option highlighted
Select Custom Code. This enables full programmatic control over prompts, timing, and other settings using our JavaScript SDK.
When to choose Custom Code:
Web configuration options with Custom Code selected
Configure your basic site information. These settings affect how notifications appear to users.
Site setup form with required fields highlighted
Field | Description | Requirements |
---|---|---|
SITE NAME | Display name shown in push notifications | Keep it concise and recognizable |
SITE URL | Your complete website URL | Must include https:// and match exactly (include www if used) |
AUTO RESUBSCRIBE | Automatically resubscribes returning users | Recommended: Helps maintain subscriber count |
DEFAULT ICON URL | Icon for prompts and notifications | Square 256x256 pixels, .png/.jpg/.gif format, HTTPS URL required |
Common Gotchas:
www
)OneSignal provides Safari certificates automatically at no cost. Only enable this if you have existing Safari Web Push certificates you need to use.
Safari certificate upload option for existing certificates
If enabled, upload your Safari Web .p12 Push Certificate
and enter the password.
Click Save to continue.
The OneSignal Service Worker is required for push notifications to function. You have two options:
Option 1: Create File Manually (Recommended)
OneSignalSDKWorker.js
Option 2: Download and Upload
OneSignalSDKWorker.js
to your serverDefault Location: The service worker must be accessible at https://yoursite.com/OneSignalSDKWorker.js
Custom Location: If you need to place the file in a subfolder, see our OneSignal Service Worker Guide for detailed instructions.
Need a custom location? For subfolder placement or migrating from another push provider, follow our OneSignal Service Worker Guide.
Service worker file download interface
Legacy Setup Alert: If your site was set up before November 22, 2021, and you’re currently using two service worker files (OneSignalSDKWorker.js
and OneSignalSDKUpdaterWorker.js
), continue hosting both files to prevent service worker issues.
New setups only require the single OneSignalSDKWorker.js
file.
Add this code to your website’s <head>
section. Replace YOUR_ONESIGNAL_APP_ID
with your actual App ID from the OneSignal dashboard.
If you’re using a JavaScript framework, follow these specialized guides:
Common Integration Points:
Service Worker Problems:
OneSignalSDKWorker.js
is accessible at the correct URLNo Bell Icon Appearing:
<head>
sectionNotifications Not Received:
Need Help? If you encounter issues, check our Web Push Troubleshooting Guide or contact support@onesignal.com
for assistance.
After successful setup, consider these advanced features:
Complete guide for setting up OneSignal Web Push notifications using custom code integration. Configure JavaScript SDK, service workers, and Safari certificates for Chrome, Firefox, Safari, and other web browsers.
Only use this Custom Code setup if you need advanced configuration or programmatic control. For most users, we recommend the:
If this is not your first app with OneSignal, click New App/Website. Otherwise, you’ll proceed directly to the setup.
OneSignal dashboard showing the initial app creation screen
Name your app something descriptive (matching your website name is recommended), then select Web from the platform list. Click Next: Configure Your Platform.
Note: You can add additional platforms (iOS, Android, etc.) later in your app’s settings.
Platform selection screen showing Web option highlighted
Select Custom Code. This enables full programmatic control over prompts, timing, and other settings using our JavaScript SDK.
When to choose Custom Code:
Web configuration options with Custom Code selected
Configure your basic site information. These settings affect how notifications appear to users.
Site setup form with required fields highlighted
Field | Description | Requirements |
---|---|---|
SITE NAME | Display name shown in push notifications | Keep it concise and recognizable |
SITE URL | Your complete website URL | Must include https:// and match exactly (include www if used) |
AUTO RESUBSCRIBE | Automatically resubscribes returning users | Recommended: Helps maintain subscriber count |
DEFAULT ICON URL | Icon for prompts and notifications | Square 256x256 pixels, .png/.jpg/.gif format, HTTPS URL required |
Common Gotchas:
www
)OneSignal provides Safari certificates automatically at no cost. Only enable this if you have existing Safari Web Push certificates you need to use.
Safari certificate upload option for existing certificates
If enabled, upload your Safari Web .p12 Push Certificate
and enter the password.
Click Save to continue.
The OneSignal Service Worker is required for push notifications to function. You have two options:
Option 1: Create File Manually (Recommended)
OneSignalSDKWorker.js
Option 2: Download and Upload
OneSignalSDKWorker.js
to your serverDefault Location: The service worker must be accessible at https://yoursite.com/OneSignalSDKWorker.js
Custom Location: If you need to place the file in a subfolder, see our OneSignal Service Worker Guide for detailed instructions.
Need a custom location? For subfolder placement or migrating from another push provider, follow our OneSignal Service Worker Guide.
Service worker file download interface
Legacy Setup Alert: If your site was set up before November 22, 2021, and you’re currently using two service worker files (OneSignalSDKWorker.js
and OneSignalSDKUpdaterWorker.js
), continue hosting both files to prevent service worker issues.
New setups only require the single OneSignalSDKWorker.js
file.
Add this code to your website’s <head>
section. Replace YOUR_ONESIGNAL_APP_ID
with your actual App ID from the OneSignal dashboard.
If you’re using a JavaScript framework, follow these specialized guides:
Common Integration Points:
Service Worker Problems:
OneSignalSDKWorker.js
is accessible at the correct URLNo Bell Icon Appearing:
<head>
sectionNotifications Not Received:
Need Help? If you encounter issues, check our Web Push Troubleshooting Guide or contact support@onesignal.com
for assistance.
After successful setup, consider these advanced features: