Web and app push

Send notifications to your website visitors, your Android and iPhone apps and from your own server, and ask for permission in a way that gets a yes and keeps it.

Push notifications reach a person even when your website or app is closed. You make one app in the dashboard for each website or mobile app. Each app has a public app key, which is safe to put in a page or an app. Your API key stays on your server.

You haveHow it worksRead
A website, on any stackA small worker file on your site and one script tag. People are asked on your pages.Website quick start, then Asking for permission properly
A React or Next.js siteThe same file and tag. Your own button calls window.SlidePush.Website quick start, then Ask with your own button
An Android appSlide Connect: one secure connection from your app. Nothing from Google is needed in the app.Android and iPhone
An iPhone or iPad appApple push, with your own Apple notification key. It does not use Slide Connect.Android and iPhone
Your own serverOne API call with an API key that has the push:send scope.Send from your server

On a Shopify store there is nothing to download: Slide's own tracking on your store loads the notification prompt and its worker for you. Check that your website shows as verified in Tracking & sites.

  1. 1Open Web and App Push, then Setup, and make an app for your website. Open How to install.
  2. 2Download the worker file and put it in the top folder of your website, so it opens at yourwebsite.com/slide-push-sw.js.
  3. 3Copy the script tag and add it to every page of your website, just before </body>. It already has this app's key in it.
  4. 4Check that Tracking & sites shows your website as verified.
  5. 5Send yourself a test from the Setup page and see it arrive.

The worker file is two lines. Copy it from the dashboard instead of typing it: it carries your app key and the right address. It looks like this.

js
self.__SLIDE_PUSH={app:"pk_live_YOUR_APP_KEY",api:"https://slide.synquic.com"};
importScripts("https://slide.synquic.com/api/v1/push/client/worker.js?v=1");

The script tag, with your own key in place of the example:

html
<script async src="https://cdn.synquic.com/widget/slide-push.min.js" data-app="pk_live_YOUR_APP_KEY"></script>
  • The worker file must be served from your own domain, because a browser only installs a service worker from the same address as the page. It loads Slide's worker, so an update never needs a change on your site.
  • Import the worker from https://slide.synquic.com/api/v1/push/client/worker.js, as the dashboard's file does. Do not copy a hashed file address from another site's worker: that file is replaced when a new worker is published.
  • Your pages must be on https. localhost also works while you build.
  • The page must be on the website you verified in Tracking & sites (or an extra domain you added to it). A page on another address is refused when it registers.
  • If the worker has to live at another path, add data-worker="/your-path.js" (and data-scope) to the script tag. The default is /slide-push-sw.js with the scope /slide-push/, which is narrow on purpose so it never replaces a worker you already have.

With the tag alone, Slide asks for you. On the person's second page view, it shows its own short dialog: a title, a sentence, Allow, Maybe later and No thanks. The browser's own prompt appears only after the person taps Allow. These are the defaults, and you can change the wording, the style, how many page views or seconds to wait, and how long to stay quiet in the app's prompt settings.

The personWhat Slide does
Taps AllowStarts the browser prompt, inside that tap. If the person allows, the browser is subscribed and Slide stores the exact words the person saw as their consent.
Taps Maybe laterDoes not ask again for 14 days. Three of these in a row count as No thanks.
Taps No thanksDoes not ask again for 90 days.
Closes the browser prompt without choosingDoes not ask again for 30 days, so the person is not pushed towards blocking the site.
Blocks notifications in the browserNever shows a dialog again: a blocked site cannot be asked.
Is on a browser that cannot keep an answerIs not asked by itself, because a No that cannot be remembered would come back on every page.

The script puts window.SlidePush on the page. Every method answers, none of them throws into your page.

