puter.notifications.enable() Turns on push notifications for your app in the browser the user is in.
Call it from a click, before any other await. It asks for the browser's permission before anything else, because browsers only show that prompt from a user gesture.
On a website, when the call isn't made from a click, or comes after a sign-in window, another popup, or a few seconds of other work in the same click, it first shows a Puter dialog. The browser's prompt opens when the user clicks Continue there. If they click Cancel, the call resolves false.
On a website, the browser asks on your own origin, and pushes arrive through your service worker (see onPush()). Puter then sends a confirmation push to that browser, which shows once as "Notifications are on". Turning pushes on this way also allows pushes from your app, so the user answers only the browser's prompt.
The call resolves as soon as the browser has answered and Puter has its subscription. It doesn't wait for the confirmation. Pushes start once your page hands the confirmation back, usually within seconds. If the confirmation doesn't arrive within 30 seconds, the onError of onPush() gets push_verification_timeout, or the console does without one, and the next page load tries again.
With only the browser's permission prompt, a user can turn pushes on in up to 5 browsers for your app. With permission granted through Puter's prompt, the limit is 10. Turning them on past the limit removes the least recently seen browser. See push limits.
The choice sticks. Once pushes are on, onPush() keeps the subscription current on later page loads without asking again. After disable(), after the user turns your app off or removes this browser in Puter, after puter.auth.signOut(), or after a different user signs in, page loads don't subscribe again until your page calls enable() from a click.
If the user turned your app off in Puter's settings, the call rejects with push_revoked. To ask again, call requestPermission() from a click, which opens Puter's permission prompt, and then call enable() again.
Pushes on a website need HTTPS, or localhost while you develop. On iOS and iPadOS they need version 16.4 or later and a site the user added to their Home Screen, with a web app manifest that sets "display": "standalone". In a browser that can't receive pushes, the call resolves false.
On a website with nobody signed in, it opens the sign-in after the browser's prompt. Signing the user in first avoids a blocked popup.
Inside the Puter desktop it does what enablePush() does, and it never rejects. When your app doesn't hold the permission yet, that's Puter's permission dialog, and allowing it also turns pushes on in this browser.
puter.notifications.enable()
puter.notifications.enable(options)
options (Object) (optional)
| Option | Type | Description |
|---|---|---|
serviceWorker |
String |
The path of the worker that imports push-sw.js. Defaults to /puter-sw.js. Pass the same path to onPush(), disable() and status(). Only used on a website. |
background |
Boolean |
Turn pushes back on without a click, only where the browser already granted permission and, on a website, the user turned them on here with a click and hasn't turned them off since. Opens no prompt, dialog or sign-in. Defaults to false. See Calls without a click. |
A Promise that resolves to true when this browser receives pushes for your app, and false when the user didn't allow notifications, canceled Puter's dialog, or the browser can't receive pushes, such as a private window or an iPhone page that isn't opened from the Home Screen. Where pushes work lists what each browser needs.
The promise rejects with an error carrying message and code:
code |
Meaning |
|---|---|
push_unavailable |
This server has no push notification service, as on most self-hosted servers. |
push_disabled |
This server has push notifications turned off. |
push_revoked |
The user turned your app off in Puter's settings. Call requestPermission() from a click, then call enable() again. With background: true, later background calls resolve false. |
push_device_removed |
The user removed this browser in Puter, and the fresh subscription was also refused. With background: true, the user removed this browser in Puter, and later background calls resolve false. |
push_worker_unavailable |
The service worker couldn't be registered or didn't start, for example because nothing is served at its path. |
push_worker_conflict |
Another service worker controls the scope. Add the importScripts() line to that worker and pass its path as serviceWorker. |
push_subscription_conflict |
The worker already has a push subscription from another service, such as Firebase or OneSignal. Give Puter its own worker in a folder, such as /puter/puter-sw.js, and pass that path as serviceWorker. A subscription Puter made earlier, even with a key Puter has since changed, is replaced instead. |
push_subscribe_failed |
The browser couldn't create a push subscription, usually because it couldn't reach its push service. |
push_subscription_invalid |
The browser's push service refused the subscription, even after a fresh one. |
push_endpoint_revoked |
Another Puter account turned your app off on this browser's subscription, and a fresh subscription couldn't replace it. |
push_challenge_failed |
Puter couldn't reach the browser's push service to send the confirmation. Try again later. |
push_verification_canceled |
disable() was called before this call finished. |
bad_request |
The browser's subscription isn't in a format or from a push service this server accepts. |
forbidden |
The call isn't from a signed-in browser session of the app. |
origin_mismatch |
The request's origin doesn't belong to the app making the call. |
too_many_requests |
Pushes were turned on too many times in a short time. Try again later. |
auth_canceled |
Nobody was signed in, and the user closed the sign-in without finishing it. |
reauth_required, token_auth_failed |
The user's session is no longer valid. On a website with background: true, the call rejects with one of these instead of opening the sign-in. |
notifications_failed |
The server sent a response the SDK couldn't read. |
With background: true, enable() runs without a click, for example on page load, and never opens the browser's prompt, Puter's dialog or the sign-in. On a website it turns pushes back on only for a signed-in user who turned them on in this browser with a click and hasn't turned them off since, whether with disable(), by removing this browser in Puter, or by turning your app off in Puter. Otherwise, or when the browser hasn't already granted notification permission, it resolves false and sends no push registration. It also resolves false when pushes are turned off here or elsewhere while it runs.
A browser the user removed in Puter stays removed. When the user removed this browser or turned your app off in Puter and this browser hasn't learned it yet, the call rejects once with push_device_removed or push_revoked, and later calls resolve false.
Inside the Puter desktop it resolves whether pushes are already on, as status() reports, without opening Puter's permission dialog.
<html>
<body>
<script src="https://js.puter.com/v2/"></script>
<button id="enable">Turn on notifications</button>
<script>
document.getElementById('enable').addEventListener('click', async () => {
try {
const on = await puter.notifications.enable();
puter.print(on ? 'Notifications are on<br>' : 'Notifications are off<br>');
} catch (error) {
puter.print(`Could not turn on notifications: ${error.code}<br>`);
}
});
</script>
</body>
</html>
<html>
<body>
<script src="https://js.puter.com/v2/"></script>
<script>
(async () => {
try {
// Resolves false without asking unless the user turned pushes on here with a click.
const on = await puter.notifications.enable({ background: true });
puter.print(on ? 'Notifications are on<br>' : 'Notifications are off<br>');
} catch (error) {
puter.print(`Could not turn on notifications: ${error.code}<br>`);
}
})();
</script>
</body>
</html>