Web push setup

​

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

---

​

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:
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 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

---

​

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

​

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

---

​

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.

1. Title: Attention-grabbing headline (recommended: under 50 characters)
2. Message: Main notification content (recommended: under 120 characters)
3. Icon: Your brand icon or notification-specific image (recommended: 256x256px PNG or JPG)
4. Large Image: Eye-catching visual content
5. Action Buttons: Call-to-action buttons
6. Browser: The browser/app displaying the push
7. Domain: Your site origin automatically set by the browser
8. Timestamp & Dismiss: Browser adds these controls
9. More Options: Browser-specific additional controls

​

Message personalization and localization

You can customize push messages to match each user’s preferences and 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

​

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

---

​

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:

---

---