MethodWhat it does
init({ appKey })Starts it. It runs by itself when the tag has data-app, so you only call it when you load the script without the attribute. Answers { supported, state, reason? }.
isSupported()True when this browser can do web push on this page. False in an iPhone browser tab.
permissionState()One word: unsupported, needs-install, default, granted or denied. It answers at once, with no request.
softAsk(options)Shows Slide's own dialog, then the browser prompt only after Allow. Options: title, body, allowLabel, laterLabel, noLabel, style ("card" or "bar"), color, userInitiated, verify (default false: runs verify() once after the person subscribes). Answers { outcome, reason?, verify? }.
subscribe({ consent: { wording } })For a page with its own ask. Needs the words the person saw. With no words it refuses and nothing is requested. Answers { ok, reason?, installationId? }.
unsubscribe()Turns notifications off in this browser and tells Slide. The dialog does not come back by itself for the No thanks wait.
link({ externalUserId })Ties this browser to your own id for the person, so your server can send to that person. Does nothing before the person subscribed.
testNotification(options)Shows one local test notification through your worker, to check that the person can see banners. Local only: no request is made and nothing is sent to Slide. It needs the browser permission to be granted and never asks for it. Options: title, body. Answers { shown, reason? }, where reason is unsupported, not_granted, no_worker or error.
verify(options)Runs testNotification, then asks "Did you see a notification?". If the person says no, it shows short steps for their system (Mac, Windows, Android, iPhone and iPad, or another) and a Test again button. Local only. Options: title, body, style ("card" or "bar"), color. Answers { outcome, reason? }, where outcome is seen, not-seen or skipped.

The browser prompt is a one way door. If the person blocks it, your page cannot ask again, and only the person can undo it in the browser settings. So ask in two steps: your own plain question first, and the browser prompt only after the person says yes.

  • Never on the first page view. Wait until the person has seen something worth hearing about. Slide's default is the second page view.
  • Always from a tap or a click. Notification.requestPermission() should be called from a user gesture such as a click, and Firefox 72 and later rejects a prompt that was not triggered by one.
  • Say what the person gets and that they can stop. Slide keeps the exact words the person saw with their consent.
  • Remember the answer. After Maybe later or No thanks, wait days, not pages. The Slide dialog does this for you.
  • On iPhone and iPad, notifications work only for a site added to the Home Screen, and only after a tap in that app.

Two ways to ask from a control of your own, such as "Tell me when it is back". With softAsk, Slide shows its dialog when your button is tapped. The wait after a Maybe later or No thanks does not apply, because the person just asked.

js
document.querySelector("#notify").addEventListener("click", async () => {
  const result = await window.SlidePush.softAsk({
    userInitiated: true,
    title: "Get a note when it is back",
    body: "We will tell you once. You can turn it off any time.",
  });
  // result.outcome: subscribed, later, no, denied, dismissed, install-hint or skipped
});
outcomeMeaningWhat to do
subscribedThe person is on.Confirm it. Call link({ externalUserId }) if you send by your own user id.
laterThe person closed the dialog with Maybe later.Nothing. Slide waits before it asks again.
noThe person chose No thanks.Nothing. Do not offer it again soon.
deniedThe browser is blocking this site.Show your own steps to unblock it, as below.
dismissedThe browser prompt was closed with no choice.Nothing. Slide waits 30 days before it asks again.
install-hintiPhone or iPad in a browser tab: Slide showed "Add this site to your Home Screen first".Nothing more. The person adds the site and opens it from there.
skippedNo dialog was shown. reason says why: unsupported, denied, already, cooldown, no_storage, app_off, not_ready, busy or error.Nothing, or hide your button for unsupported, denied and already.

With subscribe, you draw the dialog yourself. You must pass the words the person saw. Read permissionState() first and show only what can work.

permissionState()What it meansWhat to show
unsupportedThis page cannot do web push: it is not on https, the browser has no push, an iPhone or iPad is older than iOS 16.4, or it is the browser inside another app.Nothing. Hide the control rather than show a button that cannot work.
needs-installiPhone or iPad, in a browser tab rather than a Home Screen app.Short steps instead of a button: tap Share, then Add to Home Screen, then open the site from there. Your site needs a web manifest with display set to standalone or fullscreen, which is what makes it a Home Screen web app.
defaultThe person has not been asked.Your button. Ask on the tap.
grantedThe browser allows notifications for your site.Your "on" state. See the note below.
deniedThe browser blocks notifications for your site.Your own unblock steps, no button.

