> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Web push setup
> Set up web push notifications with OneSignal to re-engage Users across Chrome, Firefox, Safari, and Edge.
Web push notifications re-engage Users with timely content — even when they're not actively browsing your website. They support rich content including text, images, action buttons, and sounds.
For web push to work:
* **HTTPS website**: Web push only works on secure sites with a valid SSL certificate
* **Service worker**: You must be able to add the [OneSignal service worker](./onesignal-service-worker) to your website
* **Single domain origin**: Must follow the [same-origin policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy)
* **User permission**: Users must explicitly grant permission to receive notifications
* **Supported browsers**: Works across most modern browsers (Chrome, Firefox, Safari, Edge)
- **Incognito mode**: Users cannot subscribe while in incognito or private browsing mode.
- **iOS**: Requires additional setup — see [Web push for iOS](./web-push-for-ios).
- **Browser limits**: Some browsers may have notification limits or require user interaction — see [Web push FAQ](./web-push-setup-faq).
***
## Web push developer guides
Before sending web push notifications, complete the following setup steps.
Not a developer? See [Manage team members](./manage-team-members) to invite a teammate with developer access to your OneSignal project.
Install and configure the OneSignal Web SDK, including localhost testing and permission prompts.
Follow Apple-specific steps to enable web push on iPhones and iPads running iOS 16.4+.
Transition from another web push provider and retain your Subscriptions.
Integrate push notifications on WordPress using the official plugin — no coding required.
Integrate Shopify with OneSignal through the Vendo integration for web push, custom events, and customer identification.
***
## Configuration options
Set up your website for web push in the OneSignal dashboard under **Settings > Push & In-App > Web**.
Select the integration type that matches your site:
**Recommended** — Configure prompts, welcome notification, and service worker setup directly in the dashboard.
Use the official OneSignal WordPress plugin and configure prompts and welcome notification directly in the dashboard.
Full control 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
If Users clear their browser data, they stop receiving push notifications. Enable this option to automatically re-subscribe Users when they return to your site. See [Subscriptions](./subscriptions) for more details.
***
### Web permission prompts
Customize when and how the notification permission prompt appears to maximize opt-in rates.
Use clear messaging that explains the benefit, prompt Users at the right time (e.g., after engagement), and use a pre-prompt before triggering the native browser dialog.
Compare different prompt types (slidedown, category-based, native, subscription bell, and more).
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 integrations can set this in the dashboard.
Custom Code integration uses the `welcomeNotification` object in the `OneSignal.init` function. See [Web SDK reference](./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
***
## Users and Subscriptions
When a User subscribes to push, OneSignal automatically creates a unique Subscription tied to their browser and 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
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](./users#external-id).
Manage Users, assign External IDs, and track their activity.
How Subscriptions work across browsers and devices.
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+ 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
Step-by-step instructions to enable iOS support, including service worker and manifest setup.
***
## Design web push notifications
Web push notifications support titles, messages, icons, images, and action buttons. The diagram below shows which elements you can customize.
**Customizable elements:**
1. [Title](./push#title): Attention-grabbing headline (recommended: under 50 characters)
2. [Message](./push#message): Main notification content (recommended: under 120 characters)
3. [Icon](./notification-icons): Your brand icon or notification-specific image (recommended: `256x256px` PNG or JPG)
4. [Large image](./push#image): Eye-catching visual content
5. [Action buttons](./action-buttons): Call-to-action buttons
**Browser-controlled elements (not customizable):**
6\. Browser: The browser/app displaying the push
7\. Domain: Your site origin, automatically set by the browser
8\. Timestamp and dismiss: Browser-added controls
9\. More options: Browser-specific additional controls
Full overview of push notification creation, options, and delivery behavior.
Save time with reusable templates for consistent messaging.
### Personalization and localization
Customize push messages to match each User's preferences and language.
Insert dynamic variables like name or preferences to tailor messages.
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
Control notification delivery speed.
Set limits to prevent over-sending notifications to the same User.
Define how long push services retain messages when the device is offline.
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`
Route Users to relevant content or pages using deep links and tracking.
Let Users take immediate actions from your notification.
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 console errors
* Permission prompt appears and functions correctly
* Test notification is sent and received
* Icons and images render correctly
* Service worker is registered and up to date
* HTTPS certificate is valid
### Analytics and troubleshooting
Measure notification performance and resolve common delivery issues.
View delivery, open rate, and click-through metrics for each message.
Explore engagement and User behavior metrics across channels.
Troubleshooting checklist if messages aren't appearing.
Fix image rendering issues across different browsers.
***
## Next steps
Optimize messages with experiments to find what drives engagement.
Build automated, multi-step messaging flows triggered by User behavior.
Add custom properties to users for personalization and segmentation.
***
## FAQ
### Can Users subscribe to web push on iOS?
Yes, starting with iOS 16.4+. Users must first add your website to their Home Screen, then grant notification permission. See [Web push for iOS](./web-push-for-ios) for the full setup steps.
### Why did a User stop receiving web push notifications?
The most common cause is that the User cleared their browser data, which removes the push Subscription. Enable **Auto Resubscribe** in your web push settings to automatically re-subscribe returning Users. See [Subscriptions](./subscriptions) for details.
### Do web push notifications work in incognito or private browsing mode?
No. Users cannot subscribe to web push while in incognito or private browsing mode. Subscriptions created in a normal session are not accessible in private mode.
### What browsers support web push notifications?
Chrome, Firefox, Safari (macOS and iOS 16.4+), and Edge all support web push. Each browser may have different prompt behavior and notification display. See [Web push FAQ](./web-push-setup-faq) for browser-specific details.
### Can I use subdomains with web push?
Each subdomain (e.g., `app.example.com` vs `shop.example.com`) is a separate origin. Browsers enforce the [same-origin policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) for web push, so each subdomain requires its own OneSignal App. The service worker must also be hosted on the same origin as the subscribing page — CDNs and other subdomains are not allowed. See [Multiple sites & subdomains](./web-push-setup-faq#multiple-sites--subdomains) for setup options.
### How do I register more than one domain for web push?
You need a separate OneSignal app for each domain or subdomain. A single OneSignal app can only serve one origin. To manage multiple domains, either redirect Users to a single origin for subscription or create individual OneSignal apps per origin. See [Multiple sites & subdomains](./web-push-setup-faq#multiple-sites--subdomains) for detailed strategies.
### Why is my web push prompt not showing?
Common causes include: the site is not served over HTTPS, the service worker is not registered correctly, the User already granted or denied permission, or the User is in incognito mode. Check the browser console for errors and see [Notifications not shown](./notifications-not-shown-web-push) for a full checklist.