Safari Push Notifications
The following guide will help you set up browser push notifications on Safari. To set up browser push notifications on other browsers using the Push API, please follow this guide.
Safari Push requires quite an elaborate setup of the key infrastructure. Following diagram shows happy-path steps required for a JS SDK and Safari browser to successfully register for push notifications into Apple APNS and Bloomreach Engagement Platform:


Picture shows that Bloomreach Engagement essentially needs two configuration properties:
- APNS credentials to enable Bloomreach Engagement to push into APNS
pushPackage.zip
which sets up Safari browser for the given domain
Both of the properties can be obtained from Apple Developer Center, which requires user to have paid access to the portal.
Configuration
Following steps will describe how to configure Safari Push for a fictional website www.ecommerce.com:
Prerequisites
- Paid access to Apple Developer Account
- Mac OS computer, with:
- PHP installed on your computer
- Certificate Signing Request (see later)
Steps
Register the Website Push ID
Website Push ID is a unique identifier of the domain, which is composed from reversed domain name and a prefix web
.
Example for www.ecommerce.com: web.com.ecommerce
- Log into Apple Developer Account
- Go to section Certificates, Identifiers & Profiles
- Go to Identifiers menu
- Switch to Website Push IDs in the select box
- Hit + button


- Enter the Description and Identifier


- Click Continue and Register
- The new Identifier should appear in the list
Generate the Website Push ID certificate
In order to prove to Safari browser, that Bloomreach Engagement can be used to register for push notifications, you need a certificate which is later used for signing with pushPackage.zip.
- Continue where you left, and click on the name of the Ecommerce Co identifier
- Click on Create Certificate