granted reports the browser's setting for your site only. It does not say that Slide holds a subscription for this person, and it stays granted after unsubscribe(). When it is granted, subscribe() subscribes at once without a prompt, so keep your own on or off flag if you show a switch.

html
<button id="notify" hidden>Turn on notifications</button>
<p id="notify-help" hidden></p>

<script>
  var WORDING = "Get order updates and offers as notifications. Turn off any time.";
  var button = document.getElementById("notify");
  var help = document.getElementById("notify-help");

  var HELP = {
    denied: "Notifications are blocked for this site. Open your browser's settings for this site, set Notifications to Allow, then reload this page.",
    "needs-install": "On iPhone and iPad, add this site to your Home Screen first: tap Share, then Add to Home Screen, then open it from there."
  };

  function render(push) {
    var state = push.permissionState();
    button.hidden = state !== "default";
    help.hidden = !HELP[state];
    help.textContent = HELP[state] || "";
  }

  // The Slide script loads after the page, so wait for it.
  function whenReady(done) {
    if (window.SlidePush) return done(window.SlidePush);
    var timer = setInterval(function () {
      if (window.SlidePush) { clearInterval(timer); done(window.SlidePush); }
    }, 100);
  }

  whenReady(function (push) {
    render(push);
    button.addEventListener("click", async function () {
      var result = await push.subscribe({ consent: { wording: WORDING } });
      if (!result.ok) console.log("Not subscribed:", result.reason);
      render(push);
    });
  });
</script>

When permissionState() says denied, the person (or a browser setting) has set Notifications to Block for your site. Your page cannot ask again, so give two short steps of your own. These are the steps in the vendors' own help pages.

BrowserHow the person unblocks your site
Chrome on a computerOn your site, click the icon at the left of the address bar (View site information) and turn on Notifications. Or open Settings, Privacy and security, Site settings, Notifications, and make sure your site is not under "Not allowed to send notifications". Then reload.
Chrome on AndroidOpen your site, tap More, then Site controls, then Permissions, then Notifications, and turn Notifications on.
Safari on a MacOpen Safari, then Settings, then Websites, then Notifications, and check what your site is set to. Apple also lists each website under System Settings, Notifications, Application Notifications.
Other browsersOpen the site settings or permissions for your site, from the icon at the left of the address bar or from the browser's settings, and set Notifications to Allow. The menu names differ by browser and version.

Allowing the site in the browser is only the first of two switches. The operating system also has a switch for the browser app itself. See "Test it, and fix "I did not see it"" below.

No, not for a public website. A page cannot switch notifications on by itself. The browser grants permission only from the person's own choice in its prompt, and a page cannot read or change the operating system's own notification switch for the browser app. Notification.permission only reports the browser's setting for your site: default, granted or denied.

What you can do, and should:

  • Ask clearly, at a good moment, from a tap, with your own words first and the browser prompt second.
  • Remember a Maybe later or a No thanks and wait before you ask again. Slide does this by default.
  • Detect denied and show your own short steps to unblock the site.
  • Detect needs-install on iPhone and iPad and show the Add to Home Screen steps.
  • Tell people what they get. A person who knows what the notifications are for says yes more often, and keeps them.

There is one exception, and it is not for a public site: browsers on devices a company manages. The company's IT team can set a policy on its own devices. Chrome and Edge have the policies NotificationsAllowedForUrls and DefaultNotificationsSetting. Firefox has Permissions, then Notifications, in its policies.json, with the values Allow, Block, BlockNewRequests and Locked. If you build an internal tool for a company that manages its browsers, give its IT team those names. Slide and your website cannot set them.

Do not ask on page load, do not ask on every page, and do not fake the browser prompt. A Block is rarely undone, and it is final for that person on your site.

  1. 1Open your site on the device you will test with, and say yes to the prompt.
  2. 2In the dashboard, open Web and App Push, then Setup, then Send yourself a test. Pick the app and the device that said yes, and send.
  3. 3Watch for the banner. If it does not come, work down the table below.

