{"_id":"56cf3c4d6c5d7a13005ee88c","__v":11,"githubsync":"","parentDoc":null,"user":"56c39c05bc41330d009f25d7","category":{"_id":"56c7bab4606ee717003c4766","project":"56c35c56c0c4630d004e864c","__v":18,"pages":["56c7c193f9aa3b0d00c8458f","56cb80a4c675f50b00a4b826","56cb83859f4ae20b00644f1f","56cb853a245b841300806f82","56cb863c32011d2500681925","56cb88a4245b841300806f8b","56cb9915245b841300806fa7","56cb9a079f4ae20b00644f48","56cb9b5bc675f50b00a4b859","56cba5929f4ae20b00644f5d","56cba5c5d5c6241d00ef5e93","56cbab9c9f4ae20b00644f76","56cbad69c675f50b00a4b881","56cbb060d5c6241d00ef5ebb","56cf3c4d6c5d7a13005ee88c","56cf3d0e287eb20b009f9ec7","56cf3d7c5267d70b00494c42","56cf3ee0287eb20b009f9ecd"],"version":"56c35c56c0c4630d004e864f","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-02-20T01:00:36.607Z","from_sync":false,"order":0,"slug":"buzz-concepts","title":"Buzz Concepts"},"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"},"project":"56c35c56c0c4630d004e864c","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-25T17:39:25.497Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":12,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Overview\"\n}\n[/block]\n[Segments](doc:segment) are among the more complex objects in Buzz. Like most objects, segments belong to a single Account. Once created, segments are identified and manipulated using the `segment_key` field, which includes a unique key per Buzz instance. We use the `segment_key` instead of the `segment_id` in order to assure uniqueness in the case where multiple instances of Buzz are sharing segments with one another.\n\nBelow is an overview of the API methods relevant to segments:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"API Call\",\n    \"h-1\": \"Purpose\",\n    \"0-0\": \"[segment_category](doc:segment-4)\",\n    \"0-1\": \"Define hierarchical categories in which to organize segments within your Account. A Segment Category may have a parent_category and may be nested up to five levels deep.\",\n    \"1-0\": \"[segment_category_association](doc:segment_category_association)\",\n    \"1-1\": \"Associate a Segment with a Segment Category. A Segment may be associated with zero, one, or many Segment Categories.\",\n    \"2-0\": \"[segment_sharing](doc:segment_sharing)\",\n    \"2-1\": \"Enable another Account on the same Buzz instance to use the Segment.\",\n    \"3-0\": \"[segment_update](doc:segment_update)\",\n    \"3-1\": \"Use the API to map a cookie or unique identifier to a Segment (similar to Segment Upload)\",\n    \"4-0\": \"[segment_tag](doc:segment_tag)\",\n    \"4-1\": \"Retrieve a tag to use on your website or app to place a user into a Segment\",\n    \"5-0\": \"[event](doc:events)\",\n    \"5-1\": \"An Event may include an optional `segment_id field to indicate that whenever the Event is fired the user should be placed in the Segment\",\n    \"6-0\": \"[segment_lookup](doc:segment_lookup)\",\n    \"6-1\": \"GET a list of Segments shared with the requesting Account\",\n    \"7-0\": \"[segment_category_lookup](doc:segment_category_lookup)\",\n    \"7-1\": \"GET a list of Segment Categories shared with the requesting Account\"\n  },\n  \"cols\": 2,\n  \"rows\": 8\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Segment Uploads\"\n}\n[/block]\nBuzz supports the batch upload of text files with user segment data as well as API requests to update user Segments. This is a common need for bidders, especially for users who have large customer databases they wish to use for bidding.\n\nThe workflow for uploading files is straight-forward:\n\n1. Beeswax and the end customer must sync identifiers to allow for use of user data keyed to the customer's identity. This is an asynchronous process.\n2. The customer creates Segments using the Segment method, and optionally uses the `alternative_id` field to map the customer's IDs into Buzz.\n3. The customer uses the Buzz API to POST the files. The `segment_upload` method includes instructions and sample POSTs. After POSTing, the files are uploaded to Amazon's S3.\n4. A server-side process (not documented here) picks up the files, and attempts to insert the records into the user data store\n5. When complete, the server-side process updates the `segment_upload` records with a status and any error messages.\n6. The user can then use a GET request, polling intermittently, to retrieve the results of the upload and respond to any error messages.\n\nAlternatively, for smaller updates (up to 1000 users roughly), you can use the `segment_update`` API call and include the data in the API call instead of uploading a file.\n\nCurrently, Buzz supports only DELIMITED formatted files, in the following format:\n\n`<uuid>|<segment_ID1>:<value>|<segment_ID2>:<value>|<segment_ID3>`\n\nFor example:\n\n```12345678|stinger-123|stinger-456|stinger-789:100```\n\n`uuid` = the user id\n`segment_ID1`=the segment key to be updated in the format `<BUZZ_KEY>-<ID>`. \n\nSegments are created using the segment API. By default the segment_id will be assumed to be the segment_key field from a segment object. However, you can also use your own segment_ids by defining them in the alternative_id field in the segment and passing `segment_key_type=\"ALTERNATIVE\"` in the segment_upload POST.\n\n`value`=optional parameter to be associated with any user-segment combination. For example, you may wish to store the amount a user purchased or the number of pages of content they viewed","excerpt":"","slug":"segments","type":"basic","title":"Segments"}
[block:api-header] { "type": "basic", "title": "Overview" } [/block] [Segments](doc:segment) are among the more complex objects in Buzz. Like most objects, segments belong to a single Account. Once created, segments are identified and manipulated using the `segment_key` field, which includes a unique key per Buzz instance. We use the `segment_key` instead of the `segment_id` in order to assure uniqueness in the case where multiple instances of Buzz are sharing segments with one another. Below is an overview of the API methods relevant to segments: [block:parameters] { "data": { "h-0": "API Call", "h-1": "Purpose", "0-0": "[segment_category](doc:segment-4)", "0-1": "Define hierarchical categories in which to organize segments within your Account. A Segment Category may have a parent_category and may be nested up to five levels deep.", "1-0": "[segment_category_association](doc:segment_category_association)", "1-1": "Associate a Segment with a Segment Category. A Segment may be associated with zero, one, or many Segment Categories.", "2-0": "[segment_sharing](doc:segment_sharing)", "2-1": "Enable another Account on the same Buzz instance to use the Segment.", "3-0": "[segment_update](doc:segment_update)", "3-1": "Use the API to map a cookie or unique identifier to a Segment (similar to Segment Upload)", "4-0": "[segment_tag](doc:segment_tag)", "4-1": "Retrieve a tag to use on your website or app to place a user into a Segment", "5-0": "[event](doc:events)", "5-1": "An Event may include an optional `segment_id field to indicate that whenever the Event is fired the user should be placed in the Segment", "6-0": "[segment_lookup](doc:segment_lookup)", "6-1": "GET a list of Segments shared with the requesting Account", "7-0": "[segment_category_lookup](doc:segment_category_lookup)", "7-1": "GET a list of Segment Categories shared with the requesting Account" }, "cols": 2, "rows": 8 } [/block] [block:api-header] { "type": "basic", "title": "Segment Uploads" } [/block] Buzz supports the batch upload of text files with user segment data as well as API requests to update user Segments. This is a common need for bidders, especially for users who have large customer databases they wish to use for bidding. The workflow for uploading files is straight-forward: 1. Beeswax and the end customer must sync identifiers to allow for use of user data keyed to the customer's identity. This is an asynchronous process. 2. The customer creates Segments using the Segment method, and optionally uses the `alternative_id` field to map the customer's IDs into Buzz. 3. The customer uses the Buzz API to POST the files. The `segment_upload` method includes instructions and sample POSTs. After POSTing, the files are uploaded to Amazon's S3. 4. A server-side process (not documented here) picks up the files, and attempts to insert the records into the user data store 5. When complete, the server-side process updates the `segment_upload` records with a status and any error messages. 6. The user can then use a GET request, polling intermittently, to retrieve the results of the upload and respond to any error messages. Alternatively, for smaller updates (up to 1000 users roughly), you can use the `segment_update`` API call and include the data in the API call instead of uploading a file. Currently, Buzz supports only DELIMITED formatted files, in the following format: `<uuid>|<segment_ID1>:<value>|<segment_ID2>:<value>|<segment_ID3>` For example: ```12345678|stinger-123|stinger-456|stinger-789:100``` `uuid` = the user id `segment_ID1`=the segment key to be updated in the format `<BUZZ_KEY>-<ID>`. Segments are created using the segment API. By default the segment_id will be assumed to be the segment_key field from a segment object. However, you can also use your own segment_ids by defining them in the alternative_id field in the segment and passing `segment_key_type="ALTERNATIVE"` in the segment_upload POST. `value`=optional parameter to be associated with any user-segment combination. For example, you may wish to store the amount a user purchased or the number of pages of content they viewed