1. Get Pushwoosh Web Push SDK and unzip it. You should have the following files:
manifest.json
pushwoosh-service-worker.js
2. Open manifest.json and make the following changes:
2.1. Change name and short_name to the name of your website.
2.2. Change gcm_sender_id to your Sender ID. Please keep in mind that Sender ID is usually a 12-digit number, and it can't contain any letters.
3. Place all these files to top-level root of your website directory.
Make sure the following URLs are publicly accessible:
4.3. Initialize the Web Push SDK and make sure to queue the initialization until the moment the SDK is fully loaded.
<script type="text/javascript">
var Pushwoosh = Pushwoosh || [];
Pushwoosh.push(['init', {
logLevel: 'info', // possible values: error, info, debug
applicationCode: 'XXXXX-XXXXX', // you application code from Pushwoosh Control Panel
safariWebsitePushID: 'web.com.example.domain', // unique reverse-domain string, obtained in you Apple Developer Portal. Only needed if you send push notifications to Safari browser
defaultNotificationTitle: 'Pushwoosh', // sets a default title for push notifications
defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png', // URL to custom custom notification image
autoSubscribe: false, // or true. If true, prompts a user to subscribe for pushes upon SDK initialization
subscribeWidget: {
enable: true
},
userId: 'user_id', // optional, set custom user ID
tags: {
'Name': 'John Smith' // optional, set custom Tags
}
}]);
</script>
Push Subscription Button
To prompt your users to subscribe for push notifications, we recommend implementing a push subscription button on your website. Enhance user experience and get more subscribers!
Configuration
To finish implementing push notifications into your website, you need to configure web platforms in your Pushwoosh Control Panel following our step-by-step guides:
To subscribe to or unsubscribe from any of the SDK events, use the handlers after the SDK load:
Pushwoosh.push(['onLoad',function (api) {functiononEventNameHandler() {console.log('Triggered event: event-name!'); }// To subscribe to an event:Pushwoosh.addEventHandler('event-name', onEventNameHandler)// To unsubscribe from an event:Pushwoosh.removeEventHandler('event-name', onEventNameHandler)}]);
SDK events
Subscribe Event
Executed after a user agrees to receive push notifications.
Pushwoosh.push(['onLoad',function (api) {// Executed on displaying of the Subscription Prompt widgetPushwoosh.addEventHandler('show-subscription-widget',function (payload) {console.log('Triggered event: show-subscription-widget'); });// Executed on hiding of the Subscription Prompt widgetPushwoosh.addEventHandler('hide-subscription-widget',function (payload) {console.log('Triggered event: hide-subscription-widget'); });}]);
Notification Permission Dialog Events
Track displaying of native subscription dialog.
Pushwoosh.push(['onLoad',function (api) {// Executed on permission dialog displayingPushwoosh.addEventHandler('show-notification-permission-dialog',function (payload) {console.log('Triggered event: show-notification-permission-dialog'); });// Executed on hiding the permission dialog with one of three possible statuses: // 1. default - the dialog is closed // 2. granted - permission is granted // 3. denied - permission is deniedPushwoosh.addEventHandler('hide-notification-permission-dialog',function (payload) {console.log('Triggered event: hide-notification-permission-dialog',payload.permission); });}]);
Permission Events
Check the push notifications permission's status on SDK initialization; track the update of this status whenever it takes place.
Pushwoosh.push(['onLoad',function (api) { // Executed during the SDK initialization if 'autoSubscribe: false' or/and if a user ignores a push notification prompt.
Pushwoosh.addEventHandler('permission-default',function (payload) {console.log('Triggered event: permission-default'); });// Executed during the SDK initialization if notifications are blocked or once a user blocks push notifications.Pushwoosh.addEventHandler('permission-denied',function (payload) {console.log('Triggered event: permission-denied'); });// Executed during the SDK initialization if notifications are allowed or once a user allows push notifications.Pushwoosh.addEventHandler('permission-granted',function (payload) {console.log('Triggered event: permission-granted'); });}]);
Receive Push Event
Track push delivery to a device.
Pushwoosh.push(['onLoad',function (api) {// Executed when a push notification is displayed.Pushwoosh.addEventHandler('receive-push',function (payload) {console.log('Triggered event: receive-push',payload.notification); });}]);
Notification Events
Track whether a push notification is opened or closed by a user.
Pushwoosh.push(['onLoad',function (api) {// Executed when a user clicks on notification.Pushwoosh.addEventHandler('open-notification',function (payload) {console.log('Triggered event: open-notification',payload.notification); });// Executed when a user closes a push notification.Pushwoosh.addEventHandler('hide-notification',function (payload) {console.log('Triggered event: hide-notification',payload.notification); });}]);
Inbox Events
Track notifications sent to Inbox.
Pushwoosh.push(['onLoad',function (api) {// Executed by ServiceWorker after the Inbox Message is received and saved to indexedDB.Pushwoosh.addEventHandler('receive-inbox-message',function (payload) {console.log('Triggered event: receive-inbox-message',payload.message); });// Executed after the Inbox is updated automatically while the page is loading.Pushwoosh.addEventHandler('update-inbox-messages',function (payload) {console.log('Triggered event: receive-inbox-message',payload.messages); });}]);
// Executed when the custom subscription popup is shownPushwoosh.addEventHandler('subscribe-popup-show',function() {console.log("Triggered event: subscribe-popup-show"); })// Executed when a user clicks on the 'Subscribe' button in the pop-up windowPushwoosh.addEventHandler('subscribe-popup-accept',function() {console.log("Triggered event: subscribe-popup-accept"); })// Executed when a user clicks on the 'Ask later' button in the pop-up windowPushwoosh.addEventHandler('subscribe-popup-decline',function() {console.log("Triggered event: subscribe-popup-decline"); })// Executed when the popup hidesPushwoosh.addEventHandler('subscribe-popup-hide',function() {console.log("Triggered event: subscribe-popup-hide"); })
API
After the Web Push SDK is initialized, you can make the following calls to Pushwoosh API. All the methods return Promise objects.
Pushwoosh.push(function(api) {// Set tags for a userapi.setTags({'Tag Name 1':'value1','Tag Name 2':'value2' });// Get tags for a user from serverapi.getTags();// Register user IDapi.registerUser('myUserID');// Register user emailapi.registerEmail('<user_email>');// Post an Eventapi.postEvent('myEventName', {attributeName:'attributeValue'});//Unregister from notificationsapi.unregisterDevice();});
Please note that auto subscription is not available for Safari users. Please consider subscribing Safari users to push notifications by calling the Pushwoosh.subscribe() method.
Pushwoosh.subscribe()
This method is used to request a user's permission for push notifications. If a user is already subscribed, the method will stop executing.
If a user hasn’t subscribed for pushes yet:
1. Permission for push notifications is requested.
2. If a user allows notifications, onSubscribe event is triggered.
Pushwoosh.subscribe() is executed automatically if autoSubscribe: true. is set during the SDK initialization.
Call this method if you have chosen to manually prompt a user to subscribe for pushes using the autoSubscribe: false parameter during the initialization:
Pushwoosh.pwinbox.deleteMessagesWithCodes([code])
.then(() => {
console.log('Messages have been deleted');
});
syncMessages(): Promise<void>
Synchronizes messages with the server.
Pushwoosh.pwinbox.syncMessages()
.then(() => {
console.log('Messages have been synchronized');
});
Progressive Web App support
To integrate Pushwoosh into your Progressive Web Application (PWA), follow the steps described below.
1. Copy the path to your Service Worker file:
if ('serviceWorker'in navigator) {window.addEventListener('load', () => {navigator.serviceWorker.register('/service-worker.js') // <- your service worker url });}
Then, use the serviceWorkerUrl parameter while initializing the WebSDK as follows:
var Pushwoosh = Pushwoosh || [];Pushwoosh.push(['init', { logLevel:'error', applicationCode:'XXXXX-XXXXX', safariWebsitePushID:'web.com.example.domain', defaultNotificationTitle:'Pushwoosh', defaultNotificationImage:'https://yoursite.com/img/logo-medium.png', serviceWorkerUrl:'/service-worker.js',// <- your service worker url}]);
WebSDK does not register the new Service Worker immediately; a Service Worker is registered when it's needed:
when a device receives a push token (on device registration or re-subscription),
when a push token is deleted (on removing a device from user base).
It speeds your pages loading by shortening the number of server requests.
Browsers do not allow two different Service Workers to be registered at the same time (read more: https://github.com/w3c/ServiceWorker/issues/921), so to make your PWA work correctly, a common Service Worker should be registered for your codebase and the Pushwoosh codebase.
2. Add the following string to your Service Worker (at the beginning or at the end of, it doesn’t matter):
ServiceWorker compatible with a package version is located in node_modules/web-push-notifications/lib/service-worker.js only for Web Push SDK 3.2.7 and higher. Please note that interactions between Web Push SDK and ServiceWorker could differ for different versions, so it’s essential to use the ServiceWorker compatible with the Web Push SDK version you use.
Install Web Push SDK as a node module and save it as a dependency in your package.json:
Shell
npm install web-push-notifications --save
CommonJS modules
var Pushwoosh = require('web-push-notifications').Pushwoosh;
var pwInstance = new Pushwoosh();
pwInstance.push(['init', {
logLevel: 'info', // or debug
applicationCode: 'XXXXX-XXXXX',
safariWebsitePushID: 'web.com.example.domain',
defaultNotificationTitle: 'Pushwoosh',
defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png',
autoSubscribe: true,
userId: 'user_id',
tags: {
'Name': 'John Smith'
}
}]);
Make sure to follow this guide's steps 1 to 4 before adding the script to Google Manager Tag!
Use the following code in your Google Tag Manager to initialize Pushwoosh SDK. Create a Custom HTML Tag and paste the code below. Make sure to change your Pushwoosh Application Code, Safari Website ID, and default notification image URL.
Also set high Tag Firing priority (ex: 100) and trigger it on All Pages. See below for a screenshot.Copy