Read the delivery report carefully. Delivered means the browser received the message. Shown means the browser accepted the notification to show. Neither can see the operating system. If the operating system blocks banners for the browser app, Slide still reports delivered and shown, and nothing appears on the screen.

This happened for real: on a Mac, a test was delivered and reported as shown, and no banner came. The browser was a Chromium browser that reports itself as Chrome. The cause was the macOS notification setting for that browser app, which was set to Denied. After it was allowed in System Settings, the same test showed a banner.

What you seeLikely causeFix
Delivered and shown in Slide, no banner, on a MacmacOS notifications for the browser app are off.Apple menu, System Settings, Notifications. Under Application Notifications, choose the browser and turn on Allow notifications. Use the browser app's own name, not "Chrome".
Delivered and shown, no banner, on WindowsNotifications for the browser are off, or Do Not Disturb is on.Start, Settings, System, Notifications. Turn notifications on, then find the browser under "Notifications from apps and other senders" and switch it on. With Do Not Disturb on, banners show only for alarms, reminders and the apps you chose, and the rest go to the notification center.
Delivered and shown, no banner, on AndroidAndroid's notification setting for the browser app is off.Settings, Notifications, App notifications. Choose the browser and switch its notifications on. Menu names vary by phone and maker.
Nothing on an iPhone or iPadThe site was opened in a Safari tab, not from the Home Screen.Add the site to the Home Screen, open it from there, and ask for notifications from a tap in that app. Web push on iPhone and iPad needs iOS or iPadOS 16.4 or later.
Banners were showing and stopped, or never come at some hoursA Focus or Do Not Disturb mode is hiding them.Turn the mode off, or allow your browser app in it. Open your system's notification settings and check the browser app is allowed to show notifications.
permissionState() says denied, or no prompt ever appearsThe browser's site setting for your site is Block.Follow "When the browser says blocked" above.
subscribe() answers workerThe worker file is missing from the top folder of your site, or the page is not on https.Open yourwebsite.com/slide-push-sw.js in a tab. It should show the two lines of code. Fix the path or serve the site on https.
subscribe() answers app_off or register_failedThe app is switched off, or the page is not on the website verified for this app.Check that the app is on in Setup and that Tracking & sites shows this website as verified.
Brave: subscribe() answers subscription, or nothing arrivesBrave keeps web push behind its own setting.In Brave, open Settings, Privacy and security, and turn on "Use Google Services for Push Messaging". Restart Brave and reload the page. This is Brave's own setting, so the person chooses it.
A Chromium browser other than ChromeThese browsers often report themselves as Chrome, and the operating system lists them under their own name.Check the operating system's notification setting for that exact app name.

Your page cannot see the operating system, but the person can. verify() shows a test notification on their own device and asks if they saw it. If they did not, it shows the steps for their system, so they can fix it without contacting you. It makes no request and sends nothing to Slide.

js
// After the person has allowed notifications, for example behind a "Check that it works" button:
const check = await window.SlidePush.verify();
// check.outcome: "seen", "not-seen" or "skipped"
// For "skipped", check.reason says why: unsupported, not_granted, no_worker, busy, dismissed or error.

// Or ask for the check right after they subscribe, in the same flow:
const result = await window.SlidePush.softAsk({ userInitiated: true, verify: true });
// result.outcome is "subscribed", and result.verify has the same shape as check.

verify() and testNotification() never ask for permission. When the permission is not granted they answer skipped with the reason not_granted, so call them after the person has said yes. Clicking the test notification opens your site's home page, like any notification.

The browser check takes ten seconds. Open your site, open the browser console and run the line below. First make sure Notification.permission says granted. If a banner appears, the browser and the operating system are fine, and the problem is between Slide and the device. If nothing appears, the problem is on the device: fix the table above before you look at Slide.

js
Notification.permission                  // must say "granted"
new Notification("local test")           // a banner should appear

