HomeEngagementContentDiscoveryOther Resources

Safari Push Notifications

Suggest Edits

📘

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

  • 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

  1. Log into Apple Developer Account
  2. Go to section Certificates, Identifiers & Profiles
  3. Go to Identifiers menu
  4. Switch to Website Push IDs in the select box
  5. Hit + button
  1. Enter the Description and Identifier
  1. Click Continue and Register
  2. 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.

  1. Continue where you left, and click on the name of the Ecommerce Co identifier
  2. Click on Create Certificate
  1. Upload Certificate Signing Request (if you don’t have one on your team, create a new one here
  2. Click Continue
  3. 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.

  1. Open the Keychain Access application from the Applications > Utilities folder
  2. Import the certificate file (CER file) by selecting File > Import and locating your CER file provided by Apple
  3. Select the Certificates category and locate the certificate that you just imported
  4. Expand the arrow next to the certificate to show the key.
  5. Select the key
  6. Select File > Export Items...
  7. Name the export and ensure that the file format is Personal Information Exchange (.p12)
  8. Click Save
  9. Provide a password to protect the export. This password will need to be provided to services that will use the certificate
  10. Click OK
  11. Provide your Mac password to enable the export
  12. Click Allow
  13. 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:

  1. Go to the Project Settings > Channels > Push notifications
  2. Switch Safari Push Notifications ON
  3. Enter Website Push ID
  4. Generate new Authentication token (it is a random token, so you may use your own)
  5. 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 :

  1. Make sure you have PHP installed on your system
  2. Download and extract the Companion File from here
  3. Change createPushPackage.php line with $certificate_path variable declaration to point at P12 file you generated in previous step
  4. 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
  1. Run php createPushPackage.php from the directory same as createPushPackage.php script
  2. 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 your P12

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

  1. Go to Keys section of Apple Developer Center
  1. Click the + button
  2. Enter the name, e.g.exponeaAPNS
  3. Check the Apple Push Notifications service checkbox
  1. Click Continue and then Register
  2. 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)
  1. 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

  1. Go back to the Bloomreach Engagement tab (or open Project Settings > Channels > Push notifications )
  2. In section Apple notifications, enter:
    Team ID (as noted in previous step)
    Key ID
    Open P8 file and paste its entire contents into the ES256 Private Key
    Leave the Application Bundle ID empty if you do intend to configure iOS Push Notifications
  3. 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)
  4. Push package
    Click on the Browse .ZIP file
    Select the ZIP pushpackage1580817868.zip as generated in one of previous steps
  5. 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

  1. 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
  2. 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

  1. In Bloomreach Engagement go to Web Layers > Create New
  2. Select Push Subscribe template
  3. Make sure to target only your test user in Settings > Audience
  4. Start web layer (the confirmation dialog should clarify that you are targeting this web layer only to 1 customer)
  5. Navigate to your website
  6. Web Layer should be shown and allow you to Subscribe
  7. After clicking Subscribe, you will be presented withSafari’s confirmation dialog; here you click Allow
  8. Your customer should be safari_push_notification property - you can verify that in the Customers > Customer view
  9. 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:

  1. In Bloomreach Engagement go to Scenarios > Create New
  2. Add a Now node
  3. Add Condition and configure it with a Customer Filter :
    Select customers matching attribute: safari_push_notification is set
  4. Add Other and select Browser push notification
    Add Title, Message and URL Params
    i. Each URL param replaces %@ placeholder in urlFormatString section in your website.json file (except the last one)
    ii. Sample:
    Predefined urlFormatString = 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 at https://static.qa.gdev.exponea.com/ABC/
  5. Save the scenario
  6. Start the scenario and confirm that it targets only 1 customer

Updated 4 months ago

Did this page help you?