📘



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 Notifications require quite an elaborate setup of the key infrastructure. The following diagram shows the happy-path steps required for a JS SDK and Safari browser to successfully register for push notifications into Apple APNS and Bloomreach Engagement Platform:

The picture above shows that Bloomreach Engagement essentially needs two configuration properties:

• APNS credentials to enable Bloomreach Engagement to push into APNS

• `pushPackage.zip`, which sets up the Safari browser for the given domain

Both of the properties can be obtained from Apple Developer Center, which requires users to have paid access to the portal.

# Configure the Push

The following steps will describe how to configure Safari Push Notifications for a fictional website www.ecommerce.com:

### What do you need

• Paid access to [**Apple Developer Account**](🔗)

• Mac OS computer, with:

• PHP installed on your computer

• Certificate Signing Request (see later)

# Setup steps

## Register the Website Push ID

Website Push ID is a unique identifier of the domain, which is composed of a reversed domain name and the 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 the Identifiers menu.

4. Switch to Website [**Push IDs**](🔗) in the select box.

5. Hit the `+` button.

6. Enter the **Description** and **Identifier**.

7. Click **Continue** and **Register**.

8. The new Identifier should appear in the list.

## Generate the Website Push ID certificate

In order to prove to the 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**](🔗) off, and click on the name of the Ecommerce Co identifier.

2. Click on **Create Certificate**.

3. Upload **Certificate Signing Request** (if you don’t have one on your team, create a new one [**here**](🔗).

4. Click **Continue**.

5. Click **Download** and save `website_aps_production.cer` file on the disk.

## Convert the CER file to P12 using Keychain Access

In order to sign the _pushPackage_, you need a certificate and private key together in **P12** format. You need to convert the **CER** file downloaded from Apple Developer Center in the 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 on `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 on `OK`.

11. Provide your Mac password to enable the export.

12. Click on `Allow`.

13. The _P12_ file should now exist in the location you selected in step 7.

## Generate the pushPackage

`pushPackage.zip` is a file that contains instructions on how Safari should 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. Set up the Safari Push Notification integration, which requires:

• Team ID

• Key ID

• ES256 Private Key

• Web Push ID

4. Generate a new Authentication token (it is a random token, so you may use your own).

5. Click on `Create website.json`, this opens a modal:

• Enter Website name

• Click `Copy to clipboard`

• Create a new website.json file 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:

5. Run php `createPushPackage.php` from the directory same as `createPushPackage.php` script. It must be on the same path level as the .raw folder. The command php `createPushPackage.php` creates two forms of the folder: one unzipped and one zipped.

6. New directory is created in format `pushPackage<timestamp>` together with the ZIP archive with the same contents, e.g.:

🚧



You can see that two new files were generated: `manifest.json` contains checksums of all files in the package to ensure their consistency, while the signature is a package signature created by your `P12`.

7. `pushPackage1580817868.zip` is the file you will need.

## Configure Bloomreach Engagement for Safari Push Notifications

As was mentioned above, you need two credentials to make Safari Push in Bloomreach Engagement work, and those are `pushPackage.zip` (which you just generated in the previous step) and the `APNS key`. Now you will generate APNS key and then configure everything in Bloomreach Engagement.

## Generate the Push Key

1. Go to [**Keys**](🔗) section of Apple Developer Center.

2. Click the `+` button.

3. Enter the name, e.g. “exponeaAPNS”.

4. Check the Apple Push Notifications service checkbox.

5. Click `Continue` and then `Register`.

6. 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)

7. Download the `P8 key`.

🚧



Make sure to store it properly, as you cannot download it again. However, you can revoke it and generate a new one.

## Configure Exponea APNS and Push Notifications

1. Go back to the Bloomreach Engagement tab and open `Project Settings > Channels > Push notifications`.

2. In the `Apple notifications` section, enter:

• **Team ID** (as noted in previous step)

• **Key ID** Open the `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 the Web Push ID and generated an Authentication token, but to remind you, 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 the previous steps.

5. **Click save** The settings should be saved, and the ZIP file successfully uploaded.

🚧



If you made an error in configuration, the ZIP file might fail to upload.

6. The last step is to update the **Web integration** code, so click `Get updated tracking snippet` from the Web integration link - notice the new push/safari/websitePushID section. Copy the code to your webpage.

7. Notice the **List of error logs from the last 7 days** link.

📘



The modal opens with a list of errors detected in the integration in the the last seven days - you may need it when troubleshooting when Safari push notifications do not work.

## Trying Safari Push notifications

The simplest way to test the Safari Push is to create a Push Notification web layer from the template available in the [Weblayers](🔗) section and then define the [Scenario](🔗) which pushes to that client.

## Create Push Subscribe web layer

1. In Bloomreach Engagement, go to `Web Layers > Create New`

2. Select the Push Subscribe template

3. Make sure to target only your test user in `Settings > Audience`

4. Start the weblayer (the confirmation dialog should clarify that you are targeting this weblayer only to 1 customer).

5. Navigate to your website.

6. Weblayer should be shown and allow you to subscribe.

7. After clicking `Subscribe`, you will be presented with Safari’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 the Push in the next step.

## Send Scenario with Push Notifications

In order to verify the push, close the website that you have opened in the last step and define the 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:

• Each URL param replaces `%@` placeholder in `urlFormatString` section in your website.json file (except the last one)

• 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 one customer.