On a Mac you can also ask the operating system what it did. Find the browser's bundle id, send a test from Slide, and read the notification daemon's log. authorizationStatus: Denied means macOS is blocking the browser app. After you allow it in System Settings, the same test logs Presenting.

bash
osascript -e 'id of app "Google Chrome"'     # the bundle id, for example com.google.Chrome

/usr/bin/log show --last 2m --info --debug \
  --predicate 'process == "usernoted" AND eventMessage CONTAINS "<bundle id>"' | grep authorizationStatus

A mobile app registers itself over a small REST contract with the app key, never your API key. Make the app in the dashboard (Web and App Push, then Setup) and copy its app key and its register address from How to install. The full contract, the request fields and the samples are in the API reference.

  • Android: the app registers once with no token and keeps one secure connection to Slide open from a foreground service (Slide Connect). Keep the installation id and secret in private storage and refresh with them. Registering again on every start, or after a reinstall, leaves an old installation behind. Slide holds messages while the app is offline and delivers them on the next connection.
  • iPhone and iPad: Slide delivers through Apple push, with the notification key (a .p8 file) you save for the app in Setup. The app asks the person for permission and sends the device token, as hexadecimal text, with its registration. iPhone and iPad do not use Slide Connect: a Connect hello from an iPhone installation is refused.
  • Both: send the consent words the person saw with the registration, and report delivered, shown and clicked back to Slide, so the funnel in the dashboard fills in. Open n.url exactly as it arrives: it already carries the tracking.

The registration contract, Slide Connect frames, limits and the Swift and Kotlin samples are in the API reference, under Push for mobile apps. Open Push for mobile apps

Sending is one call over the public API. Make an API key with the push:send scope and keep it on your server. Send an Idempotency-Key on every send, so a retry sends once. Use category TRANSACTIONAL for order and account updates. To send to one person, give their own user id: link({ externalUserId }) on the web, or externalUserId when an app registers.

bash
curl -X POST https://api.slide.cx/v1/push/messages \
  -H "Authorization: Bearer $SLIDE_API_KEY" \
  -H "Idempotency-Key: order-1042-shipped" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "TRANSACTIONAL",
    "target": { "kind": "contacts", "externalUserIds": ["user_1042"] },
    "notification": {
      "title": "Your order has shipped",
      "body": "Track it in your account.",
      "url": "https://yourshop.com/orders/1042"
    }
  }'

Add "options": { "dryRun": true } to check a request without sending anything. Targets, filters, scheduling, campaigns, templates, subscribers, the consent log and webhook events are in the API reference. Open Push notifications in the API reference

  • MDN Web Docs: Notification.requestPermission(), on asking from a user gesture.
  • Mozilla Hacks: Upcoming notification permission changes in Firefox 72.
  • Microsoft Edge policy documentation and the Chromium policy list: NotificationsAllowedForUrls, DefaultNotificationsSetting.
  • Firefox Enterprise policy documentation, Permissions: https://firefox-admin-docs.mozilla.org/reference/policies/permissions/
  • Apple Support, Change Notifications settings on Mac: https://support.apple.com/guide/mac-help/mchl205da693
  • Apple Support, Safari on Mac, website notifications: https://support.apple.com/guide/safari/customize-website-notifications-sfri40734/mac
  • Microsoft Support, Notifications and Do Not Disturb in Windows: https://support.microsoft.com/windows/8942c744-6198-fe56-4639-34320cf9444e
  • Google Chrome Help, Use notifications to get alerts: https://support.google.com/chrome/answer/3220216
  • Android Help, Manage notifications: https://support.google.com/android/answer/9079661
  • WebKit blog, Web Push for Web Apps on iOS and iPadOS: https://webkit.org/blog/13878/web-push-for-web-apps-on-ios-and-ipados/
  • Brave community, Use Google Services for Push Messaging (a user forum, not Brave's documentation): https://community.brave.app/t/setting-use-google-services-for-push-messaging-is-disabled-by-default-and-push-messaging-doesnt-work/98022