Only use this Custom Code setup if you need advanced configuration or programmatic control. For most users, we recommend the:

​
Prerequisites

  • A OneSignal account
  • A website with HTTPS (required for web push notifications)
  • Access to modify your website’s HTML and upload files to your server
  • Basic understanding of JavaScript (helpful but not required)

​
Creating Your OneSignal App

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

​
1. Choose Integration

Select Custom Code. This enables full programmatic control over prompts, timing, and other settings using our JavaScript SDK.

When to choose Custom Code:

  • Need to customize notification prompts
  • Want to control when users are prompted
  • Require advanced segmentation or targeting
  • Building a single-page application (SPA)

Web configuration options with Custom Code selected

​
2. Site Setup

Configure your basic site information. These settings affect how notifications appear to users.

Site setup form with required fields highlighted

FieldDescriptionRequirements
SITE NAMEDisplay name shown in push notificationsKeep it concise and recognizable
SITE URLYour complete website URLMust include https:// and match exactly (include www if used)
AUTO RESUBSCRIBEAutomatically resubscribes returning usersRecommended: Helps maintain subscriber count
DEFAULT ICON URLIcon for prompts and notificationsSquare 256x256 pixels, .png/.jpg/.gif format, HTTPS URL required

Common Gotchas:

  • Site URL must match exactly (with or without www)
  • Icons must be served over HTTPS
  • For local testing, see Local Testing Setup

​
3. Advanced Push Settings

​
Safari Web Push Certificate (Optional)

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.

​
4. Upload Service Worker Files

The OneSignal Service Worker is required for push notifications to function. You have two options:

1

Option 1: Create File Manually (Recommended)

  1. Create a new file named OneSignalSDKWorker.js
  2. Add this single line of code: 
    importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
  3. Upload the file to your website’s root directory
2

Option 2: Download and Upload

  1. Download the OneSignal SDK files
  2. Unzip the download
  3. Upload OneSignalSDKWorker.js to your server

​
File Hosting Requirements

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

​
5. Add Code to Your Website

​
Basic Implementation

Add this code to your website’s <head> section. Replace YOUR_ONESIGNAL_APP_ID with your actual App ID from the OneSignal dashboard.

<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
<script>
  window.OneSignalDeferred = window.OneSignalDeferred || [];
  OneSignalDeferred.push(function(OneSignal) {
    OneSignal.init({
      appId: "YOUR_ONESIGNAL_APP_ID",
      safari_web_id: "YOUR_SAFARI_WEB_ID", // Only needed if using custom Safari certificate
      notifyButton: {
        enable: true, // Shows the OneSignal bell icon
      },
    });
  });
</script>

​
Framework-Specific Setup

If you’re using a JavaScript framework, follow these specialized guides:

​
Next Steps After Code Installation

  1. Initialize the SDK: The code above handles basic initialization
  2. Configure Prompting: Set up when and how users are prompted - see Permission Requests
  3. Add Custom Logic: Use the Web SDK Reference for advanced features

Common Integration Points:

  • Custom prompt timing based on user behavior
  • Segmentation and user tagging
  • Event tracking and analytics
  • A/B testing different notification strategies

​
Test Your Setup

​
Verify Installation

  1. Visit your website - you should see the OneSignal bell icon (if enabled)
  2. Click the bell to trigger the browser’s native permission prompt
  3. Subscribe to notifications
  4. Check browser console for any JavaScript errors

​
Send Test Notification

  1. Find your test subscription: Follow Find & Set Test Subscriptions
  2. Send a test push: Use our guide to send yourself a Push Notification
  3. Verify delivery across different browsers and devices

​
Troubleshooting Common Issues

Service Worker Problems:

  • Ensure OneSignalSDKWorker.js is accessible at the correct URL
  • Check that the file contains the correct import statement
  • Verify HTTPS is working properly

No Bell Icon Appearing:

  • Confirm the JavaScript code is in the <head> section
  • Check browser console for errors
  • Verify your App ID is correct

Notifications Not Received:

  • Test in an incognito/private browser window
  • Ensure notifications are enabled in browser settings
  • Check that your site is served over HTTPS

Need Help? If you encounter issues, check our Web Push Troubleshooting Guide or contact [email protected] for assistance.

​
What’s Next

After successful setup, consider these advanced features: