puter.notifications.enable()

Websites Puter Apps Node.js Workers

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.

Syntax

puter.notifications.enable()
puter.notifications.enable(options)

Parameters

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.

Return value

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.

Errors

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.

Calls without a click

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.

Examples

Turn on pushes from a button

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

Turn pushes back on at page load

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