params.json

{
  "name": "Xdomain-cookies",
  "tagline": "A JS lib that provides a mechanism to get/set cookies that can be shared across domains",
  "body": "\r\n#Cross-Domain Cookie Library\r\n\r\nThis library is intended for cases where you have scripts running on different domains (i.e. domain-a.com, domain-b.com) that need to be able to set/share a cookie value across those domains. A few example use cases would be a third-party script that wants to set/share a user identifier across both domains, or a company that wants to track if a user signed up for a newsletter across both their main website and blog that resides on a different TLD.\r\n\r\nThe library leverages 2 files to achieve this - a javascript file you load/run on the page, and an HTML file that gets loaded onto that same page by the JS file. The JS & HTML files both must be served from the same domain/location (such as an s3 bucket). They leverage postMessage across the same/trusted domain to communicate and set the cookie on that domain, which can then be read/written by the same script run on any other domain you give it access to.\r\n\r\nAuthored by *Authored by* [Evan Carothers](https://github.com/ecaroth) @ [Contently](http://www.contently.com)\r\n\r\nRead the backstory and implementation details on the Building Contently Blog entry [Tracking people across multiple domains — when cookies just aren’t enough](https://medium.com/building-contently/tracking-people-across-multiple-domains-when-cookies-just-arent-enough-b270cc95beb1)\r\n\r\nUsage\r\n------\r\n\r\nSimply include the script on any page where it's needed, create a new instance of xDomainCookie, and leverage the get/set functions:\r\n\r\n```html\r\n<script src=\"//my.s3bucket.com/xdomain_cookie.js\"></script>\r\n<script>\r\n\tvar xd_cookie = xDomainCookie( '//my.s3bucket.com' );\r\n\txd_cookie.get( 'cookie_name', function(cookie_val){\r\n\t\t//cookie val will contain value of cookie as fetched from local val (if present) else from iframe (if set), else null\r\n\t\tif(!cookie_val){\r\n\t\t\tvar new_val = get_what_value_should_be();\r\n\t\t\txd_cookie.set( 'cookie_name', new_val );\r\n\t\t}\r\n\t});\r\n</script>\r\n```\r\n\r\nUsage Notes\r\n------\r\n\r\n_Please Note_ that it's important for the `xdomain_cookie.js` file to be served from the same domain _and_ protocol as the path passed in for the iframe creation (when creating `xDomainCookie`). You can setup the script to use whichever page the protocol of the main window is using by specifying `//` as the protocol prefix (instead of explicit `https://` or `http://`, assuming the webserver hosting the `xdomain_cookie.html` file supports that procolol). It's also OK to serve both the script and iframe path over HTTPS in all instances, regardless of if the main page is loaded over HTTPS.\r\n\r\nThis script should work in all modern desktop and mobile browsers that support the postMessage API (IE 8+, Chrome, FF, etc).\r\n\r\nAPI\r\n------\r\n\r\n### xDomainIframe( iframe_domain, namespace, xdomain_only )\r\n> Create a new instance of the xDomainIframe object that creates the iframe in the page and is ready for usage\r\n\r\n> `iframe_domain` _(string, required)_ the domain, and optional path, where the iframe html script should be loaded from - NOTE should match the protocol/host/port of where the JS script is loaded from\r\n\r\n> `namespace` _(string,optional)_ a namespace to use for postMessage passing - prevents collission if you are running multiple instances of this lib on the page... usually not needed\r\n\r\n> `xdomain_only` _(boolean, optional, default false)_ if the cookie should _only_ be set on the xdomain site, not locally.. meaning that the xdomain version acts as the source of truth for the cookie value and eliminates local caching. _PLEASE NOTE_ that this flag can provide specific intended behavior for different use cases. See the _Cross Domain ONLY Cookies_ section further down the readme for more info\r\n\r\n> ```javascript\r\n> //create instance of xDomainIframe with local cookie caching\r\n> var xd_cookie = xDomainIframe( \"//my.trusted-site.com\", \"my.namespace\" );\r\n> \r\n> //create instance of xDomainIframe that uses xdomain_only cookies\r\n> var xd_cookie = xDomainIframe( \"//my.trusted-site.com\", \"my.namespace\", true );\r\n> ```\r\n\r\n###.set( cookie_name, cookie_value, expires_days )\r\n> Set the value of the xdomain (& local) cookie\r\n\r\n> `cookie_name` _(string, required)_ the name of the cookie (both for local domain & iframe domain)\r\n\r\n> `cookie_value` _(string/int/float/obj, required)_ the value of the cookie that we wish to set, get's JSON encoded & serialized\r\n\r\n> `expires_days` _(int, optional)_ # of days to use for setting cookie expiration (default is 30)\r\n\r\n> ```javascript\r\n> my_xdc_instance.set( 'my_cookie', JSON.stringify({foo:\"bar\"}), 15 );\r\n> ```\r\n\r\n\r\n###.get( cookie_name, callback, expires_days )\r\n> Get the value of the xdomain (& local) cookie with complete callback. _NOTE: this function also re-ups the xdomain cookie as if it was being re-set with .set()_\r\n\r\n> `cookie_name` _(string, required)_ the name of the cookie (both for local domain & iframe domain)\r\n\r\n> `callback` _(function, required)_ function that is called upon retreival of iframe cookie - takes 1 arg, which is the cookie value (if present)\r\n\r\n> `expires_days` _(int, optional)_ # of days to use for setting/re-upping cookie expiration (default is 30)\r\n\r\n> ```javascript\r\n> my_xdc_instance.get( 'my_cookie', function( val ){\r\n> \t  console.log(\"Current value of xdomain cookie 'my_cookie'\", val );\r\n> });\r\n> ```\r\n\r\nCross Domain ONLY Cookies\r\n------\r\n\r\nBy default the `xDomainCookies` class is configured to set and use a local cookie as a caching mechanism to allow the callback for `.get()` to return as fast as possible. This is based on the fact that you are setting a piece of information that _should not change_ on any domains you are using the xDomainCookie on, as if you change the cookie from a single domain and it's cached locally at another domain, that local cache will prevent the updated value from being returned by the `get()` callback on that specific domain. \r\n\r\nFor use cases where you are setting a cookie value that should not change (such as something simple like a user ID), allowing the local cookie cache to function is useful and ideal. If, however, you are using advanced data types (such as a serialzed JSON object that has a property that can be updated from multiple domains, and needs to always have the most updated values accessible), then you should pass in `true` for the _xdomain_only_ param when creating a new `xDomainIframe` instance. This means that the local cookie cache isn't used, and the iframe must fully lead before the callback to `get()` will fire, but will guarantee that any interaction with the cookie data will always use up-to-date values.\r\n\r\n\r\nTesting\r\n------\r\n\r\nThere's a full test suite that leverages zombie/connect to mock & test the library behavior across multiple domains in multiple different situations. There is also a pre-build development setup to load/test in local environments in the library. Both of these rely on npm packages, so be sure to do an `npm install` in the root dir before running.\r\n\r\n##### Test suite\r\n```\r\nnpm test\r\n```\r\n\r\n##### Dev Server\r\nThe dev server runs on localhost:3001. Once running you can map whatever hosts to 127.0.0.1 and load the JS in running local pages from {{myhost}}:3001/xdomain_cookie.js.\r\n```\r\nnpm run dev\r\n```\r\n\r\nIt is also pre-configurd with an example scenario that shows usage across domains. It requires you to map the following domains to 127.0.0.1 in your hosts file: shared_cookie_test.com, shared_cookie_test2.com, and shared_cookie_iframe.com\r\n\r\nYou can then see the example working by visiting http://shared_cookie_test.com:3001/test_page.html and shared_cookie_test2.com/test_page.html - take a look at the console output to see cookie behavior.\r\n",
  "note": "Don't delete this file! It's used internally to help with page regeneration."
}