{"_id":"5901b81662655c0f005c7293","parentDoc":null,"version":{"_id":"5540ce1c31827a0d007ab1cf","project":"5540ce1b31827a0d007ab1cc","__v":31,"createdAt":"2015-04-29T12:27:08.390Z","releaseDate":"2015-04-29T12:27:08.390Z","categories":["5540ce1c31827a0d007ab1d0","5540d91bbb9e762d00f594ad","5540e5f131827a0d007ab212","5540e5febb9e762d00f594d3","5540e61331827a0d007ab213","5540e6195cf9682100d61afa","5540e62631827a0d007ab214","5540e63031827a0d007ab215","5540e63531827a0d007ab216","5540e63e5cf9682100d61afc","5540e6445cf9682100d61afd","5540e64a5cf9682100d61afe","55a4ff5b2e70c0250038050f","55acb28318eefd0d0071d504","55ae1abe8576b92300291c80","55ae453ef302af23000ac109","55af586d555b900d0036d296","55af91dac8a85321007a53c3","55b9fee204775a2f00628071","55b9ff0e04775a2f00628072","55b9ff4604775a2f00628073","55b9ff5fd72d1e1900276a38","55b9ff7f04775a2f00628074","55b9ff90eb08801900f833e5","55b9ffa5d72d1e1900276a39","55b9ffca04775a2f00628075","55b9fffdd72d1e1900276a3a","56bc2f033ee9e70d008b46af","56c2f6efbbf9ec2d00e0fe4f","57595bbb18760817001e8bbe","57d8d9793916800e003dde53"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"category":{"_id":"5540e63e5cf9682100d61afc","pages":["55af4832555b900d0036d263","55c4d11e8b45eb0d004cfbd6","5698de7503721e0d0043a365"],"project":"5540ce1b31827a0d007ab1cc","__v":3,"version":"5540ce1c31827a0d007ab1cf","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-04-29T14:10:06.818Z","from_sync":false,"order":11,"slug":"chrome","title":"Chrome"},"__v":0,"user":"55b125feae3b7621003e6482","project":"5540ce1b31827a0d007ab1cc","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-04-27T09:21:26.947Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":6,"body":"[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Supports Safari, Chrome, Firefox\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"To proceed with the integration of Web Push SDK to your HTTPS website, you should do the following:\\n\\n1. Locate your Pushwoosh Application Code.\\n2. Chrome and Firefox: locate your [**Google Project Number/Sender ID**](http://docs.pushwoosh.com/docs/fcm-configuration).\\n3. Safari: locate your [**Website Push ID**](http://docs.pushwoosh.com/docs/safari-website-notifications#1-registering-with-apple).\\n4. Download [**Pushwoosh Web Push SDK**](https://cdn.pushwoosh.com/webpush/v3/PushwooshWebSDKFiles.zip).\",\n  \"title\": \"Prerequisites\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"* Chrome pushes will not work with **self-signed** certificates (https/ssl). You'll need SSL certificate signed by trusted Authority.\\n* Push notifications don't work in Incognito mode.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Integration\"\n}\n[/block]\n[**Integration sample on GitHub**](https://github.com/Pushwoosh/web-push-notifications-sample)\n\n**1.** Get Pushwoosh Web Push SDK and unzip it. You should have the following files:\n\n* **manifest.json**\n* **pushwoosh-service-worker.js**\n\n**2.** Open **manifest.json** and make the following changes:\n\n**2.1.** Change `name` and `short_name` to the name of your website.\n**2.2.** Change `gcm_sender_id` to your [Sender ID](http://docs.pushwoosh.com/docs/fcm-configuration). Please keep in mind that Sender ID is usually a 12-digit number, and it *can't contain any letters*.\n\n**3.** Place all these files to top-level root of your website directory.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Make sure the following URLs are publicly accessible:\\n\\n* https://yoursite.com/manifest.json\\n* https://yoursite.com/pushwoosh-service-worker.js\",\n  \"title\": \"\"\n}\n[/block]\n**4.** Initialize the SDK:\n\n**4.1.** Include **manifest.json** in `<head>` (not `<body>`). \n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"* Make sure `<link rel=\\\"manifest\\\" href=\\\"/manifest.json\\\">` is located above other `<link rel=\\\"manifest\\\" ...>` in the `<head>`, or it won't be found.\",\n  \"title\": \"\"\n}\n[/block]\n**4.2.** Include the SDK from our CDN *asynchronously*.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<script type=\\\"text/javascript\\\" src=\\\"//cdn.pushwoosh.com/webpush/v3/pushwoosh-web-notifications.js\\\" async></script>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n**4.3.** Initialize the Web Push SDK and make sure to queue the initialization until the moment the SDK is fully loaded. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<script type=\\\"text/javascript\\\">\\nvar Pushwoosh = Pushwoosh || [];\\nPushwoosh.push(['init', {\\n    logLevel: 'info', // possible values: error, info, debug\\n    applicationCode: 'XXXXX-XXXXX', // you application code from Pushwoosh Control Panel\\n    safariWebsitePushID: 'web.com.example.domain', //  unique reverse-domain string, obtained in you Apple Developer Portal\\n    defaultNotificationTitle: 'Pushwoosh', // sets a default title for push notifications\\n    defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png', // URL to custom custom notification image\\n    autoSubscribe: true, // or false. If true, promts a user to subscribe for pushes upon SDK initialization\\n    userId: 'userId', // optional, set custom user ID\\n    tags: {\\n        'Name': 'John Smith'   \\t// optional, set custom Tags\\n    }\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\n}]);\\n</script>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Basically, there are two ways you can prompt a user to subscribe for pushes:\\n\\n1. Automatically upon the SDK initialization by setting the `autoSubscribe` parameter to `true`\\n2. Manually, when you set the `autoSubscribe` parameter to `false` and call the [**Pushwoosh.subscribe()**](http://docs.pushwoosh.com/docs/web-push-sdk-30#public-methods) method by yourself at any convenient moment.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Registering service worker in a different scope\"\n}\n[/block]\nSometimes you can't place the service worker file in a root directory of a website but in a subdirectory.\nHere's the steps you should take to integrate Pushwoosh Web SDK in this case:\n\n1. Let's assume you can place the files in a subdirectory of your website only, for example **yourdomain.com/push-notifications**. Place *manifest.json* and *pushwoosh-service-worker.js* into the subdirectory and follow the steps **2 - 4.2** of the standard guide.\n2. Modify the configuration (**step 4.3**) by adding a parameter `scope: “/push-notifications”` where */push-notifications* is the name of the subdirectory with *manifest.json* and *pushwoosh-service-worker.js*.\n3. Add the mechanism that redirects a user to this subdirectory on your site like **yourdomain.com/push-notifications/index.html**.\n4. Add the button that registers user for pushes. This could be a button for example with *onClick* handler set to trigger `Pushwoosh.subscribe()`. Alternatively you can use auto subscription with `autoSubscribe: true` parameter during Web SDK initializer.\n5. Use the Event listener `onPermissionGranted` (http://docs.pushwoosh.com/docs/web-push-sdk-30#section-permission-tracking-listeners) in order to redirect user back to the main page when he succeeded with the subscription.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Event Listeners\"\n}\n[/block]\nIn Pushwoosh Web SDK 3.0 you can subscribe to certain events to track them. The first argument in each callback is an [**API**](http://docs.pushwoosh.com/v1.0/docs/web-push-sdk-30#api) object.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// Executed after successful SDK initialization. \\n\\nPushwoosh.push(['onReady', function(api) {\\n    console.log('Pushwoosh ready');\\n}]);\",\n      \"language\": \"javascript\",\n      \"name\": \"onReady \"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Pushwoosh.push(function(api) {\\n  console.log('Pushwoosh ready');\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"A bit easier way to subscribe to onReady\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// Executed after a user agrees to receive push notifications. \\n\\nPushwoosh.push(['onSubscribe', function(api) {\\n    console.log('Event: onSubscribe triggered');\\n}]);\",\n      \"language\": \"javascript\",\n      \"name\": \"onSubscribe\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"//  Executed after a device is unregistered from notifications.\\n\\nPushwoosh.push(['onUnsubscribe', function(api) {\\n    console.log('Event: onUnsubscribe triggered');\\n}]);\",\n      \"language\": \"javascript\",\n      \"name\": \"onUnsubscribe\"\n    }\n  ]\n}\n[/block]\n## permission tracking listeners\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// Executed during the SDK initialization if 'autoSubscribe: false' or/and if a user ignores a push notification promt.\\n\\nPushwoosh.push(['onPermissionPrompt', function(api) {\\n    console.log('Event: onPermissionPrompt triggered');\\n}]);\",\n      \"language\": \"javascript\",\n      \"name\": \"onPermissionPrompt\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// Executed during the SDK initialization if a user blocks push notifications.\\n\\nPushwoosh.push(['onPermissionDenied', function(api) {\\n    console.log('Event: onPermissionDenied triggered');\\n}]);\",\n      \"language\": \"javascript\",\n      \"name\": \"onPermissionDenied\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// Executed during the SDK initialization if a user allows push notifications.\\n\\nPushwoosh.push(['onPermissionGranted', function(api) {\\n    console.log('Event: onPermissionGranted triggered');\\n}]);\",\n      \"language\": \"javascript\",\n      \"name\": \"onPermissionGranted\"\n    }\n  ]\n}\n[/block]\n## Notification tracking listeners\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Callbacks for the listeners below have two parameters:\\n\\n1. An [**API**](http://docs.pushwoosh.com/v1.0/docs/web-push-sdk-30#api) object \\n2. Push notification payload\",\n  \"title\": \"\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// Executed when a push notification is displayed.\\n\\nPushwoosh.push(['onPushDelivery', function(api, payload) {\\n    console.log('Event: onPushDelivery triggered', payload);\\n}]);\",\n      \"language\": \"javascript\",\n      \"name\": \"onPushDelivery\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var payload = {\\n  title: 'Notification Title',\\n  body: 'Notification text message',\\n  icon: 'https://yoursite.com/img/logo-medium.png',\\n  openUrl: 'https://yoursite.com/some/path',\\n  messageHash: '2m',\\n  customData: {\\n    foo: 'bar'\\n  }\\n};\",\n      \"language\": \"javascript\",\n      \"name\": \"onPushDelivery payload example\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// Executed when a user clicks on notification.\\n\\nPushwoosh.push(['onNotificationClick', function(api, payload) {\\n    console.log('Event: onNotificationClick triggered', payload);\\n}]);\",\n      \"language\": \"javascript\",\n      \"name\": \"onNotificationClick\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var payload = {\\n  url: 'https://yoursite.com/some/path',\\n  messageHash: '2m'\\n};\",\n      \"language\": \"javascript\",\n      \"name\": \"onNotificationClick payload example\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// Executed when a push notification is closed.\\n\\nPushwoosh.push(['onNotificationClose', function(api, payload) {\\n    console.log('Event: onNotificationClose triggered', payload);\\n}]);\",\n      \"language\": \"javascript\",\n      \"name\": \"onNotificationClose\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var payload = {\\n  url: 'https://yoursite.com/some/path',\\n  messageHash: '2m'\\n};\",\n      \"language\": \"javascript\",\n      \"name\": \"onNotificationClose payload example\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"API\"\n}\n[/block]\nAfter the Web Push SDK is initialized, you can make the following calls to Pushwoosh API. All the methods return [**Promise**](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) objects.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Pushwoosh.push(function(api) {\\n  // Set tags for a user\\n  api.setTags({\\n    'Tag Name 1' => 'value1',\\n    'Tag Name 2' => 'value2'\\n  });\\n \\n  // Get tags for a user from server\\n  api.getTags();\\n   \\n  // Register user ID\\n  api.registerUser('myUserID');\\n  \\n  // Post an Event\\n  api.postEvent('myEventName', {attributeName: 'attributeValue'});\\n\\n \\t//Unregister from notifications\\n  api.unregisterDevice();\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nExample of sending Tags to Pushwoosh:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Pushwoosh.push(function(api) {\\n  var myCustomTags = {\\n    'Tag 1': 123,\\n    'Tag 2': 'some string'\\n  };\\n  api.setTags(myCustomTags)\\n    .then(function(res) {\\n      var skipped = res && res.skipped || [];\\n      if (!skipped.length) {\\n        console.log('success');\\n      }\\n      else {\\n        console.warn('skipped tags:', skipped);\\n      }\\n    })\\n    .catch(function(err) {\\n      console.error('setTags error:', err);\\n    });\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Public Methods\"\n}\n[/block]\n**Pushwoosh.subscribe()**\n\nThis method is used to request a user's permission for push notifications. If a user is already subscribed, the method will stop executing. \n\nIf a user hasn’t subscribed for pushes yet:\n\n1. Permission for push notifications is requested.\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/527fe27-image2017-3-17_16_54_7.png\",\n        \"image2017-3-17 16_54_7.png\",\n        325,\n        132,\n        \"#e0e0df\"\n      ],\n      \"border\": true,\n      \"sizing\": \"smart\"\n    }\n  ]\n}\n[/block]\n2. If a user allows notifications, `onSubscribe` event is triggered.\n\n`Pushwoosh.subscribe()` is executed automatically if `autoSubscribe: true`. is set during the SDK initialization.\n\nCall this method if you have chosen to manually prompt a user to subscribe for pushes using the `autoSubscribe: false` parameter during the initialization:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<button onclick=\\\"Pushwoosh.subscribe()\\\">Subscribe</button>\\n<script>\\n  Pushwoosh.push(['onSubscribe', function(api) {\\n    console.log('User successfully subscribed');\\n  }]);\\n</script>\",\n      \"language\": \"javascript\",\n      \"name\": \"Example\"\n    }\n  ]\n}\n[/block]\n**Pushwoosh.unsubscribe()**\n    \n1. [`/unregisterDevice`](http://docs.pushwoosh.com/docs/unregisterdevice) method is executed.\n2. `onUnsubscribe` event is triggered.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<button onclick=\\\"Pushwoosh.unsubscribe()\\\">Unsubscribe</button>\\n<script>\\n  Pushwoosh.push(['onUnsubscribe', function(api) {\\n    console.log('User successfully unsubscribed');\\n  }]);\\n</script>\",\n      \"language\": \"javascript\",\n      \"name\": \"Example\"\n    }\n  ]\n}\n[/block]\n**Pushwoosh.isSubscribed()** \n\nChecks if a user is subscribed and returns true/false flag.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Pushwoosh.isSubscribed().then(function(isSubscribed) {\\n  console.log('isSubscribed', isSubscribed);\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"Example\"\n    }\n  ]\n}\n[/block]\n**Pushwoosh.getHWID()**\n\nReturns Pushwoosh HWID.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Pushwoosh.getHWID().then(function(hwid) {\\n    console.log('hwid:', hwid);\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"Example\"\n    }\n  ]\n}\n[/block]\n**Pushwoosh.getPushToken()** \n\nReturns push token if it is available.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Pushwoosh.getPushToken().then(function(pushToken) {\\n    console.log('pushToken:', pushToken);\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"Example\"\n    }\n  ]\n}\n[/block]\n**Pushwoosh.getUserId()**\n\nReturns [**User ID**](http://docs.pushwoosh.com/docs/user-id-push) if available.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Pushwoosh.getUserId().then(function(userId) {\\n    console.log('userId:', userId);\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"Example\"\n    }\n  ]\n}\n[/block]\n**Pushwoosh.getParams()**\n\nReturns a list of the following parameters:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Pushwoosh.getParams().then(function(params) {\\n  params = params || {};\\n  var hwid = params.hwid;\\n  var pushToken = params.pushToken;\\n  var userId = params.userId;\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"Example\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Progressive Web App support\"\n}\n[/block]\nThe latest version of Web Push SDK 3.0 supports PWA out of the box. There is on thing to keep in mind if you would like to use our WebSDK with PWA - service workers initialization behaviour.\n\nIn case you need to initialize it in one scope with PWA's service worker you don't need to register it separately, just add it into the importScripts within pushwoosh-service-worker.js:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"importScripts('https://cdn.pushwoosh.com/webpush/v3/pushwoosh-service-worker.js', 'PWA-service-worker.js') \\n// Where PWA-service-worker.js as a service worker of your Progressive Web App \",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nIf PWA and WebSDK scopes does not intersect with each other, then everything will work without additional changes. \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Install from npm\"\n}\n[/block]\nInstall Web Push SDK as a node module and save it as a dependency in your package.json:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"npm install web-push-notifications --save\",\n      \"language\": \"shell\",\n      \"name\": null\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var Pushwoosh = require('web-push-notifications').Pushwoosh;\\nvar pwInstance = new Pushwoosh();\\npwInstance.push(['init', {\\n    logLevel: 'info', // or debug\\n    applicationCode: 'XXXXX-XXXXX',\\n    safariWebsitePushID: 'web.com.example.domain',\\n    defaultNotificationTitle: 'Pushwoosh',\\n    defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png',\\n    autoSubscribe: true,\\n    userId: 'user_id',\\n    tags: {\\n        'Name': 'John Smith'\\n    }\\n}]);\",\n      \"language\": \"javascript\",\n      \"name\": \"CommonJS modules\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"import {Pushwoosh} from 'web-push-notifications';\\nconst pwInstance = new Pushwoosh();\\npwInstance.push(['init', {\\n    logLevel: 'info', // or debug\\n    applicationCode: 'XXXXX-XXXXX',\\n    safariWebsitePushID: 'web.com.example.domain',\\n    defaultNotificationTitle: 'Pushwoosh',\\n    defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png',\\n    autoSubscribe: true,\\n    userId: 'user_id',\\n    tags: {\\n        'Name': 'John Smith'\\n    }\\n}]);\",\n      \"language\": \"javascript\",\n      \"name\": \"Load WebPushSDK with ES6 modules\"\n    }\n  ]\n}\n[/block]","excerpt":"Unified Pushwoosh Web SDK: Easy way to send Safari, Chrome and Firefox Browser Pushes","slug":"web-push-sdk-30","type":"basic","title":"Web Push SDK 3.0"}

Web Push SDK 3.0

Unified Pushwoosh Web SDK: Easy way to send Safari, Chrome and Firefox Browser Pushes

[block:callout] { "type": "success", "title": "Supports Safari, Chrome, Firefox" } [/block] [block:callout] { "type": "info", "body": "To proceed with the integration of Web Push SDK to your HTTPS website, you should do the following:\n\n1. Locate your Pushwoosh Application Code.\n2. Chrome and Firefox: locate your [**Google Project Number/Sender ID**](http://docs.pushwoosh.com/docs/fcm-configuration).\n3. Safari: locate your [**Website Push ID**](http://docs.pushwoosh.com/docs/safari-website-notifications#1-registering-with-apple).\n4. Download [**Pushwoosh Web Push SDK**](https://cdn.pushwoosh.com/webpush/v3/PushwooshWebSDKFiles.zip).", "title": "Prerequisites" } [/block] [block:callout] { "type": "info", "body": "* Chrome pushes will not work with **self-signed** certificates (https/ssl). You'll need SSL certificate signed by trusted Authority.\n* Push notifications don't work in Incognito mode." } [/block] [block:api-header] { "type": "basic", "title": "Integration" } [/block] [**Integration sample on GitHub**](https://github.com/Pushwoosh/web-push-notifications-sample) **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](http://docs.pushwoosh.com/docs/fcm-configuration). 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. [block:callout] { "type": "info", "body": "Make sure the following URLs are publicly accessible:\n\n* https://yoursite.com/manifest.json\n* https://yoursite.com/pushwoosh-service-worker.js", "title": "" } [/block] **4.** Initialize the SDK: **4.1.** Include **manifest.json** in `<head>` (not `<body>`). [block:callout] { "type": "warning", "body": "* Make sure `<link rel=\"manifest\" href=\"/manifest.json\">` is located above other `<link rel=\"manifest\" ...>` in the `<head>`, or it won't be found.", "title": "" } [/block] **4.2.** Include the SDK from our CDN *asynchronously*. [block:code] { "codes": [ { "code": "<script type=\"text/javascript\" src=\"//cdn.pushwoosh.com/webpush/v3/pushwoosh-web-notifications.js\" async></script>", "language": "html" } ] } [/block] **4.3.** Initialize the Web Push SDK and make sure to queue the initialization until the moment the SDK is fully loaded. [block:code] { "codes": [ { "code": "<script type=\"text/javascript\">\nvar Pushwoosh = Pushwoosh || [];\nPushwoosh.push(['init', {\n logLevel: 'info', // possible values: error, info, debug\n applicationCode: 'XXXXX-XXXXX', // you application code from Pushwoosh Control Panel\n safariWebsitePushID: 'web.com.example.domain', // unique reverse-domain string, obtained in you Apple Developer Portal\n defaultNotificationTitle: 'Pushwoosh', // sets a default title for push notifications\n defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png', // URL to custom custom notification image\n autoSubscribe: true, // or false. If true, promts a user to subscribe for pushes upon SDK initialization\n userId: 'userId', // optional, set custom user ID\n tags: {\n 'Name': 'John Smith' \t// optional, set custom Tags\n }\t\t\t\t\t\t\t\t\t\t\n}]);\n</script>", "language": "html" } ] } [/block] [block:callout] { "type": "info", "body": "Basically, there are two ways you can prompt a user to subscribe for pushes:\n\n1. Automatically upon the SDK initialization by setting the `autoSubscribe` parameter to `true`\n2. Manually, when you set the `autoSubscribe` parameter to `false` and call the [**Pushwoosh.subscribe()**](http://docs.pushwoosh.com/docs/web-push-sdk-30#public-methods) method by yourself at any convenient moment." } [/block] [block:api-header] { "title": "Registering service worker in a different scope" } [/block] Sometimes you can't place the service worker file in a root directory of a website but in a subdirectory. Here's the steps you should take to integrate Pushwoosh Web SDK in this case: 1. Let's assume you can place the files in a subdirectory of your website only, for example **yourdomain.com/push-notifications**. Place *manifest.json* and *pushwoosh-service-worker.js* into the subdirectory and follow the steps **2 - 4.2** of the standard guide. 2. Modify the configuration (**step 4.3**) by adding a parameter `scope: “/push-notifications”` where */push-notifications* is the name of the subdirectory with *manifest.json* and *pushwoosh-service-worker.js*. 3. Add the mechanism that redirects a user to this subdirectory on your site like **yourdomain.com/push-notifications/index.html**. 4. Add the button that registers user for pushes. This could be a button for example with *onClick* handler set to trigger `Pushwoosh.subscribe()`. Alternatively you can use auto subscription with `autoSubscribe: true` parameter during Web SDK initializer. 5. Use the Event listener `onPermissionGranted` (http://docs.pushwoosh.com/docs/web-push-sdk-30#section-permission-tracking-listeners) in order to redirect user back to the main page when he succeeded with the subscription. [block:api-header] { "type": "basic", "title": "Event Listeners" } [/block] In Pushwoosh Web SDK 3.0 you can subscribe to certain events to track them. The first argument in each callback is an [**API**](http://docs.pushwoosh.com/v1.0/docs/web-push-sdk-30#api) object. [block:code] { "codes": [ { "code": "// Executed after successful SDK initialization. \n\nPushwoosh.push(['onReady', function(api) {\n console.log('Pushwoosh ready');\n}]);", "language": "javascript", "name": "onReady " } ] } [/block] [block:code] { "codes": [ { "code": "Pushwoosh.push(function(api) {\n console.log('Pushwoosh ready');\n});", "language": "javascript", "name": "A bit easier way to subscribe to onReady" } ] } [/block] [block:code] { "codes": [ { "code": "// Executed after a user agrees to receive push notifications. \n\nPushwoosh.push(['onSubscribe', function(api) {\n console.log('Event: onSubscribe triggered');\n}]);", "language": "javascript", "name": "onSubscribe" } ] } [/block] [block:code] { "codes": [ { "code": "// Executed after a device is unregistered from notifications.\n\nPushwoosh.push(['onUnsubscribe', function(api) {\n console.log('Event: onUnsubscribe triggered');\n}]);", "language": "javascript", "name": "onUnsubscribe" } ] } [/block] ## permission tracking listeners [block:code] { "codes": [ { "code": "// Executed during the SDK initialization if 'autoSubscribe: false' or/and if a user ignores a push notification promt.\n\nPushwoosh.push(['onPermissionPrompt', function(api) {\n console.log('Event: onPermissionPrompt triggered');\n}]);", "language": "javascript", "name": "onPermissionPrompt" } ] } [/block] [block:code] { "codes": [ { "code": "// Executed during the SDK initialization if a user blocks push notifications.\n\nPushwoosh.push(['onPermissionDenied', function(api) {\n console.log('Event: onPermissionDenied triggered');\n}]);", "language": "javascript", "name": "onPermissionDenied" } ] } [/block] [block:code] { "codes": [ { "code": "// Executed during the SDK initialization if a user allows push notifications.\n\nPushwoosh.push(['onPermissionGranted', function(api) {\n console.log('Event: onPermissionGranted triggered');\n}]);", "language": "javascript", "name": "onPermissionGranted" } ] } [/block] ## Notification tracking listeners [block:callout] { "type": "info", "body": "Callbacks for the listeners below have two parameters:\n\n1. An [**API**](http://docs.pushwoosh.com/v1.0/docs/web-push-sdk-30#api) object \n2. Push notification payload", "title": "" } [/block] [block:code] { "codes": [ { "code": "// Executed when a push notification is displayed.\n\nPushwoosh.push(['onPushDelivery', function(api, payload) {\n console.log('Event: onPushDelivery triggered', payload);\n}]);", "language": "javascript", "name": "onPushDelivery" } ] } [/block] [block:code] { "codes": [ { "code": "var payload = {\n title: 'Notification Title',\n body: 'Notification text message',\n icon: 'https://yoursite.com/img/logo-medium.png',\n openUrl: 'https://yoursite.com/some/path',\n messageHash: '2m',\n customData: {\n foo: 'bar'\n }\n};", "language": "javascript", "name": "onPushDelivery payload example" } ] } [/block] [block:code] { "codes": [ { "code": "// Executed when a user clicks on notification.\n\nPushwoosh.push(['onNotificationClick', function(api, payload) {\n console.log('Event: onNotificationClick triggered', payload);\n}]);", "language": "javascript", "name": "onNotificationClick" } ] } [/block] [block:code] { "codes": [ { "code": "var payload = {\n url: 'https://yoursite.com/some/path',\n messageHash: '2m'\n};", "language": "javascript", "name": "onNotificationClick payload example" } ] } [/block] [block:code] { "codes": [ { "code": "// Executed when a push notification is closed.\n\nPushwoosh.push(['onNotificationClose', function(api, payload) {\n console.log('Event: onNotificationClose triggered', payload);\n}]);", "language": "javascript", "name": "onNotificationClose" } ] } [/block] [block:code] { "codes": [ { "code": "var payload = {\n url: 'https://yoursite.com/some/path',\n messageHash: '2m'\n};", "language": "javascript", "name": "onNotificationClose payload example" } ] } [/block] [block:api-header] { "title": "API" } [/block] After the Web Push SDK is initialized, you can make the following calls to Pushwoosh API. All the methods return [**Promise**](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) objects. [block:code] { "codes": [ { "code": "Pushwoosh.push(function(api) {\n // Set tags for a user\n api.setTags({\n 'Tag Name 1' => 'value1',\n 'Tag Name 2' => 'value2'\n });\n \n // Get tags for a user from server\n api.getTags();\n \n // Register user ID\n api.registerUser('myUserID');\n \n // Post an Event\n api.postEvent('myEventName', {attributeName: 'attributeValue'});\n\n \t//Unregister from notifications\n api.unregisterDevice();\n});", "language": "javascript" } ] } [/block] Example of sending Tags to Pushwoosh: [block:code] { "codes": [ { "code": "Pushwoosh.push(function(api) {\n var myCustomTags = {\n 'Tag 1': 123,\n 'Tag 2': 'some string'\n };\n api.setTags(myCustomTags)\n .then(function(res) {\n var skipped = res && res.skipped || [];\n if (!skipped.length) {\n console.log('success');\n }\n else {\n console.warn('skipped tags:', skipped);\n }\n })\n .catch(function(err) {\n console.error('setTags error:', err);\n });\n});", "language": "javascript", "name": "" } ] } [/block] [block:api-header] { "title": "Public Methods" } [/block] **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. [block:image] { "images": [ { "image": [ "https://files.readme.io/527fe27-image2017-3-17_16_54_7.png", "image2017-3-17 16_54_7.png", 325, 132, "#e0e0df" ], "border": true, "sizing": "smart" } ] } [/block] 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: [block:code] { "codes": [ { "code": "<button onclick=\"Pushwoosh.subscribe()\">Subscribe</button>\n<script>\n Pushwoosh.push(['onSubscribe', function(api) {\n console.log('User successfully subscribed');\n }]);\n</script>", "language": "javascript", "name": "Example" } ] } [/block] **Pushwoosh.unsubscribe()** 1. [`/unregisterDevice`](http://docs.pushwoosh.com/docs/unregisterdevice) method is executed. 2. `onUnsubscribe` event is triggered. [block:code] { "codes": [ { "code": "<button onclick=\"Pushwoosh.unsubscribe()\">Unsubscribe</button>\n<script>\n Pushwoosh.push(['onUnsubscribe', function(api) {\n console.log('User successfully unsubscribed');\n }]);\n</script>", "language": "javascript", "name": "Example" } ] } [/block] **Pushwoosh.isSubscribed()** Checks if a user is subscribed and returns true/false flag. [block:code] { "codes": [ { "code": "Pushwoosh.isSubscribed().then(function(isSubscribed) {\n console.log('isSubscribed', isSubscribed);\n});", "language": "javascript", "name": "Example" } ] } [/block] **Pushwoosh.getHWID()** Returns Pushwoosh HWID. [block:code] { "codes": [ { "code": "Pushwoosh.getHWID().then(function(hwid) {\n console.log('hwid:', hwid);\n});", "language": "javascript", "name": "Example" } ] } [/block] **Pushwoosh.getPushToken()** Returns push token if it is available. [block:code] { "codes": [ { "code": "Pushwoosh.getPushToken().then(function(pushToken) {\n console.log('pushToken:', pushToken);\n});", "language": "javascript", "name": "Example" } ] } [/block] **Pushwoosh.getUserId()** Returns [**User ID**](http://docs.pushwoosh.com/docs/user-id-push) if available. [block:code] { "codes": [ { "code": "Pushwoosh.getUserId().then(function(userId) {\n console.log('userId:', userId);\n});", "language": "javascript", "name": "Example" } ] } [/block] **Pushwoosh.getParams()** Returns a list of the following parameters: [block:code] { "codes": [ { "code": "Pushwoosh.getParams().then(function(params) {\n params = params || {};\n var hwid = params.hwid;\n var pushToken = params.pushToken;\n var userId = params.userId;\n});", "language": "javascript", "name": "Example" } ] } [/block] [block:api-header] { "title": "Progressive Web App support" } [/block] The latest version of Web Push SDK 3.0 supports PWA out of the box. There is on thing to keep in mind if you would like to use our WebSDK with PWA - service workers initialization behaviour. In case you need to initialize it in one scope with PWA's service worker you don't need to register it separately, just add it into the importScripts within pushwoosh-service-worker.js: [block:code] { "codes": [ { "code": "importScripts('https://cdn.pushwoosh.com/webpush/v3/pushwoosh-service-worker.js', 'PWA-service-worker.js') \n// Where PWA-service-worker.js as a service worker of your Progressive Web App ", "language": "javascript" } ] } [/block] If PWA and WebSDK scopes does not intersect with each other, then everything will work without additional changes. [block:api-header] { "type": "basic", "title": "Install from npm" } [/block] Install Web Push SDK as a node module and save it as a dependency in your package.json: [block:code] { "codes": [ { "code": "npm install web-push-notifications --save", "language": "shell", "name": null } ] } [/block] [block:code] { "codes": [ { "code": "var Pushwoosh = require('web-push-notifications').Pushwoosh;\nvar pwInstance = new Pushwoosh();\npwInstance.push(['init', {\n logLevel: 'info', // or debug\n applicationCode: 'XXXXX-XXXXX',\n safariWebsitePushID: 'web.com.example.domain',\n defaultNotificationTitle: 'Pushwoosh',\n defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png',\n autoSubscribe: true,\n userId: 'user_id',\n tags: {\n 'Name': 'John Smith'\n }\n}]);", "language": "javascript", "name": "CommonJS modules" } ] } [/block] [block:code] { "codes": [ { "code": "import {Pushwoosh} from 'web-push-notifications';\nconst pwInstance = new Pushwoosh();\npwInstance.push(['init', {\n logLevel: 'info', // or debug\n applicationCode: 'XXXXX-XXXXX',\n safariWebsitePushID: 'web.com.example.domain',\n defaultNotificationTitle: 'Pushwoosh',\n defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png',\n autoSubscribe: true,\n userId: 'user_id',\n tags: {\n 'Name': 'John Smith'\n }\n}]);", "language": "javascript", "name": "Load WebPushSDK with ES6 modules" } ] } [/block]