{"_id":"564b534ee5d9d61700d580e8","link_url":"","order":0,"title":"Getting Started","hidden":false,"type":"basic","updates":[],"api":{"settings":"","url":"","auth":"required","params":[],"results":{"codes":[{"code":"{}","name":"","status":200,"language":"json"},{"name":"","status":400,"language":"json","code":"{}"}]}},"category":"564b534de5d9d61700d580e6","excerpt":"","githubsync":"","link_external":false,"slug":"getting-started","__v":1,"createdAt":"2015-11-17T16:18:22.606Z","project":"564b534ce5d9d61700d580e2","sync_unique":"","user":"54ed0ffea45a441700fd4cf0","version":"564b534de5d9d61700d580e5","body":"The Roost Javascript API is used to control the opt-in experience and to modify the subscriptions of subscribers on your site.  Let's take a look at some of the details.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Using roost.js to Register Users\"\n}\n[/block]\nYou must first put Roost onto your site before you can do anything else.  This is covered above, under [Installing Roost](http://docs.goroost.com/docs/basic-roost-installation).  Let's explain a bit how this works.\n\nThe base roost javascript (sidebar) must appear on any page where you want to prompt users to sign up for Roost, or where you want to make Roost API calls. The first part loads Roost (asynchronously), and the second line makes sure that your API calls can happen, even if Roost is not loaded yet. Be sure that this is declared before any use of roost calls on a page.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<!-- BASE ROOST JAVASCRIPT -->\\n\\n<script src=\\\"https://cdn.goroost.com/roostjs/YOUR APP KEY HERE\\\" async></script>\\n<script>\\n    var _roost = _roost || [];\\n</script>\\n\\n<!-- Replace “YOUR APP KEY HERE” with the Roost app key that is available from Settings->Roost Javascript in the Roost dashboard. -->\\n  \",\n      \"language\": \"javascript\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Opt-in Prompt\"\n}\n[/block]\nPages with this javascript present will prompt users to register for your notifications.  The default behavior is to default the first time they come to the web page.  One prompt is shown per site, regardless of how many pages have the javascript present.\n[block:image]\n{\n  \"images\": [\n    {\n      \"caption\": \"\",\n      \"image\": [\n        \"https://files.readme.io/MeQkFP9ATCanbAItnh2F_opt-in.png\",\n        \"opt-in.png\",\n        \"1108\",\n        \"870\",\n        \"#612420\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n**Safari**:  The prompt is modal, and will be shown exactly once.  If the user disallows notifications, then they must go into Safari->Preferences->Notifications and change the settings to enable notifications.  Whatever they choose, the user will never be prompted again, unless they remove the subscription from the notification list entirely.\n\n**Chrome**:  The prompt has three choices:  Allow, Disallow, and Dismiss (x).  If the user selects Allow or Disallow, then the choice is permanent, and no further prompts will be shown for that site.  If the permission dialog is dismissed, then you may show it again, but we advise doing this cautiously.  Roost continuously optimizes the default re-prompting behavior, which may change considerably in the future.","childrenPages":[]}

Getting Started


The Roost Javascript API is used to control the opt-in experience and to modify the subscriptions of subscribers on your site. Let's take a look at some of the details. [block:api-header] { "type": "basic", "title": "Using roost.js to Register Users" } [/block] You must first put Roost onto your site before you can do anything else. This is covered above, under [Installing Roost](http://docs.goroost.com/docs/basic-roost-installation). Let's explain a bit how this works. The base roost javascript (sidebar) must appear on any page where you want to prompt users to sign up for Roost, or where you want to make Roost API calls. The first part loads Roost (asynchronously), and the second line makes sure that your API calls can happen, even if Roost is not loaded yet. Be sure that this is declared before any use of roost calls on a page. [block:code] { "codes": [ { "code": "<!-- BASE ROOST JAVASCRIPT -->\n\n<script src=\"https://cdn.goroost.com/roostjs/YOUR APP KEY HERE\" async></script>\n<script>\n var _roost = _roost || [];\n</script>\n\n<!-- Replace “YOUR APP KEY HERE” with the Roost app key that is available from Settings->Roost Javascript in the Roost dashboard. -->\n ", "language": "javascript" } ], "sidebar": true } [/block] [block:api-header] { "type": "basic", "title": "Opt-in Prompt" } [/block] Pages with this javascript present will prompt users to register for your notifications. The default behavior is to default the first time they come to the web page. One prompt is shown per site, regardless of how many pages have the javascript present. [block:image] { "images": [ { "caption": "", "image": [ "https://files.readme.io/MeQkFP9ATCanbAItnh2F_opt-in.png", "opt-in.png", "1108", "870", "#612420", "" ] } ] } [/block] **Safari**: The prompt is modal, and will be shown exactly once. If the user disallows notifications, then they must go into Safari->Preferences->Notifications and change the settings to enable notifications. Whatever they choose, the user will never be prompted again, unless they remove the subscription from the notification list entirely. **Chrome**: The prompt has three choices: Allow, Disallow, and Dismiss (x). If the user selects Allow or Disallow, then the choice is permanent, and no further prompts will be shown for that site. If the permission dialog is dismissed, then you may show it again, but we advise doing this cautiously. Roost continuously optimizes the default re-prompting behavior, which may change considerably in the future.
The Roost Javascript API is used to control the opt-in experience and to modify the subscriptions of subscribers on your site. Let's take a look at some of the details. [block:api-header] { "type": "basic", "title": "Using roost.js to Register Users" } [/block] You must first put Roost onto your site before you can do anything else. This is covered above, under [Installing Roost](http://docs.goroost.com/docs/basic-roost-installation). Let's explain a bit how this works. The base roost javascript (sidebar) must appear on any page where you want to prompt users to sign up for Roost, or where you want to make Roost API calls. The first part loads Roost (asynchronously), and the second line makes sure that your API calls can happen, even if Roost is not loaded yet. Be sure that this is declared before any use of roost calls on a page. [block:code] { "codes": [ { "code": "<!-- BASE ROOST JAVASCRIPT -->\n\n<script src=\"https://cdn.goroost.com/roostjs/YOUR APP KEY HERE\" async></script>\n<script>\n var _roost = _roost || [];\n</script>\n\n<!-- Replace “YOUR APP KEY HERE” with the Roost app key that is available from Settings->Roost Javascript in the Roost dashboard. -->\n ", "language": "javascript" } ], "sidebar": true } [/block] [block:api-header] { "type": "basic", "title": "Opt-in Prompt" } [/block] Pages with this javascript present will prompt users to register for your notifications. The default behavior is to default the first time they come to the web page. One prompt is shown per site, regardless of how many pages have the javascript present. [block:image] { "images": [ { "caption": "", "image": [ "https://files.readme.io/MeQkFP9ATCanbAItnh2F_opt-in.png", "opt-in.png", "1108", "870", "#612420", "" ] } ] } [/block] **Safari**: The prompt is modal, and will be shown exactly once. If the user disallows notifications, then they must go into Safari->Preferences->Notifications and change the settings to enable notifications. Whatever they choose, the user will never be prompted again, unless they remove the subscription from the notification list entirely. **Chrome**: The prompt has three choices: Allow, Disallow, and Dismiss (x). If the user selects Allow or Disallow, then the choice is permanent, and no further prompts will be shown for that site. If the permission dialog is dismissed, then you may show it again, but we advise doing this cautiously. Roost continuously optimizes the default re-prompting behavior, which may change considerably in the future.
{"_id":"5650ad674f81410d00bf9392","link_url":"","sync_unique":"","category":"564b534de5d9d61700d580e6","excerpt":"","githubsync":"","hidden":false,"isReference":false,"link_external":false,"api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"name":"","status":400,"language":"json","code":"{}"}]},"settings":"","url":"","auth":"required","params":[]},"title":"Roost JavaScript Conventions","type":"basic","updates":[],"__v":1,"order":1,"project":"564b534ce5d9d61700d580e2","user":"54ed0ffea45a441700fd4cf0","body":"Roost on the client side has a specific life cycle on every page containing the Roost javacript.  This is normally every page on your site, and this affects the form and manner in which APIs can be invoked.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Roost Life Cycle\"\n}\n[/block]\n**1) Your page loads**\n\n**2) Roost loads asynchronously**\n\n**3) Roost [Onload()](http://docs-js.goroost.com/docs/initialization-callback-onload) is called**\n\n**4) Roost Automatic Prompt occurs (if set to default and user is not subscribed)**\n\n**5) Roost [OnResult()](http://docs-js.goroost.com/docs/initialization-callback-onresult) is called**\n\nSome Roost calls and properties are always available, others Onload(), and others after OnResults().\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Always Available: _roost.push[] Commands\"\n}\n[/block]\nRoost calls with the form\n\n**_roost.push[<specifier>, <arguments>]** \n\ncan be called at any time -- even before Roost is loaded.  Roost will process these commands when it is loaded.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Available after Onload()\"\n}\n[/block]\nRoost is fully loaded after the Onload() call, and the _roost object can be accessed.\n\nRoost calls of the form\n\n_roost.command()\n\nAre generally available inside the [Onload() ](http://docs-js.goroost.com/docs/initialization-callback-onload)callback, or afterwards.\n\nSee [Onload()](http://docs-js.goroost.com/docs/initialization-callback-onload) for the properties passed in the data object in the Onload Callback.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Available after OnResult()\"\n}\n[/block]\n[OnResult()](http://docs-js.goroost.com/docs/initialization-callback-onresult) is called just after the user opt-in occurs (whether is it a yes or a no), and on every page load thereafter.\n\nSee [OnResult()](http://docs-js.goroost.com/docs/initialization-callback-onresult) for the properties passed in the data object in the OnResult calbback.","createdAt":"2015-11-21T17:44:07.640Z","slug":"roost-javascript-conventions","version":"564b534de5d9d61700d580e5","childrenPages":[]}

Roost JavaScript Conventions


