Web push in Safari on macOS: what differs from Chrome and Firefox

Safari on macOS has received web push notifications since Safari 16.1 on macOS 13 Ventura, using the same standard as Chrome and Firefox and without asking people to install anything. The differences are in the details: permission can only be requested from a click, every push must show a notification, several design options are ignored, and macOS settings decide whether the notification is ever seen.

In short:

• Requirements: macOS 13 Ventura or later, Safari 16.1 or later and a site served over HTTPS. No Apple Developer account needed.
• Subscribing has to start directly inside the click handler, with nothing awaited before it.
• Safari shows the title and body; it ignores images, buttons and requireInteraction, and icon and tag have no effect.
• If a push arrives and no notification is shown, Safari revokes the subscription.
• If a notification shows as delivered but you never saw it, check Focus and the alert style in macOS settings.

Supported versions and requirements

Web push reached the Mac with Safari 16.1 on macOS 13 Ventura in October 2022; older macOS releases do not get it, even with an updated Safari. It follows the standard, so you need neither a separate integration for Safari nor an Apple Developer Program membership, as WebKit confirms in Meet Web Push. Tutorials about a "Website Push ID" and certificates describe Safari's older system, which a new site does not need.

Unlike iPhone, where the site must be added to the Home Screen first, the Mac requires no installation: people subscribe from a regular tab. If they also add your site to the Dock (macOS 14 Sonoma or later), that web app has its own permission, accepted inside the web app.

With castly there is nothing Safari-specific to configure: the same SDK and the same one-line service worker, importScripts('https://castly.sh/sdk/v1/sw.js') in /castly-sw.js, cover every browser.

Permission only from a click

Safari only lets a site request notification permission in response to a user gesture, such as clicking a button. And there is a subtlety that breaks many integrations: subscribing has to start directly inside the click handler. If you wait for something else first, like loading preferences from your server, Safari may no longer connect the request to the click and reject it.

// Good: subscribing is the first thing that happens after the click
button.addEventListener('click', async () => {
  await Castly.subscribe({ userId: user.id });
  const prefs = await fetch('/api/preferences').then((r) => r.json());
  await Castly.setTags(prefs);
});

// Risky: the await before subscribing can break the link to the gesture
button.addEventListener('click', async () => {
  const prefs = await fetch('/api/preferences').then((r) => r.json());
  await Castly.subscribe({ tags: prefs });
});

The opt-in prompt you configure in the dashboard already works this way: it shows your message and requests permission when the person clicks its button. Keep in mind that people can uncheck "Allow websites to ask for permission to send notifications" under Safari › Settings › Websites › Notifications; then they will never see your request.

How notifications look on the Mac

Safari hands notifications to macOS Notification Center: they appear as a banner or alert in a corner of the screen, stay in Notification Center afterwards and open the notification's URL when clicked. But Safari ignores much of what other browsers display:

Design every notification to make sense with a title, body and link alone: if you send image through the API, Chrome will show it and Safari will not. And because tag replaces nothing, three updates about the same order become three notifications on the Mac, so send only the changes that matter.

macOS settings that can hide them

A notification reaching the Mac does not guarantee anyone sees it. macOS treats every site with permission like an app: it is listed under System Settings › Notifications, where the person chooses the alert style (None, Banners or Alerts), whether it stays in Notification Center and whether it plays a sound.

• Style set to None. Nothing appears on screen, although the notification may still be kept in Notification Center.
• Focus. While a Focus is on, Do Not Disturb included, notifications from apps that are not allowed are silenced and wait in Notification Center. It may be scheduled, for example, overnight or during work hours.
• Screen sharing. When the display is shared or mirrored, macOS hides notifications unless that is allowed in the same settings.
• Per-site permission. Under Safari › Settings › Websites › Notifications, every site is set to Allow or Deny.

Two takeaways for your product: for anything critical, offer a second channel, such as email. And when someone says "I'm not getting notifications," first check whether the dashboard shows that notification as delivered to their device: if it does, the cause is one of these settings, not the send.

Every push must show a notification

Safari does not allow invisible pushes. When subscribing, a site promises that every message will end in a visible notification, and if the service worker receives one and shows nothing, Safari revokes the subscription. Two ideas that sound reasonable and fail in Safari: skipping the notification when the person already has your site open, and using push to sync data in the background.

castly's service worker shows a notification for every push sent from your project, so this rule is covered. If you add its line to your own service worker that handles other pushes, those must end in something visible too. A subscription revoked this way later shows up as an expired subscription.

Declarative Web Push

Since Safari 18.5, which can also be installed on Sonoma and Ventura, Safari understands Declarative Web Push: the message itself describes the notification and the browser displays it without running JavaScript, so something visible is always shown and battery is saved. Browsers that do not understand it hand the message to the service worker, but Chrome and Firefox do not fully support it yet: for now it is a Safari enhancement, not a replacement for the service worker. The details are in Meet Declarative Web Push.

How to test it on your Mac

1. Subscribe like a user. Open your site over HTTPS in Safari and click your enable-notifications button.
2. Use test devices. From the dashboard's Playground you can subscribe your browser as a test device and send it a push without bothering anyone else, or do it through the API with { "type": "test" }.
3. Follow the trail. The notification's detail shows the device moving through sent, delivered and clicked.
4. Check the click and replay the first visit. Confirm the notification opens the right page, then remove your site under Safari › Settings › Websites › Notifications to see the permission request again.
5. Test the Dock separately. If your users add the site to the Dock, repeat the flow inside the web app, which has its own permission.

If you have not integrated yet, the quickstart gets you to a first push in a few minutes.

Frequently asked questions

Do I need an Apple Developer account to send push to Safari?

No. Since Safari 16.1, Safari uses standard Web Push, just like Chrome and Firefox, and the old system with a Website Push ID and certificates is not needed for new sites.

Why did Safari stop receiving my notifications?

The most common causes are that the person revoked permission, cleared the site's data, or that a push arrived without showing a notification and Safari revoked the subscription. In those cases the subscriber usually shows up as expired after the next send.

Do images and buttons in my notifications show up in Safari?

No. Safari on macOS shows neither image nor actions, so the notification has to make sense from its title and body. Images still appear in browsers that support them.

Which macOS version do I need?

macOS 13 Ventura or later, with Safari 16.1 or newer. Declarative Web Push requires Safari 18.5 or later.