Web push setup
Complete step-by-step guide to set up web push notifications for your website using OneSignal. Learn how to integrate the SDK, configure prompts, and start sending push notifications to engage your users.
Overview
Web push notifications are a powerful way to re-engage users and deliver important information when they’re not actively browsing your website. They support rich content including text, images, action buttons, and can help boost user retention and engagement.
Web push notifications help you reach users even when they're not on your site
For web push to work:
- HTTPS website: Web push only works on secure sites with a valid SSL certificate
- Single domain origin: Must follow the same-origin policy
- User permission: Users must explicitly grant permission to receive notifications
- Supported browsers: Works across most modern browsers (Chrome, Firefox, Safari, Edge)
Important limitations:
- Users cannot subscribe while in Incognito or private browsing mode
- iOS devices require additional setup (see Web push for iOS)
- Some browsers may have notification limits or require user interaction, see Web Push FAQ
This guide walks through every step—from SDK setup to sending personalized push messages—to help you successfully implement OneSignal push notifications.
Web push developer guides
Before you can send web push notifications, your developer needs to complete the following steps.
Not a developer? See Manage Team Members to invite a teammate with developer access to your OneSignal project.
Web SDK setup
Complete guide to installing and configuring the OneSignal Web SDK, including localhost testing and permission prompts.
WordPress plugin
Quickly integrate push notifications on WordPress using our official plugin—no coding required.
iOS web push setup
Follow Apple-specific steps to enable web push on iPhones and iPads running iOS 16.4+.
Migration from another provider
Learn how to transition from another web push provider and retain your subscribers.
Configuration options
Set up your website for web push in the OneSignal dashboard under Settings > Push & In-App > Web.
Activate the web platform in your OneSignal settings
Select the integration type that matches your site:
Choose your integration type based on your website setup
Typical Site
Recommended - Configure prompts, welcome notification, and service worker setup directly in the dashboard—no backend coding required.
WordPress
Use the official OneSignal plugin to easily set up push on your WordPress site with full UI-based configuration.
Custom Code
Full control setup for developers who want to customize everything via code.
Site details:
- Site Name: Used in default notification titles
- Site URL: Must exactly match your domain origin (no paths or
www
mismatch) - Auto Resubscribe: Recommended - Automatically re-subscribes returning users who cleared browser data
- Default Icon URL:
256x256px
image shown in notifications (if unset, a default bell icon is used)
Auto resubscribe
An important concept with web push is that if users clear their browser data, they will stop receiving push notifications. Enable this option to automatically re-subscribe users when they return to your site. See Subscriptions for more details.
Web settings in the OneSignal dashboard
Web permission prompts
Prompting users for notification permission is critical for opt-in. You can customize the behavior and appearance of permission requests based on your setup.
Best practices:
- Use clear messaging that explains the benefit
- Prompt users at the right time (e.g. after engagement)
- Use a pre-prompt before triggering the native browser dialog
Web permission prompts
Compare different prompt types (slidedown, category-based, native, subscription bell, and more) and learn when to use each.
Web SDK reference
Learn how to programmatically control when and how prompts are shown using the SDK.
Welcome notification
You can enable an optional confirmation push that’s sent immediately after a user subscribes. Typical and Wordpress integration can set this in the dashboard.
Welcome notifications confirm successful subscription and demonstrate value
Custom Code integration uses the welcomeNotification
object in the OneSignal.init
function. See Web SDK reference for details.
Why send welcome notifications?
- Let users know they’ve subscribed successfully
- Show what future notifications will look like
- Provide onboarding content or next steps
Understanding users and subscriptions
When a user subscribes to push, OneSignal automatically creates a unique subscription tied to their browser/device.
Web push subscriptions are created when users:
- Grant permission for push notifications on your website using a specific browser and device
- Return to your site after clearing browser data (if Auto Resubscribe is enabled)
- Subscribe from a new browser or device
Important notes:
- Each browser/device combination creates a separate subscription
- Incognito/private browsing mode cannot create subscriptions
- Web push subscriptions remain anonymous until you assign them an External ID
View and manage your subscribers in the Audience section
Users
Learn how to manage users, assign External IDs, and track their activity.
Subscriptions
Understand how subscriptions work across browsers and devices.
Segments
Group users into segments to target based on behavior, device, and more.
iOS Support
Apple added web push support for iPhones and iPads running iOS 16.4+ but with stricter requirements:
- Users must add your site to their Home Screen
- Permission prompts are shown only after that step
- Notifications behave like native app alerts once enabled
Web push for iOS
Step-by-step instructions to enable iOS support, including service worker and manifest setup.
Getting your audience to add to Home Screen
Tips for encouraging users to install your site so they can receive iOS web push.
Design web push notifications
Crafting a good push notification involves more than writing text. Design matters. Learn what elements are customizable and how to use them effectively.
Web push notification anatomy - customize elements 1-6, while 7-9 are controlled by the browser
- Title: Attention-grabbing headline (recommended: under
50
characters) - Message: Main notification content (recommended: under
120
characters) - Icon: Your brand icon or notification-specific image (recommended:
256x256px
PNG or JPG) - Large Image: Eye-catching visual content
- Action Buttons: Call-to-action buttons
- Browser: The browser/app displaying the push
- Domain: Your site origin automatically set by the browser
- Timestamp & Dismiss: Browser adds these controls
- More Options: Browser-specific additional controls
Push overview
Full overview of push notification creation, options, and delivery behavior.
Templates
Save time with reusable templates for consistent messaging.
Message personalization and localization
You can customize push messages to match each user’s preferences and language.
Message Personalization
Insert dynamic variables (like name or preferences) to tailor messages.
Multi-Language Messaging
Automatically deliver messages in each user’s preferred language.
Configure web push behavior
Control how your push messages behave after sending—when they appear, how long they’re stored, and how users interact.
Delivery, display, and dismiss settings
Throttling
Control notification delivery speed.
Frequency Capping
Set limits to prevent over-sending notifications to the same user.
Time To Live (TTL)
Define how long push services retain messages when the device is offline.
Web Push Topic
Use topics to group, replace, or suppress duplicate notifications.
Click behavior
Control what happens when a user clicks a notification.
By default: Clicking opens your homepage.
Customize it:
- Direct users to a specific URL
- Use UTM tracking
- Suppress default behavior with
?_osp=do_not_open
URLs, Links, & Deep Linking
Route users to relevant content or pages using deep links and tracking.
Action buttons
Let users take immediate actions from your notification.
SDK Push Notification Event Listeners
Listen for click events and trigger in-app behavior with custom code.
Test your setup
Before launching, thoroughly test your web push implementation across devices and browsers.
Pre-launch checklist
- SDK is correctly loaded with no errors
- Permission prompt appears and functions
- Test notification is sent and received
- Icons and images render correctly
- Service worker is updated
- HTTPS certificate is valid
Push analytics and troubleshooting
Measure and improve notification performance:
Push message reports
View delivery, open rate, and click-through metrics for each message.
Analytics overview
Explore engagement and user behavior metrics across channels.
Notifications not shown or delayed
Troubleshooting checklist if messages aren’t appearing.
Notification images not showing
Fix image rendering issues across different browsers.
Congratulations! Your web push notification setup is complete.
Next steps:
- A/B Testing: Optimize messages with experiments
- Journeys: Build automated messaging flows
- Tags: Add user-level data for targeting
- Analytics: Track engagement and conversion metrics