{"_id":"57abf2c7ad44fc0e003bdfae","parentDoc":null,"version":{"_id":"56c35c56c0c4630d004e864f","project":"56c35c56c0c4630d004e864c","__v":8,"createdAt":"2016-02-16T17:28:54.864Z","releaseDate":"2016-02-16T17:28:54.864Z","categories":["56c35c57c0c4630d004e8650","56c7b9e5379b311700ed8fe3","56c7bab4606ee717003c4766","56c7bb3613e5400d001e8cbd","56cf3f5a5267d70b00494c4b","56cf3f866c5d7a13005ee894","56fd3956caad892200847bce","599da256e7742b002588bb02"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"0.5.0","version":"0.5"},"category":{"_id":"56c7b9e5379b311700ed8fe3","pages":["56c7ba3853cafe0d00a53daa"],"project":"56c35c56c0c4630d004e864c","version":"56c35c56c0c4630d004e864f","__v":1,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-02-20T00:57:09.551Z","from_sync":false,"order":2,"slug":"stinger","title":"Stinger"},"project":"56c35c56c0c4630d004e864c","githubsync":"","user":"571e5ec87983c03600a41643","__v":2,"updates":["5968c6cf27deef00153af93e"],"next":{"pages":[],"description":""},"createdAt":"2016-08-11T03:36:39.253Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":6,"body":"In order to target your users in a web environment, you must first sync your cookies with the Beeswax cookies. Beeswax handles the syncing with third party inventory providers like Adx and Rubicon, etc.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Buyer-Initiated Cookie Sync\"\n}\n[/block]\nBuyer-initiated cooking syncing has two steps:\n1. The buyer initiates a sync by sending their buyer user ID to Beeswax's cookie match endpoint.\n2. Beeswax then redirects back to a buyer-specified endpoint with both the buyer user ID and the Beeswax user ID.\n\n**1. Buyer initiates cookie sync**\nBeeswax will provide the buyer with a cookie match endpoint.  The endpoint will have this format:\n\n    https://match.prod.bidr.io/cookie-sync/[buyername]?buyer_user_id=[user_id]\n\nOn each cookie sync, the buyer populates the `buyer_user_id` parameter with the user id that the buyer has assigned to the user who is being synced.\n\nIf the buyer has not assigned a user id to the user (if, for example, the user has cookies disabled), then the buyer should not call the Beeswax endpoint, since no cookie sync can be achieved.\n\n**2. Beeswax redirects to buyer provided endpoint**\nUpon receiving a cookie sync request, Beeswax will perform an HTTP redirect to the buyer's cookie sync endpoint.\n\nTypically, this endpoint has two required components,\n1. A parameter that identifies that the incoming sync is coming from Beeswax.\n2. A parameter that holds Beeswax's id for the user.\n\nand one optional component:\n3. Optionally, Beeswax can reflect back, as a url parameter, the _buyer's_ id for this user.  This is not necessarily needed, since the buyer will have presumably already cookied the user, but it is available as an option.\n\nFor example, a typical endpoint would look something like:\n\n    https://buyer.com/usersync?partner=beeswax&beeswax_id=[beeswax_user_id]\n\nor\n\n    https://buyer.com/usersync?partner=beeswax&beeswax_id=[beeswax_user_id]&buyer_user_id=[buyer_user_id]\n\nBy default, when Beeswax redirects to the buyer's endpoint, we will preserve the HTTP scheme (`http` or `https`) of the incoming cookie sync request to Beeswax.\n\n[block:api-header]\n{\n  \"title\": \"Beeswax-Initiated Sync\"\n}\n[/block]\nIn addition to syncs that you initiate, Beeswax will also initiate calls to your sync endpoint in order to maximize coverage. \n\nThese calls will not contain the `buyer_user_id` field. Your sync server should retrieve your buyer id from the cookie headers that will arrive with these calls. These requests can be sent to a separate endpoint if needed.\n\nNote: Beeswax-initiated syncs may contain a referrer header that looks like `https://match.prod.bidr.io/cookie-sync/msync?...`\n\nIf you would like Beeswax not to initiated syncs, please contact us and we will turn the feature off.","excerpt":"","slug":"cookie-syncing","type":"basic","title":"Cookie Syncing"}
In order to target your users in a web environment, you must first sync your cookies with the Beeswax cookies. Beeswax handles the syncing with third party inventory providers like Adx and Rubicon, etc. [block:api-header] { "type": "basic", "title": "Buyer-Initiated Cookie Sync" } [/block] Buyer-initiated cooking syncing has two steps: 1. The buyer initiates a sync by sending their buyer user ID to Beeswax's cookie match endpoint. 2. Beeswax then redirects back to a buyer-specified endpoint with both the buyer user ID and the Beeswax user ID. **1. Buyer initiates cookie sync** Beeswax will provide the buyer with a cookie match endpoint. The endpoint will have this format: https://match.prod.bidr.io/cookie-sync/[buyername]?buyer_user_id=[user_id] On each cookie sync, the buyer populates the `buyer_user_id` parameter with the user id that the buyer has assigned to the user who is being synced. If the buyer has not assigned a user id to the user (if, for example, the user has cookies disabled), then the buyer should not call the Beeswax endpoint, since no cookie sync can be achieved. **2. Beeswax redirects to buyer provided endpoint** Upon receiving a cookie sync request, Beeswax will perform an HTTP redirect to the buyer's cookie sync endpoint. Typically, this endpoint has two required components, 1. A parameter that identifies that the incoming sync is coming from Beeswax. 2. A parameter that holds Beeswax's id for the user. and one optional component: 3. Optionally, Beeswax can reflect back, as a url parameter, the _buyer's_ id for this user. This is not necessarily needed, since the buyer will have presumably already cookied the user, but it is available as an option. For example, a typical endpoint would look something like: https://buyer.com/usersync?partner=beeswax&beeswax_id=[beeswax_user_id] or https://buyer.com/usersync?partner=beeswax&beeswax_id=[beeswax_user_id]&buyer_user_id=[buyer_user_id] By default, when Beeswax redirects to the buyer's endpoint, we will preserve the HTTP scheme (`http` or `https`) of the incoming cookie sync request to Beeswax. [block:api-header] { "title": "Beeswax-Initiated Sync" } [/block] In addition to syncs that you initiate, Beeswax will also initiate calls to your sync endpoint in order to maximize coverage. These calls will not contain the `buyer_user_id` field. Your sync server should retrieve your buyer id from the cookie headers that will arrive with these calls. These requests can be sent to a separate endpoint if needed. Note: Beeswax-initiated syncs may contain a referrer header that looks like `https://match.prod.bidr.io/cookie-sync/msync?...` If you would like Beeswax not to initiated syncs, please contact us and we will turn the feature off.