{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"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.\n\n# What is it and what can I use it for?\n\nSymplify 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.\n\nYou can of course personalize all messages and use the different Symplify modules, like Journeys and Campaigns to generate your Symplify Web Push messages.\n\n- Create welcome messages for new users with link and instructions for navigating the app or best use the application\n- Send a reminder that pops up after login so they remember to complete their registration with credit card, loyalty card and shipping address etc.\n- Showcase new features and encourage users to try them out\n- Send coupons and offers\n- Remind customers of abandoned carts or loyalty credits on their accounts\n- Offer order tracking after sales\n\n# Include the Symplify Web Push resources\n\nPlease 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:\n\nEuropean servers:\n\n https://d3mi6d1ao3fzsg.cloudfront.net/webpush\n\nNorth American servers:\n\n https://d2v4xhvyfyhzvd.cloudfront.net/webpush\n\nReach out to your Success manager if you are uncertain.\n\n_The examples below are using the European CDN._\n\n### Stylesheet\n\nThe 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 `` element of your page.\n\n```html\n\n```\n\n### Script\n\nThe 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.\n\nThe script is usually inserted immediately before the closing `` element of your page.\n\n```html\n\n```\n\n# How to identify the recipient\n\nWe 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.\n\nNOTE: 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](https://help.symplify.com/hc/en-us/articles/360011076720-API-overview)\n\nA basic usage pattern is:\n\n- The user logs in to your site.\n- Once you know the id of your user, call our user hash resource.\n- Cache the user hash in your web server session storage or in your database.\n - Do not call the user hash resource for every page.\n - User hashes are valid for 90 days.\n- Include the script on pages where Symplify Web Push messages should be displayed.\n\nSecure user hashes are generated using the REST resource `/webpush`.\n\n```\nPOST /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```\n\nAn example response would look like\n\n```\n{\n \"userHash\": \"e94187765acfe001e415107c68f6a6fd5e74b66042145fe28609787b2e881b67\"\n}\n```\n\n# Push Notifications\n\n_WIP - This text is under development and subject to change_\n\nSymplify 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.\n\nPush 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.\n\nThe 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.\n\nMake 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.\n\nWe will try to follow the guidelines for a good UX from (https://developers.google.com/web/fundamentals/push-notifications/permission-ux)\n\n- We will not show a push notification permission dialog by default when the page is loaded.\n- 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.\n\nThe 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.\n\n_(for test, this is https://d3mi6d1ao3fzsg.cloudfront.net/webpush/snapshot/service-worker.js)_\n\nYou need to download `https://d3mi6d1ao3fzsg.cloudfront.net/webpush/service-worker.min.js` and serve it from your own web site.\n\nYou will not get automatic updates for this script, please make manual updates regularly.\n\n*https://d3mi6d1ao3fzsg.cloudfront.net/webpush/1/version.json displays the version of the latest release*\n\nAdd these attributes to the web push script tag to enable push notifications:\n\n- `data-notifications=\"true\"` - default is `false`\n- `data-service-worker=\"scripts/service-worker.min.js\"` - path to the downloaded service worker script. default is `service-worker.min.js`\n\n```html\n \n```\n\n### Built in Push Notification management\n\nAdd a checkbox with `data-toggles=\"push:notifications\"` to the Inbox header or footer (View examples in the [Inbox Header and Footer](#inbox-header-and-footer) section).\n\n```html\n\n```\n\nOr use our prestyled markup in the Inbox header or footer.\n\n```html\n
\n \n
\n```\n\n![inbox-notifications](inbox-notifications.png)\n\n### Custom Push Notification management\n\nNote: You need to enable the client side API via `data-enable-api=\"true\"` as described earlier.\n\n```html\nEnable Push Notifications\nDisable Push Notifications\n```\n\nNative notifications will **not** be shown when:\n\n- 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).\n- A user has not allowed native notifications via the built in notification management in their operating system (MacOS, Windows, \\*nix, Android, IOS etc).\n- A user has not allowed native notifications for you web site via the built in notification management in their web browser.\n\n# Privacy Levels\n\n_NOTE: This section is only relevant if you cannot retrieve the user hash on the server side_\n\nSymplify 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.\n\n_The difference is in the control over which of your pages the user can receive Symplify Web Push messages._\n\nThe two types of user hashes are:\n\n- `NOT_SENSITIVE`\n - Added as a querystring parameter to each link that is clicked in a Symplify message.\n - Stored in a cookie in the users' browser. (and readable by inspecting browser cookies)\n - Readable over HTTP.\n - Readable in browser history.\n- `SENSITIVE`\n - Generated by the Symplify API.\n - Injected programmatically when rendering each page.\n - Only readable by inspecting the rendered page, disappears when the page is closed.\n\nUsing 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.\n\nBy 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.\n\nBy default, all Symplify Web Push messages are sent with PrivacyLevel.Sensitive.\n\nThis means that these messages will only be shown if the page use a secure user hash generated by the REST resource.\n\n# Inbox Header and Footer\n\nInclude a script tag with your own markup to get a custom Inbox header and/or footer.\n\nThese must have the ids `sym-inbox-header` and `sym-inbox-footer` respectively.\n\n```html\n\n```\n\n```html\n\n```\n\n# Inbox List Item Template\n\nInclude a script tag with the id `sym-inbox-list-item` with your own markup to customize how the inbox displays each message.\n\n```html\n\n```\n\n# Inbox Configuration\n\nIf 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.\n\nYou 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.\n\nSome optional settings require basic HTML and/or javascript knowledge.\n\n#### Minimal options\n\n```html\n\n```\n\n#### All options\n\n```html\n\n```\n\nOptions 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`\n\n```html\n\n\n```\n\n### Available options\n\n#### data-secure-hash (required)\n\nThe secure hash for the current user.\n\n- `data-secure-hash=\"e94187765acfe001e415107c68f6a6fd5e74b66042145fe28609787b2e881b67\"`\n\n#### data-inbox-element (optional)\n\nSelector 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.\n\n- `data-inbox-element=\"#my-inbox\"`\n\n[Query Selector documentation on MDN web docs ](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector) (external link)\n\n#### data-inbox-type (optional)\n\nSymplify 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.\n\n- `data-inbox-type=\"badge\"`\n\nRead more about our inbox types and their options [here](#inbox-types).\n\n#### data-inbox-list-element (optional)\n\nSelector for the element which should be used to list the inbox on the page.\n\n- `data-inbox-list-element=\"#my-inbox-messages\"`\n\n\n\n#### data-count-method (optional)\n\nEnables 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.\n\n- `data-count-method=\"top\"` - default is `all`\n\n#### data-get-latest-message (optional)\n\nIf this is set to true, the Symplify Web Push script will automatically fetch the latest message and show it if it is unread.\n\n- `data-get-latest-message=\"true\"` - default is `false`\n\n#### data-autostart (optional)\n\nEnables 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.\n\n- `data-autostart=\"false\"` - default is `true`\n\n```javascript\nSymplify.WebPush.start();\n```\n\n#### data-enable-api (optional)\n\nEnables a simple client side API which you can use to display pop ups similar to the ones sent via the Symplify Web Push service.\n\n- `data-enable-api=\"true\"` - default is `false`\n\nYou can use the API to show a pop up by using the `Symplify.WebPush.show` function.\n\n```javascript\nSymplify.WebPush.show(\n 'Become a member today!',\n '[pop up content]',\n 'BOTTOM_RIGHT'\n);\n```\n\nUse 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.\n\n```javascript\nmyApiCall().then(function (userHash) {\n Symplify.WebPush.start({\n secureHash: userHash,\n inboxElement: '#my-inbox-element',\n });\n});\n```\n\nUse the `Symplify.WebPush.stop` function to disable Web Push functionality and stop listening for Web Push Messages.\n\n```javascript\nlogout().then(function () {\n Symplify.WebPush.stop();\n});\n```\n\n# Inbox Types\n\nIf 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.\n\nProvided types are:\n\n#### default\n\n![default](custom.png)\n\n```html\n
Messages (1)
\n```\n\nNo 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.\n\n#### toggle\n\n![toggle](toggle.png)\n\n```html\n
\n```\n\n#### badge\n\n![badge](badge.png)\n\n```html\n
\n```\n\nIcon is not included, the badge is positioned with an offset relative to the last element in your inbox element\n\n#### badgeInline\n\n![badgeInline](badge-inline.png)\n\n```html\n
Notications
\n```\n\nText is not included, the badge is positioned relative to the last element in your inbox element\n\n#### badge-bell, badge-horn\n\n![badge-bell](badge-bell.png)\n\n```html\n
\n```\n\nIcon is included.\n\n# Example page 1\n\nA page with push notifications and an inbox with a header and footer.\n\n```html\n\n\n \n \n \n \n
\n\n \n\n \n\n \n \n\n```\n\n# Example page 2\n\nA 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.\n\n```html\n\n\n \n \n \n \n \n \n\n```\n\n# Example page 3\n\nA 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.\n\n```html\n\n\n \n \n \n \n Enable Push Notifications\n
\n Disable Push Notifications\n\n \n \n\n```","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"6437984","team":986301,"collectionId":"e6b30238-4fa0-4866-856f-904382331597","publishedId":"TW6uqA8w","public":true,"publicUrl":"https://documenter-api.postman.tech/view/6437984/TW6uqA8w","privateUrl":"https://go.postman.co/documentation/6437984-e6b30238-4fa0-4866-856f-904382331597","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"documentationLayout":"classic-double-column","customisation":null,"version":"8.10.0","publishDate":"2021-01-26T10:09:32.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/80e955b4527d2fa53b0159ea6f7f3af62d4e8614d5648f110bafc5f98c3125ea","favicon":"https://res.cloudinary.com/postman/image/upload/v1591213210/team/xhe8akpy9pzo9eocaz5l.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://documenter.gw.postman.com/view/metadata/TW6uqA8w"}