{"_id":"588fcec7762db13100dfe6aa","version":{"_id":"588f722bbcace50f0052b9e1","project":"565f5fa26bafd40d0030a064","__v":1,"createdAt":"2017-01-30T17:04:43.410Z","releaseDate":"2017-01-30T17:04:43.410Z","categories":["588f722bbcace50f0052b9e2","588f722bbcace50f0052b9e3","588f722bbcace50f0052b9e4","588f722bbcace50f0052b9e5","588f722bbcace50f0052b9e6","588f722bbcace50f0052b9e7"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"5.3.0","version":"5.3.0"},"category":{"_id":"588f722bbcace50f0052b9e3","version":"588f722bbcace50f0052b9e1","project":"565f5fa26bafd40d0030a064","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-12-09T21:22:52.427Z","from_sync":false,"order":1,"slug":"user-guide","title":"Reference"},"parentDoc":null,"user":"588f6dbe6bc3360f0068d2a1","project":"565f5fa26bafd40d0030a064","__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-01-30T23:39:51.578Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":15,"body":"To understand how to use Push Messaging, it is important to understand the concept of Channels and Devices. A Channel is a way to send targeted push notifications to specific users. You define as many Channels as you need to segment push notifications.  A user registers a \"Device\" and calls a Subscribe API effectively creating an association between Channel and Device. When sending a push notification, the Channel is a parameter that is used to determine which Devices will receive the push notification. Use the Unsubscribe API to disassociate the Channel and Device when a user no longer desires to receive the push notification.\n\nIn the case of Apple and Google push notifications, the Device is the Device token obtained from Apple or Google that represent is used when sending the message payload to Apple or Google so those platforms know the identity of the device receiving the notification.  \n\nUnder the Manage dashboard, select Push to view the list of Channels, Devices, and Messages for the account. The list of Channels, Devices and Messages is aggregated across all APIs under the account.  If running nanoscale.io locally, the data is stored in the same database as the API configuration data, either SQL Lite or Postgres, depending if [running in Local or Server mode](http://devhub.nanoscale.io/v5.3.0/docs/running-justapis).  \n\nChannels can either be manually created/edited within the nanoscale.io Admin interface, but more commonly, created dynamically when a Device subscribes to a Channel. \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/8e076ce-channel-list.png\",\n        \"channel-list.png\",\n        1272,\n        355,\n        \"#f6f6f6\"\n      ]\n    }\n  ]\n}\n[/block]\nSelect the Channel name to drill into the list of Devices associated to the Channel. In the example below, Device \"ABCDEF\" is subscribed to Channel \"Ios_chnl\".  This is the only Device subscribed to this Channel. \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/47fa033-devices-channels-assoc.png\",\n        \"devices-channels-assoc.png\",\n        978,\n        356,\n        \"#f5f5f5\"\n      ]\n    }\n  ]\n}\n[/block]\n###Subscribe and Unsubscribe to a Channel\n\nWhen an app subscribes to a Channel, if the Channel record does not exist, it will automatically get created along with the record associating the Device to the Channel. The subscribe API is available when a Push Remote endpoint is created provided the `Subscribe endpoint` boolean field on the Remote endpoint is checked.\n\nIn the example below, replace [HOST] with the API host and [REMOTE ENDPOINT NAME] with the name of the Push Remote Endpoint.  \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"POST https://[HOST]/push/[REMOTE ENDPOINT NAME]/subscribe\\n\\n{\\\"platform\\\":\\\"ios\\\",\\n\\\"channel\\\":\\\"ios_chnl\\\",\\n\\\"period\\\":31536000,\\n\\\"name\\\":\\\"ABCDEF\\\",\\n\\\"token\\\":\\\"ABCDEF\\\"}\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nThe properties for the subscribe body are:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"property\",\n    \"h-1\": \"type\",\n    \"h-2\": \"description\",\n    \"0-0\": \"platform\",\n    \"0-1\": \"`string`\",\n    \"0-2\": \"Name of the push platform added under the Push Remote endpoint\",\n    \"1-0\": \"channel\",\n    \"1-1\": \"`string`\",\n    \"3-1\": \"`string`\",\n    \"2-1\": \"`number`\",\n    \"4-1\": \"`string`\",\n    \"2-0\": \"period\",\n    \"2-2\": \"Time in seconds to set an expiration for when the Device will no longer receive a push message for the Channel.\",\n    \"3-0\": \"name\",\n    \"4-0\": \"token\",\n    \"3-2\": \"Name of the Device.  This value can be anything you define.\",\n    \"4-2\": \"Device token, typically the token received from Apple or Google to create a unique identifier for the device and app combination.\",\n    \"1-2\": \"Name of the Channel.  This value can be anything you define.\",\n    \"5-0\": \"QOS\",\n    \"5-2\": \"\"\n  },\n  \"cols\": 3,\n  \"rows\": 5\n}\n[/block]\nThe unsubscribe call is similar to the subscribe call with the exception of a less fields required in the body of the payload.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"POST https://[HOST]/push/[REMOTE ENDPOINT NAME]/unsubscribe\\n\\n{\\\"platform\\\":\\\"ios\\\",\\n\\\"channel\\\":\\\"ios_chnl\\\",\\n\\\"name\\\":\\\"ABCDEF\\\",\\n\\\"token\\\":\\\"ABCDEF\\\"}\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n### Sending a Push Message\n\nA Push API is available when a Push Remote endpoint is created provided the `Publish endpoint` boolean field on the Remote endpoint is checked. This exposes an API that an external system can invoke to send a push notification to all devices subscribed to the channel. \n\nThe examples below are for sending a push notification to both Apple and Google. Replace [HOST] with the API host and [REMOTE ENDPOINT NAME] with the name of the Push Remote Endpoint.  \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"POST https://[HOST]/push/[REMOTE ENDPOINT NAME/publish\\n\\n{\\\"payload\\\":{ \\\"ios\\\": \\n{ \\\"aps\\\": { \\n   \\\"data\\\": { \\\"id\\\": \\\"1234\\\" }, \\n   \\\"alert\\\": \\\"Hello World\\\", \\n   \\\"sound\\\": \\\"default\\\" } \\n    }}, \\n   \\\"channel\\\":\\\"ios_chnl\\\", \\n   \\\"environment\\\":\\\"development\\\"\\n   }\",\n      \"language\": \"curl\",\n      \"name\": \"push api for sending to Apple Push Notification service\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\\"payload\\\":{ \\\"fcm\\\": \\n{ \\\"fcm\\\":{\\\"notification\\\" : {\\n      \\\"body\\\" : \\\"This is a message\\\",\\n      \\\"title\\\" : \\\"Hellow World\\\",\\n      \\\"icon\\\" : \\\"myicon\\\"\\n    },\\n    \\\"data\\\" : {\\n      \\\"id\\\" : \\\"1234\\\"}}}, \\n   \\\"channel\\\":\\\"sample\\\", \\n   \\\"environment\\\":\\\"development\\\"\\n}      \",\n      \"language\": \"curl\",\n      \"name\": \"push api for sending to Google Firebase Cloud Messaging service\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"manage-push-channels-devices-and-messages","type":"basic","title":"Push Channels, Devices, and Messages"}

Push Channels, Devices, and Messages


To understand how to use Push Messaging, it is important to understand the concept of Channels and Devices. A Channel is a way to send targeted push notifications to specific users. You define as many Channels as you need to segment push notifications. A user registers a "Device" and calls a Subscribe API effectively creating an association between Channel and Device. When sending a push notification, the Channel is a parameter that is used to determine which Devices will receive the push notification. Use the Unsubscribe API to disassociate the Channel and Device when a user no longer desires to receive the push notification. In the case of Apple and Google push notifications, the Device is the Device token obtained from Apple or Google that represent is used when sending the message payload to Apple or Google so those platforms know the identity of the device receiving the notification. Under the Manage dashboard, select Push to view the list of Channels, Devices, and Messages for the account. The list of Channels, Devices and Messages is aggregated across all APIs under the account. If running nanoscale.io locally, the data is stored in the same database as the API configuration data, either SQL Lite or Postgres, depending if [running in Local or Server mode](http://devhub.nanoscale.io/v5.3.0/docs/running-justapis). Channels can either be manually created/edited within the nanoscale.io Admin interface, but more commonly, created dynamically when a Device subscribes to a Channel. [block:image] { "images": [ { "image": [ "https://files.readme.io/8e076ce-channel-list.png", "channel-list.png", 1272, 355, "#f6f6f6" ] } ] } [/block] Select the Channel name to drill into the list of Devices associated to the Channel. In the example below, Device "ABCDEF" is subscribed to Channel "Ios_chnl". This is the only Device subscribed to this Channel. [block:image] { "images": [ { "image": [ "https://files.readme.io/47fa033-devices-channels-assoc.png", "devices-channels-assoc.png", 978, 356, "#f5f5f5" ] } ] } [/block] ###Subscribe and Unsubscribe to a Channel When an app subscribes to a Channel, if the Channel record does not exist, it will automatically get created along with the record associating the Device to the Channel. The subscribe API is available when a Push Remote endpoint is created provided the `Subscribe endpoint` boolean field on the Remote endpoint is checked. In the example below, replace [HOST] with the API host and [REMOTE ENDPOINT NAME] with the name of the Push Remote Endpoint. [block:code] { "codes": [ { "code": "POST https://[HOST]/push/[REMOTE ENDPOINT NAME]/subscribe\n\n{\"platform\":\"ios\",\n\"channel\":\"ios_chnl\",\n\"period\":31536000,\n\"name\":\"ABCDEF\",\n\"token\":\"ABCDEF\"}", "language": "curl" } ] } [/block] The properties for the subscribe body are: [block:parameters] { "data": { "h-0": "property", "h-1": "type", "h-2": "description", "0-0": "platform", "0-1": "`string`", "0-2": "Name of the push platform added under the Push Remote endpoint", "1-0": "channel", "1-1": "`string`", "3-1": "`string`", "2-1": "`number`", "4-1": "`string`", "2-0": "period", "2-2": "Time in seconds to set an expiration for when the Device will no longer receive a push message for the Channel.", "3-0": "name", "4-0": "token", "3-2": "Name of the Device. This value can be anything you define.", "4-2": "Device token, typically the token received from Apple or Google to create a unique identifier for the device and app combination.", "1-2": "Name of the Channel. This value can be anything you define.", "5-0": "QOS", "5-2": "" }, "cols": 3, "rows": 5 } [/block] The unsubscribe call is similar to the subscribe call with the exception of a less fields required in the body of the payload. [block:code] { "codes": [ { "code": "POST https://[HOST]/push/[REMOTE ENDPOINT NAME]/unsubscribe\n\n{\"platform\":\"ios\",\n\"channel\":\"ios_chnl\",\n\"name\":\"ABCDEF\",\n\"token\":\"ABCDEF\"}", "language": "curl" } ] } [/block] ### Sending a Push Message A Push API is available when a Push Remote endpoint is created provided the `Publish endpoint` boolean field on the Remote endpoint is checked. This exposes an API that an external system can invoke to send a push notification to all devices subscribed to the channel. The examples below are for sending a push notification to both Apple and Google. Replace [HOST] with the API host and [REMOTE ENDPOINT NAME] with the name of the Push Remote Endpoint. [block:code] { "codes": [ { "code": "POST https://[HOST]/push/[REMOTE ENDPOINT NAME/publish\n\n{\"payload\":{ \"ios\": \n{ \"aps\": { \n \"data\": { \"id\": \"1234\" }, \n \"alert\": \"Hello World\", \n \"sound\": \"default\" } \n }}, \n \"channel\":\"ios_chnl\", \n \"environment\":\"development\"\n }", "language": "curl", "name": "push api for sending to Apple Push Notification service" } ] } [/block] [block:code] { "codes": [ { "code": "{\"payload\":{ \"fcm\": \n{ \"fcm\":{\"notification\" : {\n \"body\" : \"This is a message\",\n \"title\" : \"Hellow World\",\n \"icon\" : \"myicon\"\n },\n \"data\" : {\n \"id\" : \"1234\"}}}, \n \"channel\":\"sample\", \n \"environment\":\"development\"\n} ", "language": "curl", "name": "push api for sending to Google Firebase Cloud Messaging service" } ] } [/block]