Roost on the client side has a specific life cycle on every page containing the Roost javacript. This is normally every page on your site, and this affects the form and manner in which APIs can be invoked. [block:api-header] { "type": "basic", "title": "Roost Life Cycle" } [/block] **1) Your page loads** **2) Roost loads asynchronously** **3) Roost [Onload()](http://docs-js.goroost.com/docs/initialization-callback-onload) is called** **4) Roost Automatic Prompt occurs (if set to default and user is not subscribed)** **5) Roost [OnResult()](http://docs-js.goroost.com/docs/initialization-callback-onresult) is called** Some Roost calls and properties are always available, others Onload(), and others after OnResults(). [block:api-header] { "type": "basic", "title": "Always Available: _roost.push[] Commands" } [/block] Roost calls with the form **_roost.push[<specifier>, <arguments>]** can be called at any time -- even before Roost is loaded. Roost will process these commands when it is loaded. [block:api-header] { "type": "basic", "title": "Available after Onload()" } [/block] Roost is fully loaded after the Onload() call, and the _roost object can be accessed. Roost calls of the form _roost.command() Are generally available inside the [Onload() ](http://docs-js.goroost.com/docs/initialization-callback-onload)callback, or afterwards. See [Onload()](http://docs-js.goroost.com/docs/initialization-callback-onload) for the properties passed in the data object in the Onload Callback. [block:api-header] { "type": "basic", "title": "Available after OnResult()" } [/block] [OnResult()](http://docs-js.goroost.com/docs/initialization-callback-onresult) is called just after the user opt-in occurs (whether is it a yes or a no), and on every page load thereafter. See [OnResult()](http://docs-js.goroost.com/docs/initialization-callback-onresult) for the properties passed in the data object in the OnResult calbback.
Roost on the client side has a specific life cycle on every page containing the Roost javacript. This is normally every page on your site, and this affects the form and manner in which APIs can be invoked. [block:api-header] { "type": "basic", "title": "Roost Life Cycle" } [/block] **1) Your page loads** **2) Roost loads asynchronously** **3) Roost [Onload()](http://docs-js.goroost.com/docs/initialization-callback-onload) is called** **4) Roost Automatic Prompt occurs (if set to default and user is not subscribed)** **5) Roost [OnResult()](http://docs-js.goroost.com/docs/initialization-callback-onresult) is called** Some Roost calls and properties are always available, others Onload(), and others after OnResults(). [block:api-header] { "type": "basic", "title": "Always Available: _roost.push[] Commands" } [/block] Roost calls with the form **_roost.push[<specifier>, <arguments>]** can be called at any time -- even before Roost is loaded. Roost will process these commands when it is loaded. [block:api-header] { "type": "basic", "title": "Available after Onload()" } [/block] Roost is fully loaded after the Onload() call, and the _roost object can be accessed. Roost calls of the form _roost.command() Are generally available inside the [Onload() ](http://docs-js.goroost.com/docs/initialization-callback-onload)callback, or afterwards. See [Onload()](http://docs-js.goroost.com/docs/initialization-callback-onload) for the properties passed in the data object in the Onload Callback. [block:api-header] { "type": "basic", "title": "Available after OnResult()" } [/block] [OnResult()](http://docs-js.goroost.com/docs/initialization-callback-onresult) is called just after the user opt-in occurs (whether is it a yes or a no), and on every page load thereafter. See [OnResult()](http://docs-js.goroost.com/docs/initialization-callback-onresult) for the properties passed in the data object in the OnResult calbback.
{"_id":"5650a7644f81410d00bf938f","user":"54ed0ffea45a441700fd4cf0","__v":0,"api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"excerpt":"","updates":[],"order":3,"sync_unique":"","category":"564b534de5d9d61700d580e6","createdAt":"2015-11-21T17:18:28.895Z","githubsync":"","body":"It is possible to use Roost to determine if a browser is able to receive notifications or not using the **onload** callback function . This is fired on page load from Roost.js and returns a boolean based on browser capability.\n[block:html]\n{\n  \"html\": \"<div style=\\\"font-size: 14pt; font-weight: bold;\\\">\\n_roost.push(['onload', function(data) {}]);\\n</div>\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"callback function\",\n    \"0-1\": \"function which takes one parameter, the Roost data object\"\n  },\n  \"cols\": 2,\n  \"rows\": 1\n}\n[/block]\n**The Data Object**\n\nThe **data** object passed to your callback contains one property, _promptable_.\n \n  * promptable:  This will be set to true if the browser is able to receive notifications.\n\n**Example: promptable = true**\nIt is common to show / hide UI elements based on if the client's browser may receive notifications. Hiding a menu item or displaying a modal to prompt for permissions is a good example.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<!-- EXAMPLE: HIDE A MENU ITEM -->\\n\\n<script>\\n    var _roost = _roost || [];\\n    _roost.push(['onload', function(data) {\\n        if (data.promptable) {\\n            //your code goes here\\n        }\\n    }]);\\n</script>\",\n      \"language\": \"text\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]","link_external":false,"title":"Initialization Callback - Onload","type":"basic","version":"564b534de5d9d61700d580e5","hidden":false,"link_url":"","project":"564b534ce5d9d61700d580e2","slug":"initialization-callback-onload","childrenPages":[]}

Initialization Callback - Onload


It is possible to use Roost to determine if a browser is able to receive notifications or not using the **onload** callback function . This is fired on page load from Roost.js and returns a boolean based on browser capability. [block:html] { "html": "<div style=\"font-size: 14pt; font-weight: bold;\">\n_roost.push(['onload', function(data) {}]);\n</div>" } [/block] [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Description", "0-0": "callback function", "0-1": "function which takes one parameter, the Roost data object" }, "cols": 2, "rows": 1 } [/block] **The Data Object** The **data** object passed to your callback contains one property, _promptable_. * promptable: This will be set to true if the browser is able to receive notifications. **Example: promptable = true** It is common to show / hide UI elements based on if the client's browser may receive notifications. Hiding a menu item or displaying a modal to prompt for permissions is a good example. [block:code] { "codes": [ { "code": "<!-- EXAMPLE: HIDE A MENU ITEM -->\n\n<script>\n var _roost = _roost || [];\n _roost.push(['onload', function(data) {\n if (data.promptable) {\n //your code goes here\n }\n }]);\n</script>", "language": "text" } ], "sidebar": true } [/block]
It is possible to use Roost to determine if a browser is able to receive notifications or not using the **onload** callback function . This is fired on page load from Roost.js and returns a boolean based on browser capability. [block:html] { "html": "<div style=\"font-size: 14pt; font-weight: bold;\">\n_roost.push(['onload', function(data) {}]);\n</div>" } [/block] [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Description", "0-0": "callback function", "0-1": "function which takes one parameter, the Roost data object" }, "cols": 2, "rows": 1 } [/block] **The Data Object** The **data** object passed to your callback contains one property, _promptable_. * promptable: This will be set to true if the browser is able to receive notifications. **Example: promptable = true** It is common to show / hide UI elements based on if the client's browser may receive notifications. Hiding a menu item or displaying a modal to prompt for permissions is a good example. [block:code] { "codes": [ { "code": "<!-- EXAMPLE: HIDE A MENU ITEM -->\n\n<script>\n var _roost = _roost || [];\n _roost.push(['onload', function(data) {\n if (data.promptable) {\n //your code goes here\n }\n }]);\n</script>", "language": "text" } ], "sidebar": true } [/block]
{"_id":"5650a79f25691837008a7fa2","__v":2,"body":"It is possible to use Roost to determine if a browser is able to receive notifications or not using the **onresult** callback function . This is fired when a Roost subscription is complete (allowed or denied), and on every page load thereafter.  It is always called after [Onload()](http://docs-js.goroost.com/docs/initialization-callback-onload).\n[block:html]\n{\n  \"html\": \"<div style=\\\"font-size: 14pt; font-weight: bold;\\\">\\n_roost.push(['onresult', function(data) {}]);\\n</div>\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"callback function\",\n    \"0-1\": \"function which takes one parameter, the Roost data object\"\n  },\n  \"cols\": 2,\n  \"rows\": 1\n}\n[/block]\n**The Data Object**\n\nThe **data** object passed to your callback contains several properties:\n\n* **alias**:  Unique ID assigned for each user.  This is only available if you have assigned an alias via the[ 'alias' call](http://docs-js.goroost.com/docs/segmenting-individuals-alias).\n* **denied**: True if the user has specifically said No to the system opt-in dialog on the browser.\n* **deviceToken**: Unique token assigned for this registration on this device.\n* **enabled**: True if the user has subscribed for notifications, and they are currently enabled.  False otherwise.\n* **firstTime**: True if this is the first call of onResult since registration occurred.\n* **registered**: True if the user has successfully subscribed for notifications\n \nIt is common to show / hide UI elements based on the users registration state.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<!-- EXAMPLE: DO SOME ACTION THE FIRST TIME AFTER A USER REGISTERS -->\\n\\n<script>\\n    var _roost = _roost || [];\\n    _roost.push(['onresult', function(data) {\\n        if (data.firstTime && data.registered) {\\n            //your code goes here\\n        }\\n    }]);\\n</script>\",\n      \"language\": \"text\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]","category":"564b534de5d9d61700d580e6","hidden":false,"link_url":"","order":4,"user":"54ed0ffea45a441700fd4cf0","excerpt":"","project":"564b534ce5d9d61700d580e2","title":"Initialization Callback - OnResult","type":"basic","updates":[],"sync_unique":"","api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":"","auth":"required","params":[]},"createdAt":"2015-11-21T17:19:27.402Z","githubsync":"","link_external":false,"slug":"initialization-callback-onresult","version":"564b534de5d9d61700d580e5","childrenPages":[]}

Initialization Callback - OnResult


It is possible to use Roost to determine if a browser is able to receive notifications or not using the **onresult** callback function . This is fired when a Roost subscription is complete (allowed or denied), and on every page load thereafter. It is always called after [Onload()](http://docs-js.goroost.com/docs/initialization-callback-onload). [block:html] { "html": "<div style=\"font-size: 14pt; font-weight: bold;\">\n_roost.push(['onresult', function(data) {}]);\n</div>" } [/block] [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Description", "0-0": "callback function", "0-1": "function which takes one parameter, the Roost data object" }, "cols": 2, "rows": 1 } [/block] **The Data Object** The **data** object passed to your callback contains several properties: * **alias**: Unique ID assigned for each user. This is only available if you have assigned an alias via the[ 'alias' call](http://docs-js.goroost.com/docs/segmenting-individuals-alias). * **denied**: True if the user has specifically said No to the system opt-in dialog on the browser. * **deviceToken**: Unique token assigned for this registration on this device. * **enabled**: True if the user has subscribed for notifications, and they are currently enabled. False otherwise. * **firstTime**: True if this is the first call of onResult since registration occurred. * **registered**: True if the user has successfully subscribed for notifications It is common to show / hide UI elements based on the users registration state. [block:code] { "codes": [ { "code": "<!-- EXAMPLE: DO SOME ACTION THE FIRST TIME AFTER A USER REGISTERS -->\n\n<script>\n var _roost = _roost || [];\n _roost.push(['onresult', function(data) {\n if (data.firstTime && data.registered) {\n //your code goes here\n }\n }]);\n</script>", "language": "text" } ], "sidebar": true } [/block]
It is possible to use Roost to determine if a browser is able to receive notifications or not using the **onresult** callback function . This is fired when a Roost subscription is complete (allowed or denied), and on every page load thereafter. It is always called after [Onload()](http://docs-js.goroost.com/docs/initialization-callback-onload). [block:html] { "html": "<div style=\"font-size: 14pt; font-weight: bold;\">\n_roost.push(['onresult', function(data) {}]);\n</div>" } [/block] [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Description", "0-0": "callback function", "0-1": "function which takes one parameter, the Roost data object" }, "cols": 2, "rows": 1 } [/block] **The Data Object** The **data** object passed to your callback contains several properties: * **alias**: Unique ID assigned for each user. This is only available if you have assigned an alias via the[ 'alias' call](http://docs-js.goroost.com/docs/segmenting-individuals-alias). * **denied**: True if the user has specifically said No to the system opt-in dialog on the browser. * **deviceToken**: Unique token assigned for this registration on this device. * **enabled**: True if the user has subscribed for notifications, and they are currently enabled. False otherwise. * **firstTime**: True if this is the first call of onResult since registration occurred. * **registered**: True if the user has successfully subscribed for notifications It is common to show / hide UI elements based on the users registration state. [block:code] { "codes": [ { "code": "<!-- EXAMPLE: DO SOME ACTION THE FIRST TIME AFTER A USER REGISTERS -->\n\n<script>\n var _roost = _roost || [];\n _roost.push(['onresult', function(data) {\n if (data.firstTime && data.registered) {\n //your code goes here\n }\n }]);\n</script>", "language": "text" } ], "sidebar": true } [/block]
{"_id":"56784243092f210d00e304a2","body":"Roost on the client side has a specific life cycle on every page containing the Roost javacript.  This is normally every page on your site, and this affects the form and manner in which APIs can be invoked.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Roost Life Cycle\"\n}\n[/block]\n**1) Your page loads**\n\n**2) Roost loads asynchronously**\n\n**3) Roost [Onload()](http://docs.goroost.com/docs/initialization-callback-onload) is called**\n\n**4) Roost Automatic Prompt occurs (if set to default and user is not subscribed)**\n\n**5) Roost [OnResult()](http://docs.goroost.com/docs/initialization-callback-onresult) is called**\n\nSome Roost calls and properties are always available, others Onload(), and others after OnResults().\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Always Available: _roost.push[] Commands\"\n}\n[/block]\nRoost calls with the form\n\n**_roost.push[<specifier>, <arguments>]** \n\ncan be called at any time -- even before Roost is loaded.  Roost will process these commands when it is loaded.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Available after Onload()\"\n}\n[/block]\nRoost is fully loaded after the Onload() call, and the _roost object can be accessed.\n\nRoost calls of the form\n\n**_roost.command()**\n\nare generally available inside the [Onload() ](http://docs.goroost.com/docs/initialization-callback-onload)callback, or afterwards.\n\nIf you are calling _roost functions outside of the Onload() callback, you should call them in with the following syntax to avoid race conditions.  In cases where Onload has not yet been called, functions specified as below will wait to execute until the Onload callback is invoked.  Otherwise, they will execute immediately.\n\n**_roost.push([\"onload\", function() { _roost.FUNCTION();}]);**\n\nSee [Onload()](http://docs.goroost.com/docs/initialization-callback-onload) for the properties passed in the data object in the Onload Callback.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Available after OnResult()\"\n}\n[/block]\n[OnResult()](http://docs.goroost.com/docs/initialization-callback-onresult) is called just after the user opt-in occurs (whether is it a yes or a no), and on every page load thereafter.\n\nSee [OnResult()](http://docs.goroost.com/docs/initialization-callback-onresult) for the properties passed in the data object in the OnResult calbback.","createdAt":"2015-12-21T18:17:39.820Z","githubsync":"","hidden":false,"link_external":false,"slug":"roost-javascript-conventions-1","sync_unique":"","type":"basic","updates":[],"api":{"settings":"","results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"auth":"required","params":[],"url":""},"excerpt":"","project":"564b534ce5d9d61700d580e2","title":"Roost JavaScript Conventions","user":"54ed0ffea45a441700fd4cf0","__v":0,"category":"564b534de5d9d61700d580e6","link_url":"","order":5,"version":"564b534de5d9d61700d580e5","childrenPages":[]}

Roost JavaScript Conventions


Roost on the client side has a specific life cycle on every page containing the Roost javacript. This is normally every page on your site, and this affects the form and manner in which APIs can be invoked. [block:api-header] { "type": "basic", "title": "Roost Life Cycle" } [/block] **1) Your page loads** **2) Roost loads asynchronously** **3) Roost [Onload()](http://docs.goroost.com/docs/initialization-callback-onload) is called** **4) Roost Automatic Prompt occurs (if set to default and user is not subscribed)** **5) Roost [OnResult()](http://docs.goroost.com/docs/initialization-callback-onresult) is called** Some Roost calls and properties are always available, others Onload(), and others after OnResults(). [block:api-header] { "type": "basic", "title": "Always Available: _roost.push[] Commands" } [/block] Roost calls with the form **_roost.push[<specifier>, <arguments>]** can be called at any time -- even before Roost is loaded. Roost will process these commands when it is loaded. [block:api-header] { "type": "basic", "title": "Available after Onload()" } [/block] Roost is fully loaded after the Onload() call, and the _roost object can be accessed. Roost calls of the form **_roost.command()** are generally available inside the [Onload() ](http://docs.goroost.com/docs/initialization-callback-onload)callback, or afterwards. If you are calling _roost functions outside of the Onload() callback, you should call them in with the following syntax to avoid race conditions. In cases where Onload has not yet been called, functions specified as below will wait to execute until the Onload callback is invoked. Otherwise, they will execute immediately. **_roost.push(["onload", function() { _roost.FUNCTION();}]);** See [Onload()](http://docs.goroost.com/docs/initialization-callback-onload) for the properties passed in the data object in the Onload Callback. [block:api-header] { "type": "basic", "title": "Available after OnResult()" } [/block] [OnResult()](http://docs.goroost.com/docs/initialization-callback-onresult) is called just after the user opt-in occurs (whether is it a yes or a no), and on every page load thereafter. See [OnResult()](http://docs.goroost.com/docs/initialization-callback-onresult) for the properties passed in the data object in the OnResult calbback.
Roost on the client side has a specific life cycle on every page containing the Roost javacript. This is normally every page on your site, and this affects the form and manner in which APIs can be invoked. [block:api-header] { "type": "basic", "title": "Roost Life Cycle" } [/block] **1) Your page loads** **2) Roost loads asynchronously** **3) Roost [Onload()](http://docs.goroost.com/docs/initialization-callback-onload) is called** **4) Roost Automatic Prompt occurs (if set to default and user is not subscribed)** **5) Roost [OnResult()](http://docs.goroost.com/docs/initialization-callback-onresult) is called** Some Roost calls and properties are always available, others Onload(), and others after OnResults(). [block:api-header] { "type": "basic", "title": "Always Available: _roost.push[] Commands" } [/block] Roost calls with the form **_roost.push[<specifier>, <arguments>]** can be called at any time -- even before Roost is loaded. Roost will process these commands when it is loaded. [block:api-header] { "type": "basic", "title": "Available after Onload()" } [/block] Roost is fully loaded after the Onload() call, and the _roost object can be accessed. Roost calls of the form **_roost.command()** are generally available inside the [Onload() ](http://docs.goroost.com/docs/initialization-callback-onload)callback, or afterwards. If you are calling _roost functions outside of the Onload() callback, you should call them in with the following syntax to avoid race conditions. In cases where Onload has not yet been called, functions specified as below will wait to execute until the Onload callback is invoked. Otherwise, they will execute immediately. **_roost.push(["onload", function() { _roost.FUNCTION();}]);** See [Onload()](http://docs.goroost.com/docs/initialization-callback-onload) for the properties passed in the data object in the Onload Callback. [block:api-header] { "type": "basic", "title": "Available after OnResult()" } [/block] [OnResult()](http://docs.goroost.com/docs/initialization-callback-onresult) is called just after the user opt-in occurs (whether is it a yes or a no), and on every page load thereafter. See [OnResult()](http://docs.goroost.com/docs/initialization-callback-onresult) for the properties passed in the data object in the OnResult calbback.
{"_id":"5650a930a462732b002b3641","__v":0,"excerpt":"","sync_unique":"","title":"Autoprompt","version":"564b534de5d9d61700d580e5","type":"basic","user":"54ed0ffea45a441700fd4cf0","api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"body":"**Auto-prompt** allows you to enable/disable the automatic opt-in prompt for subscribing a site visitor.\n\nThe default opt-in prompt is displayed the first time a user visits a Roost-enabled page.  This behavior can be enabled/disabled by calling the **auto-prompt** command.   This call is typically placed just after the base Roost javascript (as shown in the example).\n[block:html]\n{\n  \"html\": \"<div style=\\\"font-size: 14pt; font-weight: bold;\\\">\\n  _roost.push([\\\"autoprompt\\\", &lt;boolean&gt;])\\n</div>\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"autoprompt\",\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Description\",\n    \"0-1\": \"Command to modify auto-prompt behavior\",\n    \"1-0\": \"(boolean)\",\n    \"1-1\": \"Boolean value enabling/disabling auto-prompt\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<!-- DISABLING AUTO-PROMPT -->\\n  \\n<script src=\\\"https://cdn.goroost.com/roostjs/YOUR APP KEY HERE\\\" async>\\n</script>\\n<script>\\n    var _roost = _roost || [];\\n    _roost.push(['autoprompt', false]);\\n</script>\",\n      \"language\": \"javascript\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]\n**Notes**\n  * Other means (described in following sections) will be needed to subscribe users if auto-prompt is disabled. \n  * Most sites use Auto-prompt successfully, and using it will certainly capture more organic visitors.  An alternative to using Auto-prompt on all your pages it to prompt subscribers on particular pages.  Another alternative is to prompt visitors after they have been to several pages on your site - see [Prompt after X Visits](doc:prompt-on--page-loads).","link_url":"","slug":"autoprompt","category":"5650a6b2a462732b002b3640","githubsync":"","updates":[],"createdAt":"2015-11-21T17:26:08.951Z","hidden":false,"link_external":false,"order":0,"project":"564b534ce5d9d61700d580e2","childrenPages":[]}

Autoprompt


**Auto-prompt** allows you to enable/disable the automatic opt-in prompt for subscribing a site visitor. The default opt-in prompt is displayed the first time a user visits a Roost-enabled page. This behavior can be enabled/disabled by calling the **auto-prompt** command. This call is typically placed just after the base Roost javascript (as shown in the example). [block:html] { "html": "<div style=\"font-size: 14pt; font-weight: bold;\">\n _roost.push([\"autoprompt\", &lt;boolean&gt;])\n</div>" } [/block] [block:parameters] { "data": { "0-0": "autoprompt", "h-0": "Parameter", "h-1": "Description", "0-1": "Command to modify auto-prompt behavior", "1-0": "(boolean)", "1-1": "Boolean value enabling/disabling auto-prompt" }, "cols": 2, "rows": 2 } [/block] [block:code] { "codes": [ { "code": "<!-- DISABLING AUTO-PROMPT -->\n \n<script src=\"https://cdn.goroost.com/roostjs/YOUR APP KEY HERE\" async>\n</script>\n<script>\n var _roost = _roost || [];\n _roost.push(['autoprompt', false]);\n</script>", "language": "javascript" } ], "sidebar": true } [/block] **Notes** * Other means (described in following sections) will be needed to subscribe users if auto-prompt is disabled. * Most sites use Auto-prompt successfully, and using it will certainly capture more organic visitors. An alternative to using Auto-prompt on all your pages it to prompt subscribers on particular pages. Another alternative is to prompt visitors after they have been to several pages on your site - see [Prompt after X Visits](doc:prompt-on--page-loads).
**Auto-prompt** allows you to enable/disable the automatic opt-in prompt for subscribing a site visitor. The default opt-in prompt is displayed the first time a user visits a Roost-enabled page. This behavior can be enabled/disabled by calling the **auto-prompt** command. This call is typically placed just after the base Roost javascript (as shown in the example). [block:html] { "html": "<div style=\"font-size: 14pt; font-weight: bold;\">\n _roost.push([\"autoprompt\", &lt;boolean&gt;])\n</div>" } [/block] [block:parameters] { "data": { "0-0": "autoprompt", "h-0": "Parameter", "h-1": "Description", "0-1": "Command to modify auto-prompt behavior", "1-0": "(boolean)", "1-1": "Boolean value enabling/disabling auto-prompt" }, "cols": 2, "rows": 2 } [/block] [block:code] { "codes": [ { "code": "<!-- DISABLING AUTO-PROMPT -->\n \n<script src=\"https://cdn.goroost.com/roostjs/YOUR APP KEY HERE\" async>\n</script>\n<script>\n var _roost = _roost || [];\n _roost.push(['autoprompt', false]);\n</script>", "language": "javascript" } ], "sidebar": true } [/block] **Notes** * Other means (described in following sections) will be needed to subscribe users if auto-prompt is disabled. * Most sites use Auto-prompt successfully, and using it will certainly capture more organic visitors. An alternative to using Auto-prompt on all your pages it to prompt subscribers on particular pages. Another alternative is to prompt visitors after they have been to several pages on your site - see [Prompt after X Visits](doc:prompt-on--page-loads).
{"_id":"5650a9560bf9ee3500cd05c1","sync_unique":"","updates":[],"githubsync":"","link_external":false,"hidden":false,"slug":"prompt-after-x-visits","title":"Prompt After X Visits","type":"basic","api":{"auth":"required","params":[],"url":"","results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":""},"body":"Min Visits allows you to delay the automatic opt-in prompt until a visitor has been on several been on several pages of your site.\n[block:html]\n{\n  \"html\": \"<div style=\\\"font-size: 14pt; font-weight: bold;\\\">\\n  _roost.push([\\\"minvisits\\\", &lt;number&gt;])\\n</div>\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"minvisits\",\n    \"0-1\": \"Command to delay auto-prompt\",\n    \"1-0\": \"(# of min visits)\",\n    \"1-1\": \"The number is the number of visits or page loads required to show the subscription opt-in prompt.\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<!-- PROMPT ON 3rd VISIT TO THIS SITE -->\\n\\n<script>\\n    var _roost = _roost || [];\\n    _roost.push(['autoprompt', false]);\\n    _roost.push([ 'minvisits', 3 ]);\\n</script>\",\n      \"language\": \"text\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]\n\nThis approach is useful if your site is largely drive-by traffic, which means you may want to prompt your site's visitors a bit more cautiously.  A good way to do this is to prompt on the Xth page load.  This tracks the number of page loads across all Roost-enabled pages on the entire site.","createdAt":"2015-11-21T17:26:46.898Z","excerpt":"","user":"54ed0ffea45a441700fd4cf0","version":"564b534de5d9d61700d580e5","project":"564b534ce5d9d61700d580e2","__v":0,"category":"5650a6b2a462732b002b3640","link_url":"","order":1,"childrenPages":[]}

Prompt After X Visits


Min Visits allows you to delay the automatic opt-in prompt until a visitor has been on several been on several pages of your site. [block:html] { "html": "<div style=\"font-size: 14pt; font-weight: bold;\">\n _roost.push([\"minvisits\", &lt;number&gt;])\n</div>" } [/block] [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Description", "0-0": "minvisits", "0-1": "Command to delay auto-prompt", "1-0": "(# of min visits)", "1-1": "The number is the number of visits or page loads required to show the subscription opt-in prompt." }, "cols": 2, "rows": 2 } [/block] [block:code] { "codes": [ { "code": "<!-- PROMPT ON 3rd VISIT TO THIS SITE -->\n\n<script>\n var _roost = _roost || [];\n _roost.push(['autoprompt', false]);\n _roost.push([ 'minvisits', 3 ]);\n</script>", "language": "text" } ], "sidebar": true } [/block] This approach is useful if your site is largely drive-by traffic, which means you may want to prompt your site's visitors a bit more cautiously. A good way to do this is to prompt on the Xth page load. This tracks the number of page loads across all Roost-enabled pages on the entire site.
Min Visits allows you to delay the automatic opt-in prompt until a visitor has been on several been on several pages of your site. [block:html] { "html": "<div style=\"font-size: 14pt; font-weight: bold;\">\n _roost.push([\"minvisits\", &lt;number&gt;])\n</div>" } [/block] [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Description", "0-0": "minvisits", "0-1": "Command to delay auto-prompt", "1-0": "(# of min visits)", "1-1": "The number is the number of visits or page loads required to show the subscription opt-in prompt." }, "cols": 2, "rows": 2 } [/block] [block:code] { "codes": [ { "code": "<!-- PROMPT ON 3rd VISIT TO THIS SITE -->\n\n<script>\n var _roost = _roost || [];\n _roost.push(['autoprompt', false]);\n _roost.push([ 'minvisits', 3 ]);\n</script>", "language": "text" } ], "sidebar": true } [/block] This approach is useful if your site is largely drive-by traffic, which means you may want to prompt your site's visitors a bit more cautiously. A good way to do this is to prompt on the Xth page load. This tracks the number of page loads across all Roost-enabled pages on the entire site.
{"_id":"5650a99325691837008a7fa4","slug":"register-on-action","updates":["58877831d5e7f50f002c93f5","5887784080cbe70f009b16ab","58877857ee111631005dbb79"],"user":"54ed0ffea45a441700fd4cf0","version":"564b534de5d9d61700d580e5","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"name":"","status":400,"language":"json","code":"{}"}]},"settings":"","url":""},"body":"**Register **can be used to explicitly invoke the native registration opt-in prompt for the current subscriber.  This is typically called from a user experience element that is calling the user to action, such as a dialog or checkbox informing the user that they will be opting-in for notifications.\n\nUse **register** when you want to display the Roost opt-in prompt in reaction to a click or other action.  For example, you may have a button or menu item embedded in a section describing push notifications.\n[block:html]\n{\n  \"html\": \"<div style=\\\"font-size: 14pt; font-weight: bold;\\\">\\n  _roost.register()\\n  \\n  // if called outside of Onload() callback:\\n  _roost.push([\\\"onload\\\", function() { _roost.register(); }]);\\n</div>\"\n}\n[/block]\n**Additional Considerations**\n\n  * **register()** will NOT invoke the Opt-in experience if the user has subscribed or blocked the subscription.  This differs from **prompt()**, which will honor the 7 day waiting delay after a user dismisses the opt-in dialog.\n \n  * Calling **register()** requires that the base Roost javascript must be somewhere on the page.\n  * [Auto-Prompt](doc:auto-prompt) should be disabled for prompt to function correctly.\n \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<!-- EXAMPLE: REGISTER ON CLICK -->\\n\\n<!-- First you have to disable the auto-prompt - somewhere after the base roost javascript -->\\n<script>\\n    var _roost = _roost || [];\\n    _roost.push(['autoprompt', false]);\\n</script>\\n.\\n.\\n.\\n<!-- Then your trigger -->\\n<button onclick=\\\"_roost.regiser();\\\">Subscribe for Notifications</button>\",\n      \"language\": \"text\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Register() vs Prompt()\"\n}\n[/block]\nFor HTTP sites, this differs from **prompt()**, in that only the secure page is shown.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/t8wAzsuQoGSkulr63UEM_opt-in.png\",\n        \"opt-in.png\",\n        \"700\",\n        \"300\",\n        \"#fc4c40\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nRegister is identical to prompt() for HTTPS sites.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/0CO3XMXSAS3zm0i2mE6A_ssl-opt-in.png\",\n        \"ssl-opt-in.png\",\n        \"700\",\n        \"300\",\n        \"#63492f\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]","category":"5650a6b2a462732b002b3640","link_external":false,"order":2,"createdAt":"2015-11-21T17:27:47.864Z","githubsync":"","hidden":false,"sync_unique":"","title":"Register on Action","isReference":false,"link_url":"","type":"basic","__v":5,"excerpt":"","project":"564b534ce5d9d61700d580e2","childrenPages":[]}

Register on Action


**Register **can be used to explicitly invoke the native registration opt-in prompt for the current subscriber. This is typically called from a user experience element that is calling the user to action, such as a dialog or checkbox informing the user that they will be opting-in for notifications. Use **register** when you want to display the Roost opt-in prompt in reaction to a click or other action. For example, you may have a button or menu item embedded in a section describing push notifications. [block:html] { "html": "<div style=\"font-size: 14pt; font-weight: bold;\">\n _roost.register()\n \n // if called outside of Onload() callback:\n _roost.push([\"onload\", function() { _roost.register(); }]);\n</div>" } [/block] **Additional Considerations** * **register()** will NOT invoke the Opt-in experience if the user has subscribed or blocked the subscription. This differs from **prompt()**, which will honor the 7 day waiting delay after a user dismisses the opt-in dialog. * Calling **register()** requires that the base Roost javascript must be somewhere on the page. * [Auto-Prompt](doc:auto-prompt) should be disabled for prompt to function correctly. [block:code] { "codes": [ { "code": "<!-- EXAMPLE: REGISTER ON CLICK -->\n\n<!-- First you have to disable the auto-prompt - somewhere after the base roost javascript -->\n<script>\n var _roost = _roost || [];\n _roost.push(['autoprompt', false]);\n</script>\n.\n.\n.\n<!-- Then your trigger -->\n<button onclick=\"_roost.regiser();\">Subscribe for Notifications</button>", "language": "text" } ], "sidebar": true } [/block] [block:api-header] { "type": "basic", "title": "Register() vs Prompt()" } [/block] For HTTP sites, this differs from **prompt()**, in that only the secure page is shown. [block:image] { "images": [ { "image": [ "https://files.readme.io/t8wAzsuQoGSkulr63UEM_opt-in.png", "opt-in.png", "700", "300", "#fc4c40", "" ] } ] } [/block] Register is identical to prompt() for HTTPS sites. [block:image] { "images": [ { "image": [ "https://files.readme.io/0CO3XMXSAS3zm0i2mE6A_ssl-opt-in.png", "ssl-opt-in.png", "700", "300", "#63492f", "" ] } ] } [/block]
**Register **can be used to explicitly invoke the native registration opt-in prompt for the current subscriber. This is typically called from a user experience element that is calling the user to action, such as a dialog or checkbox informing the user that they will be opting-in for notifications. Use **register** when you want to display the Roost opt-in prompt in reaction to a click or other action. For example, you may have a button or menu item embedded in a section describing push notifications. [block:html] { "html": "<div style=\"font-size: 14pt; font-weight: bold;\">\n _roost.register()\n \n // if called outside of Onload() callback:\n _roost.push([\"onload\", function() { _roost.register(); }]);\n</div>" } [/block] **Additional Considerations** * **register()** will NOT invoke the Opt-in experience if the user has subscribed or blocked the subscription. This differs from **prompt()**, which will honor the 7 day waiting delay after a user dismisses the opt-in dialog. * Calling **register()** requires that the base Roost javascript must be somewhere on the page. * [Auto-Prompt](doc:auto-prompt) should be disabled for prompt to function correctly. [block:code] { "codes": [ { "code": "<!-- EXAMPLE: REGISTER ON CLICK -->\n\n<!-- First you have to disable the auto-prompt - somewhere after the base roost javascript -->\n<script>\n var _roost = _roost || [];\n _roost.push(['autoprompt', false]);\n</script>\n.\n.\n.\n<!-- Then your trigger -->\n<button onclick=\"_roost.regiser();\">Subscribe for Notifications</button>", "language": "text" } ], "sidebar": true } [/block] [block:api-header] { "type": "basic", "title": "Register() vs Prompt()" } [/block] For HTTP sites, this differs from **prompt()**, in that only the secure page is shown. [block:image] { "images": [ { "image": [ "https://files.readme.io/t8wAzsuQoGSkulr63UEM_opt-in.png", "opt-in.png", "700", "300", "#fc4c40", "" ] } ] } [/block] Register is identical to prompt() for HTTPS sites. [block:image] { "images": [ { "image": [ "https://files.readme.io/0CO3XMXSAS3zm0i2mE6A_ssl-opt-in.png", "ssl-opt-in.png", "700", "300", "#63492f", "" ] } ] } [/block]
{"_id":"5650a9c0bde46b17002bc532","excerpt":"","title":"Prompt on Action","updates":[],"version":"564b534de5d9d61700d580e5","api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"name":"","status":400,"language":"json","code":"{}"}]},"settings":"","url":"","auth":"required","params":[]},"sync_unique":"","category":"5650a6b2a462732b002b3640","order":3,"hidden":false,"link_external":false,"project":"564b534ce5d9d61700d580e2","slug":"prompt-on-action","type":"basic","user":"54ed0ffea45a441700fd4cf0","__v":1,"githubsync":"","link_url":"","body":"**Prompt **can be used to explicitly invoke the opt-in prompt for the current subscriber.\n\nUse **prompt** when you want to delay the Roost opt-in prompt so that it executes in a javascript function, or in reaction to some event.  **prompt()** is best used when the trigger for the event is behind-the-scenes.\n\nHowever, if you have a user experience element that invokes the opt-in experience, such as a button, menu item, or dialog -- then it is better to use [register()](doc:register-on-action).\n[block:html]\n{\n  \"html\": \"<div style=\\\"font-size: 14pt; font-weight: bold;\\\">\\n  _roost.prompt()\\n  \\n  // if called outside of Onload() callback:\\n  _roost.push([\\\"onload\\\", function() { _roost.prompt(); }]);\\n</div>\"\n}\n[/block]\n**Additional Considerations**\n\n- **Prompt()** will invoke the Opt-in experience if:\n  * The user has not yet subscribed or blocked the subscription\n  * The user has not dismissed the Opt-In dialog in the last 7 days\n  *  Otherwise **prompt()** will NOT invoke the Opt-in experience.\n\n\n  - Calling **prompt()** requires that the base Roost javascript must be somewhere on the page.\n  - [Auto-Prompt](doc:auto-prompt) must be disabled for prompt to function correctly.\n \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<!-- EXAMPLE: PROMPT AFTER SOME CONDITION OCCURS -->\\n\\n<!-- First you have to disable the auto-prompt - somewhere after the base roost javascript -->\\n<script>\\n    var _roost = _roost || [];\\n    _roost.push(['autoprompt', false]);\\n</script>\\n.\\n.\\n.\\n<!-- Then your trigger -->\\nfunction oneOfYourFunctions() {\\n    .\\n    .\\n    .\\n    _roost.prompt();\\n}\",\n      \"language\": \"text\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"HTTP vs HTTPS\"\n}\n[/block]\nThe behavior of prompt() varies slightly for sites served via HTTP vs HTTPS.\n\n**HTTP**:  **prompt()** will invoke the Opt-in Flyout, which then invokes the native opt-in experience on a roost-hosted secure page, as seen below.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/gioNgNPdSkm6q4UDnnCi_flyout.png\",\n        \"flyout.png\",\n        \"700\",\n        \"300\",\n        \"#644c33\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nAnd the second step on the secure page.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/t8wAzsuQoGSkulr63UEM_opt-in.png\",\n        \"opt-in.png\",\n        \"700\",\n        \"300\",\n        \"#fc4c40\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n**HTTPS**:  **prompt()** will invoke the native opt-in experience on the current page, as seen below:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/0CO3XMXSAS3zm0i2mE6A_ssl-opt-in.png\",\n        \"ssl-opt-in.png\",\n        \"700\",\n        \"300\",\n        \"#63492f\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]","createdAt":"2015-11-21T17:28:32.795Z","childrenPages":[]}

Prompt on Action


**Prompt **can be used to explicitly invoke the opt-in prompt for the current subscriber. Use **prompt** when you want to delay the Roost opt-in prompt so that it executes in a javascript function, or in reaction to some event. **prompt()** is best used when the trigger for the event is behind-the-scenes. However, if you have a user experience element that invokes the opt-in experience, such as a button, menu item, or dialog -- then it is better to use [register()](doc:register-on-action). [block:html] { "html": "<div style=\"font-size: 14pt; font-weight: bold;\">\n _roost.prompt()\n \n // if called outside of Onload() callback:\n _roost.push([\"onload\", function() { _roost.prompt(); }]);\n</div>" } [/block] **Additional Considerations** - **Prompt()** will invoke the Opt-in experience if: * The user has not yet subscribed or blocked the subscription * The user has not dismissed the Opt-In dialog in the last 7 days * Otherwise **prompt()** will NOT invoke the Opt-in experience. - Calling **prompt()** requires that the base Roost javascript must be somewhere on the page. - [Auto-Prompt](doc:auto-prompt) must be disabled for prompt to function correctly. [block:code] { "codes": [ { "code": "<!-- EXAMPLE: PROMPT AFTER SOME CONDITION OCCURS -->\n\n<!-- First you have to disable the auto-prompt - somewhere after the base roost javascript -->\n<script>\n var _roost = _roost || [];\n _roost.push(['autoprompt', false]);\n</script>\n.\n.\n.\n<!-- Then your trigger -->\nfunction oneOfYourFunctions() {\n .\n .\n .\n _roost.prompt();\n}", "language": "text" } ], "sidebar": true } [/block] [block:api-header] { "type": "basic", "title": "HTTP vs HTTPS" } [/block] The behavior of prompt() varies slightly for sites served via HTTP vs HTTPS. **HTTP**: **prompt()** will invoke the Opt-in Flyout, which then invokes the native opt-in experience on a roost-hosted secure page, as seen below. [block:image] { "images": [ { "image": [ "https://files.readme.io/gioNgNPdSkm6q4UDnnCi_flyout.png", "flyout.png", "700", "300", "#644c33", "" ] } ] } [/block] And the second step on the secure page. [block:image] { "images": [ { "image": [ "https://files.readme.io/t8wAzsuQoGSkulr63UEM_opt-in.png", "opt-in.png", "700", "300", "#fc4c40", "" ] } ] } [/block] **HTTPS**: **prompt()** will invoke the native opt-in experience on the current page, as seen below: [block:image] { "images": [ { "image": [ "https://files.readme.io/0CO3XMXSAS3zm0i2mE6A_ssl-opt-in.png", "ssl-opt-in.png", "700", "300", "#63492f", "" ] } ] } [/block]
**Prompt **can be used to explicitly invoke the opt-in prompt for the current subscriber. Use **prompt** when you want to delay the Roost opt-in prompt so that it executes in a javascript function, or in reaction to some event. **prompt()** is best used when the trigger for the event is behind-the-scenes. However, if you have a user experience element that invokes the opt-in experience, such as a button, menu item, or dialog -- then it is better to use [register()](doc:register-on-action). [block:html] { "html": "<div style=\"font-size: 14pt; font-weight: bold;\">\n _roost.prompt()\n \n // if called outside of Onload() callback:\n _roost.push([\"onload\", function() { _roost.prompt(); }]);\n</div>" } [/block] **Additional Considerations** - **Prompt()** will invoke the Opt-in experience if: * The user has not yet subscribed or blocked the subscription * The user has not dismissed the Opt-In dialog in the last 7 days * Otherwise **prompt()** will NOT invoke the Opt-in experience. - Calling **prompt()** requires that the base Roost javascript must be somewhere on the page. - [Auto-Prompt](doc:auto-prompt) must be disabled for prompt to function correctly. [block:code] { "codes": [ { "code": "<!-- EXAMPLE: PROMPT AFTER SOME CONDITION OCCURS -->\n\n<!-- First you have to disable the auto-prompt - somewhere after the base roost javascript -->\n<script>\n var _roost = _roost || [];\n _roost.push(['autoprompt', false]);\n</script>\n.\n.\n.\n<!-- Then your trigger -->\nfunction oneOfYourFunctions() {\n .\n .\n .\n _roost.prompt();\n}", "language": "text" } ], "sidebar": true } [/block] [block:api-header] { "type": "basic", "title": "HTTP vs HTTPS" } [/block] The behavior of prompt() varies slightly for sites served via HTTP vs HTTPS. **HTTP**: **prompt()** will invoke the Opt-in Flyout, which then invokes the native opt-in experience on a roost-hosted secure page, as seen below. [block:image] { "images": [ { "image": [ "https://files.readme.io/gioNgNPdSkm6q4UDnnCi_flyout.png", "flyout.png", "700", "300", "#644c33", "" ] } ] } [/block] And the second step on the secure page. [block:image] { "images": [ { "image": [ "https://files.readme.io/t8wAzsuQoGSkulr63UEM_opt-in.png", "opt-in.png", "700", "300", "#fc4c40", "" ] } ] } [/block] **HTTPS**: **prompt()** will invoke the native opt-in experience on the current page, as seen below: [block:image] { "images": [ { "image": [ "https://files.readme.io/0CO3XMXSAS3zm0i2mE6A_ssl-opt-in.png", "ssl-opt-in.png", "700", "300", "#63492f", "" ] } ] } [/block]
{"_id":"5650a9e174ba9a0d0047923d","body":"Targeting your messages better is one of the key approaches to more effective push notifications.  On Roost, **Segments** are the core technology used to do this.\n\nUsing the Javascript API, you can assign Segments to subscribers who are on the current Roost-enabled page.  Once these Segments are assigned, then you can target notifications to subscribers associated with specific Segments.  \n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"On a sports site you might Segment a subscriber with \\\"NFL\\\" or \\\"Seahawks\\\", because they visited pages that are focused on those topics. \\n\\nThis user would then receive notification sent to the the \\\"NFL\\\" and \\\"Seahawks\\\" tags, as well as general broadcast notifications (with no segments specified).\",\n  \"title\": \"Example: Sports Site Segmentation\"\n}\n[/block]\n\n\nAll of segmentation calls require the base Roost javascript on the page.","githubsync":"","hidden":false,"sync_unique":"","__v":0,"api":{"params":[],"url":"","results":{"codes":[{"name":"","status":200,"language":"json","code":"{}"},{"language":"json","code":"{}","name":"","status":400}]},"settings":"","auth":"required"},"order":4,"title":"Segmentation Overview","version":"564b534de5d9d61700d580e5","excerpt":"","project":"564b534ce5d9d61700d580e2","slug":"segmentation-overview","updates":[],"category":"5650a6b2a462732b002b3640","link_external":false,"link_url":"","type":"basic","user":"54ed0ffea45a441700fd4cf0","createdAt":"2015-11-21T17:29:05.990Z","childrenPages":[]}

Segmentation Overview


Targeting your messages better is one of the key approaches to more effective push notifications. On Roost, **Segments** are the core technology used to do this. Using the Javascript API, you can assign Segments to subscribers who are on the current Roost-enabled page. Once these Segments are assigned, then you can target notifications to subscribers associated with specific Segments. [block:callout] { "type": "info", "body": "On a sports site you might Segment a subscriber with \"NFL\" or \"Seahawks\", because they visited pages that are focused on those topics. \n\nThis user would then receive notification sent to the the \"NFL\" and \"Seahawks\" tags, as well as general broadcast notifications (with no segments specified).", "title": "Example: Sports Site Segmentation" } [/block] All of segmentation calls require the base Roost javascript on the page.
Targeting your messages better is one of the key approaches to more effective push notifications. On Roost, **Segments** are the core technology used to do this. Using the Javascript API, you can assign Segments to subscribers who are on the current Roost-enabled page. Once these Segments are assigned, then you can target notifications to subscribers associated with specific Segments. [block:callout] { "type": "info", "body": "On a sports site you might Segment a subscriber with \"NFL\" or \"Seahawks\", because they visited pages that are focused on those topics. \n\nThis user would then receive notification sent to the the \"NFL\" and \"Seahawks\" tags, as well as general broadcast notifications (with no segments specified).", "title": "Example: Sports Site Segmentation" } [/block] All of segmentation calls require the base Roost javascript on the page.
{"_id":"5650aa0525691837008a7fa6","body":"Assign an Alias to a subscriber using the **alias** command.\n\nParameters are passed as an array.\n[block:html]\n{\n  \"html\": \"<div style=\\\"font-size: 14pt; font-weight: bold;\\\">\\n  _roost.push([\\\"alias\\\", &lt;unique id that you provide&gt;])\\n</div>\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"alias\",\n    \"0-1\": \"Command for associating an alias with the current subscriber.\",\n    \"1-0\": \"(unique id)\",\n    \"1-1\": \"Unique identifier that you wish to have associated with this subscriber.\",\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Description\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<!-- ASSIGNING AN ALIAS TO THE CURRENT USER -->\\n\\n<script>\\n    var _roost = _roost || [];\\n    _roost.push([\\\"alias\\\", \\\"amanda@xyz123.com\\\"]);\\n</script>\\n\\n<!-- You will typically replace the email address shown above with server-side script that supplies the unique alias string from your server.  For example: -->\\n\\n<script>\\n    var _roost = _roost || [];\\n    _roost.push([\\\"alias\\\", <?php echo $user_id ?>]);\\n</script>\\n\",\n      \"language\": \"javascript\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"What is an Alias?\"\n}\n[/block]\nIf you need to mark a particular subscriber, the Roost term for this is **'Alias.' ** You can assign any string as an Alias for a subscriber.  Often this is the subscriber's email, or an internal ID that you use on your servers.  \n\nAliases are most applicable on sites with a login or membership feature.","link_external":false,"project":"564b534ce5d9d61700d580e2","slug":"segmenting-individuals-alias","version":"564b534de5d9d61700d580e5","githubsync":"","hidden":false,"title":"Segmenting Individuals - Alias","updates":[],"createdAt":"2015-11-21T17:29:41.460Z","excerpt":"","link_url":"","order":5,"type":"basic","user":"54ed0ffea45a441700fd4cf0","__v":0,"api":{"params":[],"url":"","results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required"},"category":"5650a6b2a462732b002b3640","sync_unique":"","childrenPages":[]}

Segmenting Individuals - Alias


Assign an Alias to a subscriber using the **alias** command. Parameters are passed as an array. [block:html] { "html": "<div style=\"font-size: 14pt; font-weight: bold;\">\n _roost.push([\"alias\", &lt;unique id that you provide&gt;])\n</div>" } [/block] [block:parameters] { "data": { "0-0": "alias", "0-1": "Command for associating an alias with the current subscriber.", "1-0": "(unique id)", "1-1": "Unique identifier that you wish to have associated with this subscriber.", "h-0": "Parameter", "h-1": "Description" }, "cols": 2, "rows": 2 } [/block] [block:code] { "codes": [ { "code": "<!-- ASSIGNING AN ALIAS TO THE CURRENT USER -->\n\n<script>\n var _roost = _roost || [];\n _roost.push([\"alias\", \"amanda@xyz123.com\"]);\n</script>\n\n<!-- You will typically replace the email address shown above with server-side script that supplies the unique alias string from your server. For example: -->\n\n<script>\n var _roost = _roost || [];\n _roost.push([\"alias\", <?php echo $user_id ?>]);\n</script>\n", "language": "javascript" } ], "sidebar": true } [/block] [block:api-header] { "type": "basic", "title": "What is an Alias?" } [/block] If you need to mark a particular subscriber, the Roost term for this is **'Alias.' ** You can assign any string as an Alias for a subscriber. Often this is the subscriber's email, or an internal ID that you use on your servers. Aliases are most applicable on sites with a login or membership feature.
Assign an Alias to a subscriber using the **alias** command. Parameters are passed as an array. [block:html] { "html": "<div style=\"font-size: 14pt; font-weight: bold;\">\n _roost.push([\"alias\", &lt;unique id that you provide&gt;])\n</div>" } [/block] [block:parameters] { "data": { "0-0": "alias", "0-1": "Command for associating an alias with the current subscriber.", "1-0": "(unique id)", "1-1": "Unique identifier that you wish to have associated with this subscriber.", "h-0": "Parameter", "h-1": "Description" }, "cols": 2, "rows": 2 } [/block] [block:code] { "codes": [ { "code": "<!-- ASSIGNING AN ALIAS TO THE CURRENT USER -->\n\n<script>\n var _roost = _roost || [];\n _roost.push([\"alias\", \"amanda@xyz123.com\"]);\n</script>\n\n<!-- You will typically replace the email address shown above with server-side script that supplies the unique alias string from your server. For example: -->\n\n<script>\n var _roost = _roost || [];\n _roost.push([\"alias\", <?php echo $user_id ?>]);\n</script>\n", "language": "javascript" } ], "sidebar": true } [/block] [block:api-header] { "type": "basic", "title": "What is an Alias?" } [/block] If you need to mark a particular subscriber, the Roost term for this is **'Alias.' ** You can assign any string as an Alias for a subscriber. Often this is the subscriber's email, or an internal ID that you use on your servers. Aliases are most applicable on sites with a login or membership feature.
{"_id":"5650aa2425691837008a7fa8","slug":"set-segments","title":"Set Segments","user":"54ed0ffea45a441700fd4cf0","excerpt":"","link_external":false,"project":"564b534ce5d9d61700d580e2","body":"Set the Segments for a subscriber using the **segments** command.  \n\nThis call replaces any Segments currently associated with a subscriber - it is not additive.\n\nParameters are passed in an array.\n[block:html]\n{\n  \"html\": \"<div style=\\\"font-size: 14pt; font-weight: bold;\\\">\\n  _roost.push([\\\"segments\\\", &lt;first&gt;, &lt;second&gt;, ..., &lt;last&gt;])\\n</div>\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"segments\",\n    \"0-1\": \"Command to set the segments for a subscriber\",\n    \"1-0\": \"(remaining parameters)\",\n    \"1-1\": \"Segments to be added (replacing previous segment list)\",\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Description\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<!-- 'Segments' OPERATION WILL SET THE LIST OF SEGMENTS FOR A SUBSCRIBER -->\\n<script>\\n    var _roost = _roost || [];\\n    _roost.push([\\\"segments\\\", \\\"breakingnews\\\", \\\"sports\\\"]);\\n</script>\",\n      \"language\": \"text\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]","hidden":false,"sync_unique":"","type":"basic","version":"564b534de5d9d61700d580e5","__v":0,"order":6,"createdAt":"2015-11-21T17:30:12.851Z","githubsync":"","link_url":"","updates":[],"api":{"params":[],"url":"","results":{"codes":[{"code":"{}","name":"","status":200,"language":"json"},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required"},"category":"5650a6b2a462732b002b3640","childrenPages":[]}

Set Segments


Set the Segments for a subscriber using the **segments** command. This call replaces any Segments currently associated with a subscriber - it is not additive. Parameters are passed in an array. [block:html] { "html": "<div style=\"font-size: 14pt; font-weight: bold;\">\n _roost.push([\"segments\", &lt;first&gt;, &lt;second&gt;, ..., &lt;last&gt;])\n</div>" } [/block] [block:parameters] { "data": { "0-0": "segments", "0-1": "Command to set the segments for a subscriber", "1-0": "(remaining parameters)", "1-1": "Segments to be added (replacing previous segment list)", "h-0": "Parameter", "h-1": "Description" }, "cols": 2, "rows": 2 } [/block] [block:code] { "codes": [ { "code": "<!-- 'Segments' OPERATION WILL SET THE LIST OF SEGMENTS FOR A SUBSCRIBER -->\n<script>\n var _roost = _roost || [];\n _roost.push([\"segments\", \"breakingnews\", \"sports\"]);\n</script>", "language": "text" } ], "sidebar": true } [/block]
Set the Segments for a subscriber using the **segments** command. This call replaces any Segments currently associated with a subscriber - it is not additive. Parameters are passed in an array. [block:html] { "html": "<div style=\"font-size: 14pt; font-weight: bold;\">\n _roost.push([\"segments\", &lt;first&gt;, &lt;second&gt;, ..., &lt;last&gt;])\n</div>" } [/block] [block:parameters] { "data": { "0-0": "segments", "0-1": "Command to set the segments for a subscriber", "1-0": "(remaining parameters)", "1-1": "Segments to be added (replacing previous segment list)", "h-0": "Parameter", "h-1": "Description" }, "cols": 2, "rows": 2 } [/block] [block:code] { "codes": [ { "code": "<!-- 'Segments' OPERATION WILL SET THE LIST OF SEGMENTS FOR A SUBSCRIBER -->\n<script>\n var _roost = _roost || [];\n _roost.push([\"segments\", \"breakingnews\", \"sports\"]);\n</script>", "language": "text" } ], "sidebar": true } [/block]
{"_id":"5650aa43bde46b17002bc534","sync_unique":"","title":"Add Segments","version":"564b534de5d9d61700d580e5","body":"Associate additional Segments with a subscriber with the **segments_add** command.\n\nParameters are passed in an array.\n[block:html]\n{\n  \"html\": \"<div style=\\\"font-size: 14pt; font-weight: bold;\\\">\\n  _roost.push([\\\"segments_add\\\", &lt;first&gt;, &lt;second&gt;, ..., &lt;last&gt;])\\n</div>\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-1\": \"Command to add segments for the current subscriber\",\n    \"0-0\": \"segments_add\",\n    \"1-0\": \"(remaining parameters)\",\n    \"1-1\": \"Segments to be added\",\n    \"h-0\": \"Parameters\",\n    \"h-1\": \"Description\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Example\"\n}\n[/block]\nThe Example will add three Segments for the current user: \"breakingnews\", \"politics\", and \"sports\".\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<!-- \\\"segments_add\\\" OPERATION WILL ASSOCIATE ADDITIONAL SEGMENTS WITH A SUBSCRIBER -->\\n<script>\\n    var _roost = _roost || [];\\n    _roost.push([\\\"segments_add\\\", \\\"breakingnews\\\", \\\"politics\\\", \\\"sports\\\"]);\\n</script>\",\n      \"language\": \"text\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]","githubsync":"","link_external":false,"order":7,"slug":"add-segments","type":"basic","updates":[],"api":{"results":{"codes":[{"language":"json","code":"{}","name":"","status":200},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"category":"5650a6b2a462732b002b3640","createdAt":"2015-11-21T17:30:43.417Z","project":"564b534ce5d9d61700d580e2","user":"54ed0ffea45a441700fd4cf0","__v":0,"excerpt":"","hidden":false,"link_url":"","childrenPages":[]}

Add Segments


Associate additional Segments with a subscriber with the **segments_add** command. Parameters are passed in an array. [block:html] { "html": "<div style=\"font-size: 14pt; font-weight: bold;\">\n _roost.push([\"segments_add\", &lt;first&gt;, &lt;second&gt;, ..., &lt;last&gt;])\n</div>" } [/block] [block:parameters] { "data": { "0-1": "Command to add segments for the current subscriber", "0-0": "segments_add", "1-0": "(remaining parameters)", "1-1": "Segments to be added", "h-0": "Parameters", "h-1": "Description" }, "cols": 2, "rows": 2 } [/block] [block:api-header] { "type": "basic", "title": "Example" } [/block] The Example will add three Segments for the current user: "breakingnews", "politics", and "sports". [block:code] { "codes": [ { "code": "<!-- \"segments_add\" OPERATION WILL ASSOCIATE ADDITIONAL SEGMENTS WITH A SUBSCRIBER -->\n<script>\n var _roost = _roost || [];\n _roost.push([\"segments_add\", \"breakingnews\", \"politics\", \"sports\"]);\n</script>", "language": "text" } ], "sidebar": true } [/block]
Associate additional Segments with a subscriber with the **segments_add** command. Parameters are passed in an array. [block:html] { "html": "<div style=\"font-size: 14pt; font-weight: bold;\">\n _roost.push([\"segments_add\", &lt;first&gt;, &lt;second&gt;, ..., &lt;last&gt;])\n</div>" } [/block] [block:parameters] { "data": { "0-1": "Command to add segments for the current subscriber", "0-0": "segments_add", "1-0": "(remaining parameters)", "1-1": "Segments to be added", "h-0": "Parameters", "h-1": "Description" }, "cols": 2, "rows": 2 } [/block] [block:api-header] { "type": "basic", "title": "Example" } [/block] The Example will add three Segments for the current user: "breakingnews", "politics", and "sports". [block:code] { "codes": [ { "code": "<!-- \"segments_add\" OPERATION WILL ASSOCIATE ADDITIONAL SEGMENTS WITH A SUBSCRIBER -->\n<script>\n var _roost = _roost || [];\n _roost.push([\"segments_add\", \"breakingnews\", \"politics\", \"sports\"]);\n</script>", "language": "text" } ], "sidebar": true } [/block]
{"_id":"5650aa66bde46b17002bc536","api":{"url":"","results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"language":"json","code":"{}","name":"","status":400}]},"settings":"","auth":"required","params":[]},"hidden":false,"slug":"remove-segments","version":"564b534de5d9d61700d580e5","title":"Remove Segments","order":8,"project":"564b534ce5d9d61700d580e2","__v":0,"body":"Remove (disassociate) a set of Segments from a subscriber using the **segments_remove** command.  \n[block:html]\n{\n  \"html\": \"<div style=\\\"font-size: 14pt; font-weight: bold;\\\">\\n  _roost.push([\\\"segments_remove\\\", &lt;first&gt;, &lt;second&gt;, ..., &lt;last&gt;])\\n</div>\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"segments_remove\",\n    \"0-1\": \"Specifies that the following parameters are segments to be disassociated with the subscriber.\",\n    \"1-0\": \"(remaining parameters)\",\n    \"1-1\": \"Segments to be removed.\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<!-- DISASSOCIATES A LIST OF SEGMENTS FROM A SUBSCRIBER -->\\n<script>\\n    var _roost = _roost || [];\\n    _roost.push([\\\"segments_remove\\\", \\\"boringnews\\\"]);\\n</script>\",\n      \"language\": \"text\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]","createdAt":"2015-11-21T17:31:18.123Z","githubsync":"","link_external":false,"link_url":"","type":"basic","updates":[],"user":"54ed0ffea45a441700fd4cf0","category":"5650a6b2a462732b002b3640","excerpt":"","sync_unique":"","childrenPages":[]}

Remove Segments


Remove (disassociate) a set of Segments from a subscriber using the **segments_remove** command. [block:html] { "html": "<div style=\"font-size: 14pt; font-weight: bold;\">\n _roost.push([\"segments_remove\", &lt;first&gt;, &lt;second&gt;, ..., &lt;last&gt;])\n</div>" } [/block] [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Description", "0-0": "segments_remove", "0-1": "Specifies that the following parameters are segments to be disassociated with the subscriber.", "1-0": "(remaining parameters)", "1-1": "Segments to be removed." }, "cols": 2, "rows": 2 } [/block] [block:code] { "codes": [ { "code": "<!-- DISASSOCIATES A LIST OF SEGMENTS FROM A SUBSCRIBER -->\n<script>\n var _roost = _roost || [];\n _roost.push([\"segments_remove\", \"boringnews\"]);\n</script>", "language": "text" } ], "sidebar": true } [/block]
Remove (disassociate) a set of Segments from a subscriber using the **segments_remove** command. [block:html] { "html": "<div style=\"font-size: 14pt; font-weight: bold;\">\n _roost.push([\"segments_remove\", &lt;first&gt;, &lt;second&gt;, ..., &lt;last&gt;])\n</div>" } [/block] [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Description", "0-0": "segments_remove", "0-1": "Specifies that the following parameters are segments to be disassociated with the subscriber.", "1-0": "(remaining parameters)", "1-1": "Segments to be removed." }, "cols": 2, "rows": 2 } [/block] [block:code] { "codes": [ { "code": "<!-- DISASSOCIATES A LIST OF SEGMENTS FROM A SUBSCRIBER -->\n<script>\n var _roost = _roost || [];\n _roost.push([\"segments_remove\", \"boringnews\"]);\n</script>", "language": "text" } ], "sidebar": true } [/block]
{"_id":"5650aa92c285ce170068b621","hidden":false,"link_url":"","user":"54ed0ffea45a441700fd4cf0","body":"**supportedBrowser()** returns true if the current browser supports Roost browser notifications.  Remember that this function, like all **_roost** functions must be called during or after **[onLoad()](doc:initialization-callback-onload)** (typically in the onload() callback).\n[block:html]\n{\n  \"html\": \"<div style=\\\"font-size: 14pt; font-weight: bold;\\\">\\n  _roost.supportedBrowser();\\n  \\n  // if called outside of Onload() callback:\\n  _roost.push([\\\"onload\\\", function() { _roost.supportedBrowser(); }]);\\n</div>\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Examples\"\n}\n[/block]\nFor the example, let's do something practical.  Let's say you have a div containing a call to action for notifications, and maybe some settings.  But you only want to show it if notifications are usable in this browser.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<!-- EXAMPLE: SHOW A DIV ONLY WHEN NOTIFICATIONS WORK IN THIS BROWSER -->\\n\\n<script>\\n    var _roost = _roost || [];\\n    _roost.push(['onload', function(data) {\\n        if (_roost.supportedBrowser()) {\\n            //show your div here\\n        }\\n    }]);\\n</script>\",\n      \"language\": \"text\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]","category":"5650a6b2a462732b002b3640","excerpt":"","githubsync":"","order":9,"type":"basic","updates":[],"createdAt":"2015-11-21T17:32:02.399Z","project":"564b534ce5d9d61700d580e2","title":"Is Browser Supported","link_external":false,"slug":"is-browser-supported","sync_unique":"","version":"564b534de5d9d61700d580e5","__v":2,"api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"language":"json","code":"{}","name":"","status":400}]},"settings":"","url":"","auth":"required","params":[]},"childrenPages":[]}

Is Browser Supported


**supportedBrowser()** returns true if the current browser supports Roost browser notifications. Remember that this function, like all **_roost** functions must be called during or after **[onLoad()](doc:initialization-callback-onload)** (typically in the onload() callback). [block:html] { "html": "<div style=\"font-size: 14pt; font-weight: bold;\">\n _roost.supportedBrowser();\n \n // if called outside of Onload() callback:\n _roost.push([\"onload\", function() { _roost.supportedBrowser(); }]);\n</div>" } [/block] [block:api-header] { "type": "basic", "title": "Examples" } [/block] For the example, let's do something practical. Let's say you have a div containing a call to action for notifications, and maybe some settings. But you only want to show it if notifications are usable in this browser. [block:code] { "codes": [ { "code": "<!-- EXAMPLE: SHOW A DIV ONLY WHEN NOTIFICATIONS WORK IN THIS BROWSER -->\n\n<script>\n var _roost = _roost || [];\n _roost.push(['onload', function(data) {\n if (_roost.supportedBrowser()) {\n //show your div here\n }\n }]);\n</script>", "language": "text" } ], "sidebar": true } [/block]
**supportedBrowser()** returns true if the current browser supports Roost browser notifications. Remember that this function, like all **_roost** functions must be called during or after **[onLoad()](doc:initialization-callback-onload)** (typically in the onload() callback). [block:html] { "html": "<div style=\"font-size: 14pt; font-weight: bold;\">\n _roost.supportedBrowser();\n \n // if called outside of Onload() callback:\n _roost.push([\"onload\", function() { _roost.supportedBrowser(); }]);\n</div>" } [/block] [block:api-header] { "type": "basic", "title": "Examples" } [/block] For the example, let's do something practical. Let's say you have a div containing a call to action for notifications, and maybe some settings. But you only want to show it if notifications are usable in this browser. [block:code] { "codes": [ { "code": "<!-- EXAMPLE: SHOW A DIV ONLY WHEN NOTIFICATIONS WORK IN THIS BROWSER -->\n\n<script>\n var _roost = _roost || [];\n _roost.push(['onload', function(data) {\n if (_roost.supportedBrowser()) {\n //show your div here\n }\n }]);\n</script>", "language": "text" } ], "sidebar": true } [/block]
{"_id":"5650aabba462732b002b3644","githubsync":"","link_external":false,"link_url":"","order":10,"sync_unique":"","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"**promptable()** returns true if  the current browser supports notifications, and the user has not committed (allowed/disallowed).  \n\nThis is similar to [supportedBrowser()](doc:is-supported-browser), but with the additional condition for the user's subscription status.\n\nBest called inside [Onload()](doc:initialization-callback-onload), or afterwards.\n[block:html]\n{\n  \"html\": \"<div style=\\\"font-size: 14pt; font-weight: bold;\\\">\\n  _roost.promptable();\\n  \\n  // if called outside of Onload() callback:\\n  _roost.push([\\\"onload\\\", function() { _roost.promptable(); }]);\\n</div>\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Example\"\n}\n[/block]\nSimilar to the example for [supportedBrowser()](doc:is-supported-browser), let's show a div only when opt-in is possible, and the user has not committed yet.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<!-- EXAMPLE: SHOW A DIV ONLY WHEN PROMPTING\\n     THE USER TO OPT-IN IS POSSIBLE -->\\n\\n<script>\\n    var _roost = _roost || [];\\n    _roost.push(['onload', function(data) {\\n        if (_roost.promptable()) {\\n            //show your div here\\n        }\\n    }]);\\n</script>\",\n      \"language\": \"text\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]","createdAt":"2015-11-21T17:32:43.210Z","type":"basic","title":"Is Promptable","version":"564b534de5d9d61700d580e5","category":"5650a6b2a462732b002b3640","excerpt":"","project":"564b534ce5d9d61700d580e2","__v":1,"hidden":false,"slug":"is-promptable","updates":[],"user":"54ed0ffea45a441700fd4cf0","childrenPages":[]}

Is Promptable


**promptable()** returns true if the current browser supports notifications, and the user has not committed (allowed/disallowed). This is similar to [supportedBrowser()](doc:is-supported-browser), but with the additional condition for the user's subscription status. Best called inside [Onload()](doc:initialization-callback-onload), or afterwards. [block:html] { "html": "<div style=\"font-size: 14pt; font-weight: bold;\">\n _roost.promptable();\n \n // if called outside of Onload() callback:\n _roost.push([\"onload\", function() { _roost.promptable(); }]);\n</div>" } [/block] [block:api-header] { "type": "basic", "title": "Example" } [/block] Similar to the example for [supportedBrowser()](doc:is-supported-browser), let's show a div only when opt-in is possible, and the user has not committed yet. [block:code] { "codes": [ { "code": "<!-- EXAMPLE: SHOW A DIV ONLY WHEN PROMPTING\n THE USER TO OPT-IN IS POSSIBLE -->\n\n<script>\n var _roost = _roost || [];\n _roost.push(['onload', function(data) {\n if (_roost.promptable()) {\n //show your div here\n }\n }]);\n</script>", "language": "text" } ], "sidebar": true } [/block]
**promptable()** returns true if the current browser supports notifications, and the user has not committed (allowed/disallowed). This is similar to [supportedBrowser()](doc:is-supported-browser), but with the additional condition for the user's subscription status. Best called inside [Onload()](doc:initialization-callback-onload), or afterwards. [block:html] { "html": "<div style=\"font-size: 14pt; font-weight: bold;\">\n _roost.promptable();\n \n // if called outside of Onload() callback:\n _roost.push([\"onload\", function() { _roost.promptable(); }]);\n</div>" } [/block] [block:api-header] { "type": "basic", "title": "Example" } [/block] Similar to the example for [supportedBrowser()](doc:is-supported-browser), let's show a div only when opt-in is possible, and the user has not committed yet. [block:code] { "codes": [ { "code": "<!-- EXAMPLE: SHOW A DIV ONLY WHEN PROMPTING\n THE USER TO OPT-IN IS POSSIBLE -->\n\n<script>\n var _roost = _roost || [];\n _roost.push(['onload', function(data) {\n if (_roost.promptable()) {\n //show your div here\n }\n }]);\n</script>", "language": "text" } ], "sidebar": true } [/block]
{"_id":"5650ab560bf9ee3500cd05c3","link_url":"","user":"54ed0ffea45a441700fd4cf0","__v":0,"githubsync":"","title":"Enable/Disable","updates":[],"version":"564b534de5d9d61700d580e5","api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"body":"The **Enable** call is used to programatically enable or disable the current user's subscription.  \n\nThis is normally done in response to some event or user action, such as clicking a 'Browser Notifications' checkbox on your settings page.\n\n**Important**:  This call will have effect ONLY IF THE USER IS SUBSCRIBED.  The enable/disable state modifies an active subscription, and will have no effect on users who have disallowed notifications, or who have not opted-in yet.\n[block:html]\n{\n  \"html\": \"<div style=\\\"font-size: 14pt; font-weight: bold;\\\">\\n    _roost.push(['enable', &lt;boolean&gt;]);\\n</div>\\n\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameters\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"enable\",\n    \"0-1\": \"Command to modify an active subscriber's enabled state\",\n    \"1-0\": \"(boolean)\",\n    \"1-1\": \"Set to 'true' to enable current subscription, and 'false' to disable.\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Example\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<!-- EXAMPLE:  DISABLE THE CURRENT USER'S\\n     NOTIFICATION SUBSCRIPTION -->\\n<script>\\n    var _roost = _roost || [];\\n    _roost.push([\\\"enable\\\", \\\"false\\\"]);\\n</script>\",\n      \"language\": \"text\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]","createdAt":"2015-11-21T17:35:18.554Z","project":"564b534ce5d9d61700d580e2","slug":"enabledisable","sync_unique":"","category":"5650a6b2a462732b002b3640","excerpt":"","hidden":false,"link_external":false,"order":11,"type":"basic","childrenPages":[]}

Enable/Disable


The **Enable** call is used to programatically enable or disable the current user's subscription. This is normally done in response to some event or user action, such as clicking a 'Browser Notifications' checkbox on your settings page. **Important**: This call will have effect ONLY IF THE USER IS SUBSCRIBED. The enable/disable state modifies an active subscription, and will have no effect on users who have disallowed notifications, or who have not opted-in yet. [block:html] { "html": "<div style=\"font-size: 14pt; font-weight: bold;\">\n _roost.push(['enable', &lt;boolean&gt;]);\n</div>\n" } [/block] [block:parameters] { "data": { "h-0": "Parameters", "h-1": "Description", "0-0": "enable", "0-1": "Command to modify an active subscriber's enabled state", "1-0": "(boolean)", "1-1": "Set to 'true' to enable current subscription, and 'false' to disable." }, "cols": 2, "rows": 2 } [/block] [block:api-header] { "type": "basic", "title": "Example" } [/block] [block:code] { "codes": [ { "code": "<!-- EXAMPLE: DISABLE THE CURRENT USER'S\n NOTIFICATION SUBSCRIPTION -->\n<script>\n var _roost = _roost || [];\n _roost.push([\"enable\", \"false\"]);\n</script>", "language": "text" } ], "sidebar": true } [/block]
The **Enable** call is used to programatically enable or disable the current user's subscription. This is normally done in response to some event or user action, such as clicking a 'Browser Notifications' checkbox on your settings page. **Important**: This call will have effect ONLY IF THE USER IS SUBSCRIBED. The enable/disable state modifies an active subscription, and will have no effect on users who have disallowed notifications, or who have not opted-in yet. [block:html] { "html": "<div style=\"font-size: 14pt; font-weight: bold;\">\n _roost.push(['enable', &lt;boolean&gt;]);\n</div>\n" } [/block] [block:parameters] { "data": { "h-0": "Parameters", "h-1": "Description", "0-0": "enable", "0-1": "Command to modify an active subscriber's enabled state", "1-0": "(boolean)", "1-1": "Set to 'true' to enable current subscription, and 'false' to disable." }, "cols": 2, "rows": 2 } [/block] [block:api-header] { "type": "basic", "title": "Example" } [/block] [block:code] { "codes": [ { "code": "<!-- EXAMPLE: DISABLE THE CURRENT USER'S\n NOTIFICATION SUBSCRIPTION -->\n<script>\n var _roost = _roost || [];\n _roost.push([\"enable\", \"false\"]);\n</script>", "language": "text" } ], "sidebar": true } [/block]