Step-by-Step Setup Instructions

This topic provides detailed instructions for integrating your website with the Oracle Responsys Web Push Service. Follow the steps in this section if you are new to Oracle Responsys Web Push, and you are creating a Web Push App for the first time.

Migrating from an Existing Provider

If you are switching to Responsys from an existing Web Push provider, then refer to Migrating from an Existing Provider to remove your previous provider.

Supported Browsers

• Refer to Supported Browsers to see the browsers supported for Web Push notifications.

• Ensure you handle Unsupported Browsers and Operating Systems as specified in How to handle Unsupported Platforms.

How to handle Unsupported Platforms (Browsers, OS)

• Do not implement the Responsys Web Push Solution on unsupported Browsers and unsupported Operating Systems.

• List of Browsers Supported and Operating Systems Supported is detailed at Browser Support.

High Level Overview

1. Step 1: Initial Setup. In Responsys, create a Web Push App and Web Push Channel List, and then associate the list with your app.

2. Step 2: Add the Web Push Tag to your website. Add the Responsys Web Push Tag to your website.

3. Step 3: Deploy Service Worker. Add the Responsys Service Worker to your website.

4. Step 4: Send a Test Web Push Notification. Send a test Web Push Notification.

Ensure you handle Unsupported Browsers and Operating Systems as specified in How to handle Unsupported Platforms.

Now that you have an idea of the steps involved, let's discuss each step in detail.

Step 1: Initial Setup

[1.1] Complete the "Adding a Web Push App" steps in Manage Apps and Platforms to create a Web Push App in Responsys.

[1.2] Complete the steps in Setting up the Web Push Channel List to set up a Web Push Channel list and associate it with your app.

Step 2: Add the Web Push Tag to your Website

The Responsys Web Push Tag is a Javascript snippet that must be added to every page of your website. Implementing the tag on your website enables the following:

• Ensures all pages of your website can subscribe to notifications.

• You can perform actions such as setting the User Identifier when a website user logs in.

• You can raise Conversion or Purchase Events.

NOTE: Do not use the Web Push Tag from one Web Push app on multiple website domains. Otherwise, your end users could receive duplicate notifications. Create a new app for each website domain you want to implement Web Push on.

To add the Web Push Tag to your Website:

[2.1] In Responsys, navigate to the App Developer Console and find your Web Push App.

[2.2] Click Edit > Platform.

[2.3] Click Download > Web Push Tag.

[2.4] Click Copy.

[2.5] (Optional) Customize the Web Push Javascript tag.

You can edit the Javascript tag if you want to change the default behavior. Here are some use cases where you might want to customize the default Web Push tag:

• You want to track the website version your website visitors are using.

• When users visit your website, you do not want a Web Push Permission Prompt to appear right away.

• You want asynchronous Javascript.

[2.5.1] To track the website version your website visitors are using:

In the Web Push Javascript you copied in step 2.4, change the value of appver to your Web Push app version number.

For example: "appver":"1.0.0"

[2.5.2] Delaying the Web Push Notification Permission Prompt:

Websites may want to delay the Web Push Notification Permission Prompt because they want other events to occur first, to increase the likelihood that a user will opt in to Web Push Notifications. Here are some reasons you may want to delay the Web Push Notification Permission Prompt:

• The website wants to send the Notification Permission Prompt at a "contextually relevant" moment, instead of as soon as a website visitor arrives to the website.

• The website wants to implement pre-permission messaging.

To delay the Web Push Notification Permission Prompt:

In the Web Push Javascript you copied in step 2.4, change the value of lazy to true. When users who are not subscribed to Web Push notifications visit your website, the Web Push Permission Prompt will not appear right away.

It is then the responsibility of the web developer to call the webPushManagerAPI.register() function of Web Push SDK API to display the Web Push Notification Permission Prompt.

[2.5.3] To make the Javascript asynchronous:

Add async to the <script> element. For example:

<script 
    type='text/Javascript' 
    id='rsyswpsdk'
    async   
    src='https://responsys.net/e1/responsysimages/content/user/wpIndex_08_Jan.js?1' 
    wpconfig = '{"appserviceKey":"GAsbojlN2PfAjbI3hVV_vFcbY2dutcccZlmZbM3F31B3YXtqqLezk4dDFDa1ij-KIx_WxPZaWcqNd1RlrdLP7OM=","apiKey":"ABCDFG-jS1FHww1C67vzONIKo","accountToken":"ABCiL3XUHTos8wxm2klLSJTvI","appver":"0.0.0","apiHost":"https://api.pushio.com","lazy":false}'>
</script>

[2.6] Insert the Web Tag into the <head> element of every page of your website.

<head>
<script 
    type='text/Javascript' 
    id='rsyswpsdk' 
    async
    src='https://responsys.net/e1/responsysimages/content/user/wpIndex_08_Jan.js?1' 
    wpconfig = '{"appserviceKey":"GAsbojlN2PfAjbI3hVV_vFcbY2dutcccZlmZbM3F31B3YXtqqLezk4dDFDa1ij-KIx_WxPZaWcqNd1RlrdLP7OM=","apiKey":"ABCDFG-jS1FHww1C67vzONIKo","accountToken":"ABCiL3XUHTos8wxm2klLSJTvI","appver":"0.0.0","apiHost":"https://api.pushio.com","lazy":false}'>
</script>
</head>

Step 3: Upload the Service Worker to your Website

The Oracle Responsys Web Push Service Worker is a script that runs in the background to send Web Push Notifications to website visitors. Refer to Google's documentation to learn more about service workers.

The Responsys Web Push Service Worker handles incoming push requests and communicates with Responsys. You can download your Responsys Service Worker in Responsys.

NOTE: Do not use the Service Worker from one Web Push app on multiple website domains. Otherwise, your end users could receive duplicate notifications. Create a new app for each website domain you want to implement Web Push on.

To upload the Service Worker to your Website:

[3.1] Navigate to the App Developer Console and find your Web Push App. You created this in step 1.1.

[3.2] Click Edit > Platform.

[3.3] Click Download > Service Worker.

[3.4] Click Download Service Worker. A file named webpush-service-worker.js will be downloaded.

[3.5] Upload the webpush-service-worker.js file to the top-level root of your site directory, making them publicly accessible.

Verify if you've uploaded the Service Worker files correctly by navigating to the file location below (replace yoursite.com with your site's domain).

https://yoursite.com/webpush-service-worker.js

If you've correctly uploaded the Service Worker, navigating to the Service Worker on your site should look something like this:

Step 4: Send a Test Web Push Notification

[4.1] Complete the steps in Test Apps to test sending a Web Push notification.

Next Steps

By completing this guide, you've integrated your website with Oracle Web Push! Check out the Oracle Responsys Help Center to learn how to Orchestrate Web Push Campaigns!