- Upload Certificate Signing Request (if you don’t have one on your team, create a new one here
- Click Continue
- Click Download and save
website_aps_production.cer
file on the disk


Convert the CER file to P12 using Keychain Access
In order to with sign pushPackage, you need a certificate and private key together in P12 format. You need to convert CER file downloaded from Apple Developer Center in previous step to P12 format.
- Open the Keychain Access application from the Applications > Utilities folder
- Import the certificate file (CER file) by selecting File > Import and locating your CER file provided by Apple
- Select the Certificates category and locate the certificate that you just imported
- Expand the arrow next to the certificate to show the key.
- Select the key
- Select File > Export Items...
- Name the export and ensure that the file format is Personal Information Exchange (.p12)
- Click Save
- Provide a password to protect the export. This password will need to be provided to services that will use the certificate
- Click OK
- Provide your Mac password to enable the export
- Click Allow
- The
P12 file
should now exist in the location you selected in step 7
Generate the pushPackage
pushPackage.zip
is a file which contains instructions on how should Safari handle push notifications from Bloomreach Engagement. It also proves ownership of the domain by verifying the signature of the generated package.
Generate website.json
You will need the website.json
file to generate the pushPackage.zip
. Since it is critical to get website.json
right, Bloomreach Engagement has a tool to help you with its creation:
- Go to the Project Settings > Channels > Push notifications
- Switch Safari Push Notifications ON
- Enter Website Push ID
- Generate new Authentication token (it is a random token, so you may use your own)
- Click onCreate website.json, this opens a modal:
- Enter Website name
- Click Copy to clipboard
- Create a new file website.json on your disk and paste the contents of clipboard
Do not close the tab with Bloomreach Engagement push notification settings, you will be finishing the configuration later




Generate pushPackage.zip
Once you have generated website.json
, you can finally generate pushPackage.zip
:
- Make sure you have PHP installed on your system
- Download and extract the Companion File from here
- Change
createPushPackage.php
line with$certificate_path
variable declaration to point atP12 file
you generated in previous step - Create a folder with the following minimal structure:
pushPackage.raw/
icon.iconset/
icon_128x128.png
[email protected]
icon_16x16.png
[email protected]
icon_32x32.png
[email protected]
website.json
createPushPackage.php
- Run php
createPushPackage.php
from the directory same ascreatePushPackage.php
script - New directory is created in format
pushPackage<timestamp>
together with the ZIP archive with the same contents, e.g.:
pushPackage1580817868/
icon.iconset/
icon_128x128.png
[email protected]
icon_16x16.png
[email protected]
icon_32x32.png
[email protected]
manifest.json
signature
Website.json
You can see that two new files were generated:
manifest.json
contains checksums of all files in the package to ensure their consistency, while signature is a package signature created by yourP12
pushPackage1580817868.zip
is the file you will need
Configure Bloomreach Engagement for Safari Push Notifications
As have we already said, you need two credentials to make Safari Push in Bloomreach Engagement work, those are: pushPackage.zip
(which you just generated in previous step) and APNS key. Now you will generate APNS key and then configure everything in Bloomreach Engagement.
Generate Push Key
- Go to Keys section of Apple Developer Center


- Click the + button
- Enter the name, e.g.
exponeaAPNS
- Check the Apple Push Notifications service checkbox


- Click Continue and then Register
- Make a note of (or copy out) the following information as you will need them later; (see screenshot)
Team ID
(in the right top corner)
Key ID
(in the key details section of the page)


- Download the
P8 key
Make sure to store it properly, as you can’t download it again. You can revoke it and generate a new one though
Configure Exponea APNS and Push Notifications
- Go back to the Bloomreach Engagement tab (or open Project Settings > Channels > Push notifications )
- In section Apple notifications, enter:
Team ID
(as noted in previous step)
Key ID
OpenP8 file
and paste its entire contents into theES256
Private Key
Leave the Application Bundle ID empty if you do intend to configure iOS Push Notifications - You have already entered Web Push ID and generated Authentication token, but to remind, you need the following values:
Web Push ID :web.com.ecommerce
Authentication token : … (as generated, you can also find it inside website.json file) - Push package
Click on the Browse .ZIP file
Select the ZIPpushpackage1580817868.zip
as generated in one of previous steps - Click save
The settings should be saved and ZIP file successfully uploaded


If you made an error in configuration, the ZIP may fail to upload
- The last step is to update Web integration code, so click Get updated tracking snippet from Web integration link - notice the new push/safari/websitePushID section
Copy the code to your webpage - Notice the List of error logs from last 7 days link
When clicking, modal opens with a list of errors detected in the integration in last 7 days - you may need it when troubleshooting when Safari push notifications don’t work


Trying Safari Push notifications
The simplest way to try Safari Push is to create Push Notification web layer from the template available in Web Layers section and then define Scenario which pushes to that client.
Create Push Subscribe web layer
- In Bloomreach Engagement go to Web Layers > Create New
- Select Push Subscribe template
- Make sure to target only your test user in Settings > Audience
- Start web layer (the confirmation dialog should clarify that you are targeting this web layer only to 1 customer)
- Navigate to your website
- Web Layer should be shown and allow you to Subscribe
- After clicking Subscribe, you will be presented withSafari’s confirmation dialog; here you click Allow
- Your customer should be
safari_push_notification property
- you can verify that in the Customers > Customer view - Close the website to try Push in next step.
Send Scenario with Push Notifications
In order to verify push, close the website where you’ve opened in last step and define a following Scenario:
- In Bloomreach Engagement go to Scenarios > Create New
- Add a
Now
node - Add
Condition
and configure it with a Customer Filter :
Select customers matching attribute:safari_push_notification
is set - Add
Other
and select Browser push notification
Add Title, Message and URL Params
i. Each URL param replaces%@
placeholder inurlFormatString
section in your website.json file (except the last one)
ii. Sample:
PredefinedurlFormatString
=https://static.qa.gdev.exponea.com/%@/?iitt=%@
iitt=%@
placeholder is defined by Bloomreach Engagement
So, when you enter URL Params =ABC
The user will land athttps://static.qa.gdev.exponea.com/ABC/
- Save the scenario
- Start the scenario and confirm that it targets only 1 customer
Updated 4 months ago