{"info":{"_postman_id":"e6b30238-4fa0-4866-856f-904382331597","name":"Web Push JS","description":"

This document describes how to integrate Symplify Web Push on your web site.

What is it and what can I use it for?

Symplify Web Push messaging enables you to Pop Up when your customer is on site.\nYou can for example use Symplify Web Push to inform selected customers that they have an active offer available, tips and tricks within the platform or showcasing features based on the recipient profile.

You can of course personalize all messages and use the different Symplify modules, like Journeys and Campaigns to generate your Symplify Web Push messages.

Create welcome messages for new users with link and instructions for navigating the app or best use the application
Send a reminder that pops up after login so they remember to complete their registration with credit card, loyalty card and shipping address etc.
Showcase new features and encourage users to try them out
Send coupons and offers
Remind customers of abandoned carts or loyalty credits on their accounts
Offer order tracking after sales

Include the Symplify Web Push resources

Please note: Depending on which Symplify server you are using, you will need to use one of these distributions to allow the Web Push script to communicate with the correct server:

European servers:

https://d3mi6d1ao3fzsg.cloudfront.net/webpush\n

North American servers:

https://d2v4xhvyfyhzvd.cloudfront.net/webpush\n

Reach out to your Success manager if you are uncertain.

The examples below are using the European CDN.

Stylesheet

The Symplify Web Push stylesheet contains the default look and feel of the inbox and pop ups. You can customize the inbox by overriding the default styles using your own stylesheet.\nThe stylesheet is usually inserted in the <head> element of your page.

<link\n    rel=\"stylesheet\"\n    type=\"text/css\"\n    href=\"https://d3mi6d1ao3fzsg.cloudfront.net/webpush/1/webpush.min.css\"\n/>\n

Script

The Symplify Web Push script is responsible for displaying symplify web push messages as they arrive, as well as providing an optional inbox where received messages are listed with their respective read or unread status. The Symplify Web Push editor can customize where and how the message should be displayed.

The script is usually inserted immediately before the closing </body> element of your page.

<script\n    id=\"sym-web-push\"\n    src=\"https://d3mi6d1ao3fzsg.cloudfront.net/webpush/1/webpush.min.js\"\n    type=\"text/javascript\"\n    data-inbox-element=\"#my-inbox-element\"\n    data-user-hash=\"[server side generated user hash, see 'How to identify the recipient']\"\n    async\n></script>\n

How to identify the recipient

We need a secret identifier that is used when connecting to the Symplify Web Push service.\nThe secret is a securely hashed signature created by calling our REST API with the id of your contact. If the contact is present in any of your lists in Symplify, we will return a hash which you can use to connect to the contact's inbox.

NOTE: Since communicating with our REST API is done on the server side, this will require some development on your side. Read about using our API here

A basic usage pattern is:

The user logs in to your site.
Once you know the id of your user, call our user hash resource.
Cache the user hash in your web server session storage or in your database.
- Do not call the user hash resource for every page.
- User hashes are valid for 90 days.
\n
Include the script on pages where Symplify Web Push messages should be displayed.

Secure user hashes are generated using the REST resource /webpush.

POST /rest/{customerid}/webpush\n{\n  \"contactId\": \"the id of the user in your database\", (originalId in Symplify)\n  \"privacyLevel\": \"SENSITIVE|NOT_SENSITIVE\" (defaults to SENSITIVE)\n}\n

An example response would look like

{\n    \"userHash\": \"e94187765acfe001e415107c68f6a6fd5e74b66042145fe28609787b2e881b67\"\n}\n

Push Notifications

WIP - This text is under development and subject to change

Symplify Web Push is embedded in your pages, and is using regular HTML elements and javascript to show notifications. This, however, depends on the user being logged in and viewing your web site. While this is sufficient for most communcation, you might also want to draw attention to important updates to users tha are not actively browsing your web site.

Push notifications behave a little differently compared to our script, since it is managed by the operating system and/or web browser your users are using.

The user must opt-in through the browsers built-in dialog to allow your web site to display push notifications. In addition to allowing the web site to show notifications, the user must also have enabled notifications in their computer settings. If the user clicks \"Block\" in the built-in dialog to not allow your native notifications there is no way to ask again. The user must then go in to the browser settings and remove the block for your web site.

Make sure you ask for permission to send push notifications a time when the user is most likely to understand why you want to show notifications, and what they will receive.

We will try to follow the guidelines for a good UX from (https://developers.google.com/web/fundamentals/push-notifications/permission-ux)

We will not show a push notification permission dialog by default when the page is loaded.
A toggle for native notifications is added to the inbox, or you can implement your own custom UI. The built-in permissions dialog is shown when the toggle/button is clicked.

The push notification Service Worker script must be hosted at the same origin (Protocol + Domain name + Port) as the web site where you want to show notifications. Each sub-domain is considered a different origin.

(for test, this is https://d3mi6d1ao3fzsg.cloudfront.net/webpush/snapshot/service-worker.js)

You need to download https://d3mi6d1ao3fzsg.cloudfront.net/webpush/service-worker.min.js and serve it from your own web site.

You will not get automatic updates for this script, please make manual updates regularly.

https://d3mi6d1ao3fzsg.cloudfront.net/webpush/1/version.json displays the version of the latest release

Add these attributes to the web push script tag to enable push notifications:

data-notifications=\"true\" - default is false
data-service-worker=\"scripts/service-worker.min.js\" - path to the downloaded service worker script. default is service-worker.min.js

 <script\n            type=\"application/javascript\"\n             src=\"https://d3mi6d1ao3fzsg.cloudfront.net/webpush/1/webpush.min.js\"\n            data-inbox-type=\"toggle\"\n            data-count-method=\"unread\"\n            data-enable-api=\"true\"\n            data-notifications=\"true\"\n            data-service-worker=\"scripts/service-worker.min.js\"\n            async\n        >\n

Built in Push Notification management

Add a checkbox with data-toggles=\"push:notifications\" to the Inbox header or footer (View examples in the Inbox Header and Footer section).

<input type=\"checkbox\" data-toggles=\"push:notifications\" />\n

Or use our prestyled markup in the Inbox header or footer.

<div class=\"sym-input-toggle\">\n    <label class=\"sym-input-switch\">\n        <input type=\"checkbox\" id=\"push-notifications\" data-toggles=\"push:notifications\">\n        <div class=\"sym-input-slider\"></div>\n    </label>\n    <label for=\"push-notifications\">Push notifications</span>\n</div>\n

$\"inbox-notifications\"$

Custom Push Notification management

Note: You need to enable the client side API via data-enable-api=\"true\" as described earlier.

<a onclick=\"Symplify.WebPush.subscribeToPush()\">Enable Push Notifications</a>\n<a onclick=\"Symplify.WebPush.unsubscribeFromPush()\"\n    >Disable Push Notifications</a\n>\n

Native notifications will not be shown when:

A user is viewing your web site. (Note: It's not possible to know if the user is currently visiting a page where Symplify Web Push UI is running).
A user has not allowed native notifications via the built in notification management in their operating system (MacOS, Windows, *nix, Android, IOS etc).
A user has not allowed native notifications for you web site via the built in notification management in their web browser.

Privacy Levels

NOTE: This section is only relevant if you cannot retrieve the user hash on the server side

Symplify Web Push provides two similiar types of identifiers for the user for which messages should be displayed. They are both equally secure but one can be generated automatically when a user clicks on a link in a message sent by Symplify, and the other must be requested from Symplify by your server and inserted on the page programmatically.

The difference is in the control over which of your pages the user can receive Symplify Web Push messages.

The two types of user hashes are:

NOT_SENSITIVE
- Added as a querystring parameter to each link that is clicked in a Symplify message.
- Stored in a cookie in the users' browser. (and readable by inspecting browser cookies)
- Readable over HTTP.
- Readable in browser history.
\n
SENSITIVE
- Generated by the Symplify API.
- Injected programmatically when rendering each page.
- Only readable by inspecting the rendered page, disappears when the page is closed.
\n

Using only a cookie, Symplify can never know if your users are viewing a page while logged in, or if the user has logged out (and possibly left the computer for others to use). The cookie is stored for the entire domain, including subdomains. ie www.example.com, shop.example.com, userarea.example.com.

By using the user hash generated on the server side, you can insert it on pages where you know the user is logged in - and no identification that can be found later by a rogue agent will be stored on the users' computer.

By default, all Symplify Web Push messages are sent with PrivacyLevel.Sensitive.

This means that these messages will only be shown if the page use a secure user hash generated by the REST resource.

Inbox Header and Footer

Include a script tag with your own markup to get a custom Inbox header and/or footer.

These must have the ids sym-inbox-header and sym-inbox-footer respectively.

<script id=\"sym-inbox-header\" type=\"text/html\">\n    <strong>Messages</strong>\n    <img class=\"profile-picture\" src=\"profile-12345.png\" />\n</script>\n

<script id=\"sym-inbox-footer\" type=\"text/html\">\n    <div class=\"sym-input-toggle\">\n        <label class=\"sym-input-switch\">\n            <input type=\"checkbox\" id=\"push-notifications\" data-toggles=\"push:notifications\">\n            <div class=\"sym-input-slider\"></div>\n        </label>\n        <label for=\"push-notifications\">Push notifications</span>\n    </div>\n</script>\n

Inbox List Item Template

Include a script tag with the id sym-inbox-list-item with your own markup to customize how the inbox displays each message.

<script id=\"sym-inbox-list-item\" type=\"text/html\">\n    <li class=\"sym-msg\">\n        <span class=\"sym-msg-text\"></span>\n        <span class=\"sym-msg-delete\"></span>\n    </li>\n</script>\n

Inbox Configuration

If you want to display the inbox in a specific location or implement your own UI for the inbox, you can tell the Symplify Web Push script where and how to list the user's messages.

You can also enable a client side API, which you can use to display pop ups to users without using the Symplify Web Push service. This can be useful when the user browse pages without being logged in.

Some optional settings require basic HTML and/or javascript knowledge.

Minimal options

<script\n    type=\"text/javascript\"\n    id=\"sym-webpush\"\n    data-secure-hash=\"e94187765acfe001e415107c68f6a6fd5e74b66042145fe28609787b2e881b67\"\n></script>\n

All options

<script\n    type=\"text/javascript\"\n    id=\"sym-webpush\"\n    data-secure-hash=\"e94187765acfe001e415107c68f6a6fd5e74b66042145fe28609787b2e881b67\"\n    data-inbox-element=\"#my-inbox\"\n    data-inbox-type=\"badge\"\n    data-inbox-header=\"#my-inbox-header\"\n    data-inbox-footer=\"#my-inbox-footer\"\n    data-notifications=\"true\"\n    data-inbox-list-element=\"#my-inbox-messages\"\n    data-count-method=\"unread\"\n    data-get-latest-message=\"true\"\n    data-enable-api=\"true\"\n    data-autostart=\"false\"\n    data-notifications=\"true\"\n    data-worker-script=\"scripts/worker-script.js\"\n></script>\n

Options may also be passed using the global variable window.SymWebPush.\nWhen using this method you get the variable name by removing \"data-\" and convert the remainder to camelCase.\ni.e. data-inbox-type becomes inboxType

<script type=\"text/javascript\">\n    window.SymWebPush = {\n        inboxElement: '#sym-inbox',\n        secureHash: '[server side generated user hash]',\n    };\n</script>\n<script\n    id=\"sym-web-push\"\n    src=\"https://d3mi6d1ao3fzsg.cloudfront.net/webpush/1/webpush.min.js\"\n    type=\"text/javascript\"\n    async\n></script>\n

Available options

data-secure-hash (required)

The secure hash for the current user.

data-secure-hash=\"e94187765acfe001e415107c68f6a6fd5e74b66042145fe28609787b2e881b67\"

data-inbox-element (optional)

Selector for the element which should be used to insert the inbox on the page. If you do not specify an inbox element, no UI except for the popups that pop up when a new message arrive will be displayed. This element is also used as a toggle for the inbox dropdown.

data-inbox-element=\"#my-inbox\"

Query Selector documentation on MDN web docs (external link)

data-inbox-type (optional)

Symplify Web Push provides a few different ways to display the user's number of unread messages. Add an element with a sym-inbox-count class inside your custom inbox element, or use our \"badge\" type to display a small badge with a counter.

data-inbox-type=\"badge\"

Read more about our inbox types and their options here.

data-inbox-list-element (optional)

Selector for the element which should be used to list the inbox on the page.

data-inbox-list-element=\"#my-inbox-messages\"

\n\n\n

data-count-method (optional)

Enables you to postpone the initialization of the Symplify Web Push functionality. Useful if your inbox element is rendered after the document is loaded.\nYou need to enable the client side API to start the functionality at a later time.

data-count-method=\"top\" - default is all

data-get-latest-message (optional)

If this is set to true, the Symplify Web Push script will automatically fetch the latest message and show it if it is unread.

data-get-latest-message=\"true\" - default is false

data-autostart (optional)

Enables you to postpone the initialization of the Symplify Web Push functionality. Useful in Single Page Applications or if your inbox element is rendered after the document is loaded.\nYou need to enable the client side API to start the functionality at a later time.

data-autostart=\"false\" - default is true

Symplify.WebPush.start();\n

data-enable-api (optional)

Enables a simple client side API which you can use to display pop ups similar to the ones sent via the Symplify Web Push service.

data-enable-api=\"true\" - default is false

You can use the API to show a pop up by using the Symplify.WebPush.show function.

Symplify.WebPush.show(\n    'Become a member today!',\n    '[pop up content]',\n    'BOTTOM_RIGHT'\n);\n

Use the Symplify.WebPush.start function to start the Web Push functionality when data-autostart=\"false\". You can provide options that was not available on page render.

myApiCall().then(function (userHash) {\n    Symplify.WebPush.start({\n        secureHash: userHash,\n        inboxElement: '#my-inbox-element',\n    });\n});\n

Use the Symplify.WebPush.stop function to disable Web Push functionality and stop listening for Web Push Messages.

logout().then(function () {\n    Symplify.WebPush.stop();\n});\n

Inbox Types

If you do not want to create your own UI for the Symplify Web Push inbox, you can use one of the types provided out of the box.

Provided types are:

default

$\"default\"$

<div id=\"sym-inbox\">Messages (<span class=\"sym-inbox-count\">1</span>)</div>\n

No markup is automatically inserted for the inbox count indicator.\nThe script will look for an element with the class sym-inbox-count inside the element selected by data-inbox-element and set the text to the user's number of unread messages.

toggle

$\"toggle\"$

<div id=\"sym-inbox\"></div>\n

badge

$\"badge\"$

<div id=\"sym-inbox\"><svg></svg></div>\n

Icon is not included, the badge is positioned with an offset relative to the last element in your inbox element

badgeInline

$\"badgeInline\"$

<div id=\"sym-inbox\">Notications</div>\n

Text is not included, the badge is positioned relative to the last element in your inbox element

badge-bell, badge-horn

$\"badge-bell\"$

<div id=\"sym-inbox\"></div>\n

Icon is included.

Example page 1

A page with push notifications and an inbox with a header and footer.

<!DOCTYPE html>\n<html>\n    <head>\n        <link\n            rel=\"stylesheet\"\n            type=\"text/css\"\n            href=\"https://d3mi6d1ao3fzsg.cloudfront.net/webpush/1/webpush.min.css\"\n        />\n    </head>\n    <body>\n        <div id=\"sym-inbox\"></div>\n\n        <script id=\"sym-inbox-header\" type=\"text/html\">\n            <strong>Messages</strong>\n            <span class=\"profile-pic\"></span>\n        </script>\n\n        <script id=\"sym-inbox-footer\" type=\"text/html\">\n            <div class=\"sym-input-toggle\">\n                <label class=\"sym-input-switch\">\n                    <input type=\"checkbox\" id=\"push-notifications\" data-toggles=\"push:notifications\">\n                    <div class=\"sym-input-slider\"></div>\n                </label>\n                <label for=\"push-notifications\">Push notifications</span>\n            </div>\n        </script>\n\n        <script\n            type=\"application/javascript\"\n            src=\"https://d3mi6d1ao3fzsg.cloudfront.net/webpush/1/webpush.min.js\"\n            data-secure-hash=\"3179e184a6f9e3g6fbd2d1b12ae2dfd0bd01ba340dd153d4163d692554f8c11e\"\n            data-inbox-type=\"toggle\"\n            data-enable-api=\"true\"\n            data-notifications=\"true\"\n            data-service-worker=\"scripts/service-worker.min.js\"\n            async\n        ></script>\n    </body>\n</html>\n

Example page 2

A page without an Inbox. If you're using the NOT_SENSITIVE option where the user hash is sent in the page URL, remove the data-secure-hash attribute as well.

<!DOCTYPE html>\n<html>\n    <head>\n        <link\n            rel=\"stylesheet\"\n            type=\"text/css\"\n            href=\"https://d3mi6d1ao3fzsg.cloudfront.net/webpush/1/webpush.min.css\"\n        />\n    </head>\n    <body>\n        <script\n            type=\"application/javascript\"\n            src=\"https://d3mi6d1ao3fzsg.cloudfront.net/webpush/1/webpush.min.js\"\n            data-secure-hash=\"3179e184a6f9e3g6fbd2d1b12ae2dfd0bd01ba340dd153d4163d692554f8c11e\"\n            async\n        ></script>\n    </body>\n</html>\n

Example page 3

A page with push notifications and no Inbox. If you're using the NOT_SENSITIVE option where the user hash is sent in the page URL, remove the data-secure-hash attribute as well.

<!DOCTYPE html>\n<html>\n    <head>\n        <link\n            rel=\"stylesheet\"\n            type=\"text/css\"\n            href=\"https://d3mi6d1ao3fzsg.cloudfront.net/webpush/1/webpush.min.css\"\n        />\n    </head>\n    <body>\n        <a onclick=\"Symplify.WebPush.subscribeToPush()\"\n            >Enable Push Notifications</a\n        >\n        <br />\n        <a onclick=\"Symplify.WebPush.unsubscribeFromPush()\"\n            >Disable Push Notifications</a\n        >\n\n        <script\n            type=\"application/javascript\"\n            src=\"https://d3mi6d1ao3fzsg.cloudfront.net/webpush/1/webpush.min.js\"\n            data-secure-hash=\"3179e184a6f9e3g6fbd2d1b12ae2dfd0bd01ba340dd153d4163d692554f8c11e\"\n            data-enable-api=\"true\"\n            data-notifications=\"true\"\n            data-service-worker=\"scripts/service-worker.min.js\"\n            async\n        ></script>\n    </body>\n</html>\n

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"What is it and what can I use it for?","slug":"what-is-it-and-what-can-i-use-it-for"},{"content":"Include the Symplify Web Push resources","slug":"include-the-symplify-web-push-resources"},{"content":"How to identify the recipient","slug":"how-to-identify-the-recipient"},{"content":"Push Notifications","slug":"push-notifications"},{"content":"Privacy Levels","slug":"privacy-levels"},{"content":"Inbox Header and Footer","slug":"inbox-header-and-footer"},{"content":"Inbox List Item Template","slug":"inbox-list-item-template"},{"content":"Inbox Configuration","slug":"inbox-configuration"},{"content":"Inbox Types","slug":"inbox-types"},{"content":"Example page 1","slug":"example-page-1"},{"content":"Example page 2","slug":"example-page-2"},{"content":"Example page 3","slug":"example-page-3"}],"owner":"6437984","collectionId":"e6b30238-4fa0-4866-856f-904382331597","publishedId":"TW6uqA8w","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"publishDate":"2021-01-26T10:09:32.000Z"},"item":[],"event":[{"listen":"prerequest","script":{"id":"8c73c26c-8fbc-4c18-bd3d-4beec9bd8c82","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"63ae6707-e563-439e-8564-7bd8366fb89c","type":"text/javascript","exec":[""]}}]}