Apple has introduced support for Web Push in PWAs starting with iOS 16.4.
This guide assumes that Batch Web SDK is already up and running on your website: you should be able to subscribe to and receive notifications using Safari on macOS 13 (or higher) before going forward.
Configuring Safari APNs is not required as this protocol is not used by iOS.
To be able to subscribe to Web Push notifications on their phones and tablets, iOS users have to install your website as an app. But in order to be installable, your website must be a Progressive Web Application (PWA).
What is a PWA?
PWAs bridge the gap between websites and native apps by offering capabilities previously reserved for native apps to websites. PWAs are first and foremost Websites following the latest best practices and technologies but can be enhanced with deeper system integration for users who install them.
Turning your website into a PWA
PWAs are websites with a couple of extra requirements:
They must be served over
httpsThey must have a Web Application Manifest
They must have a Service Worker
Good news: you've already done this part when integrating our web sdk 🎉
This manifest needs to be referenced in your website using an HTML
<head>tag.
First things first, let's create your manifest.
For this example, we will call our manifest manifest.json and host it on our website's root. You can name it however you want or host it on a CDN, but we will not cover this.
If you have a Content Security Policy (CSP), you might need to update it to allow your manifest to be registered. Search for manifest-src.
Open an editor, create a file named manifest.json, paste the following content and replace the default values:
{
"short_name": "Batch store", // Name of your app if the "name" doesn't fit
"name": "Batch Store", // Name of your app on the homescreen
"icons": [
{
"src": "https://cdn.glitch.global/20fbe514-82ff-481c-affd-936b061873bb/pwa_logo.png?v=1676644156289", // Icon URL. Can be hosted on a CDN.
"type": "image/png", // Icon mimetype
"sizes": "235x235" // Your icon size
}
],
"id": "/",
"start_url": "/", // URL that will be loaded by the system when launching your PWA. You can set tracking parameters here. Example: "/?utm_source=pwa".
"background_color": "#FFFFFF", // The background that should be displayed behind your logo while the PWA is loading
"display": "standalone", // This tells iOS to display your app without the Safari interface. Without it, Web Push notifications are NOT enabled by iOS!
"scope": "/",
"theme_color": "#FFFFFF", // Your website's accent color
"description": "Batch's Demo Store PWA" // Website description.
}
Remove the comments, and upload this file to your website's root (/).
Then, add the following meta tag on your pages, in <head>:
<html>
<head>
<link rel="manifest" href="manifest.json">
</head>
</html>
Upload/deploy your website and you're done!
Testing
You will need an iPhone or iPad running iOS 16.4 or newer to test the integration.
Even though you've turned your website into a PWA, Batch Web SDK will not show the pre-subscription prompt that shows up on your mac's Safari: you need to install your PWA.
Asking for notification permission on iOS, just like on macOS Safari, can only be done after the user interacts with your website. Batch can provide this with our UI Components feature.
Here is how to do it:
Open your website in Safari
Press the "Share" button at the bottom of your screen
Select "Add to Home Screen"
You should then see your PWA's Title and Icon as defined in the manifest. Is the icon is a preview of the website, Safari failed to recognize your Manifest.Exit Safari: your PWA will be available on your lockscreen.
Now that it is installed, open it. If configured, Batch Web SDK will show a UI component prompting you to subscribe to notifications. Subscribe and you should see the iOS permission request. You're done!
As the Safari Inspector is not available for installed PWAs, you will need to add a way (hidden button, secret tap sequence, etc...) to call the batchSDK('ui.showPublicIdentifiers') javascript method so that Batch displays the Installation ID needed to test your Web Push notification.
Troubleshooting
If you are having trouble figuring out why your manifest doesn't work, use Chrome's inspector (using the Application tab) to find out why. Safari can also print useful errors in its remote inspector.