{"_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":13,"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_upload](doc:segment_upload)\",\n    \"3-1\": \"Schedule a bulk file of user-segment associations to be processed.\",\n    \"5-0\": \"[segment_tag](doc:segment_tag)\",\n    \"5-1\": \"Retrieve a tag to use on your website or app to place a user into a Segment\",\n    \"6-0\": \"[event](doc:events)\",\n    \"6-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    \"7-0\": \"[segment_lookup](doc:segment_lookup)\",\n    \"7-1\": \"GET a list of Segments shared with the requesting Account\",\n    \"8-0\": \"[segment_category_lookup](doc:segment_category_lookup)\",\n    \"8-1\": \"GET a list of Segment Categories shared with the requesting Account\",\n    \"4-0\": \"[segment_update](doc:segment_update)\",\n    \"4-1\": \"Use the API to map a cookie or unique identifier to a Segment (similar to Segment Upload)\"\n  },\n  \"cols\": 2,\n  \"rows\": 9\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 users who have large customer databases they wish to use for bidding.\n\nThe workflow for uploading files is straight-forward:\n\n1. For cookie-based users only: 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 set up by an administrator.\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 uploads files to an S3 bucket, then uses the Buzz API to POST the location of these files. The `segment_upload` method includes instructions and sample POSTs.\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\n[block:api-header]\n{\n  \"title\": \"Segment Upload Best Practices\"\n}\n[/block]\n**Best Practice #1: Don't alternate ADD and REMOVE operations. Instead, submit like operations consecutively.**\n\nBeeswax processes segment uploads in the order they are received and uploads with the same value for the `operation_type` field are processed simultaneously. An upload pattern with alternating operation types (e.g. `ADD_SEGMENTS, REMOVE_SEGMENTS, ADD_SEGMENTS, REMOVE_SEGMENTS, ADD_SEGMENTS, REMOVE_SEGMENTS `) might take 3 times as long as if the same uploads were submitted in like order: `ADD_SEGMENTS, ADD_SEGMENTS, ADD_SEGMENTS, REMOVE_SEGMENTS, REMOVE_SEGMENTS, REMOVE_SEGMENTS`. In the first scenario, Beeswax will process one upload at a time, serially, but in the second scenario, Beeswax will process all three ADD uploads at the same time followed by all three REMOVE uploads at the same time.\n\n**Best Practice #2: Submit larger uploads.**\n\nIn general, larger uploads are more efficient to process. The worst case is to submit many medium-sized uploads; it is much better to submit fewer, larger uploads. Beeswax can handle uploads that contain hundreds of millions of records and are up to 10GB in size.\n\n**Best Practice #3: Batch multiple files into a single upload.**\n\nIf you already have your files broken up into multiple small or medium sized files, submit them in a single, batched, segment upload. Beeswax will process the batch as if they were a single file, which will be much faster and more efficient than if they were created as individual segment uploads.\n\n**Best Practice #4: Track Which Segment IDs Are Contained in Each Upload.**\n\nIn the event you or the Beeswax team need to troubleshoot why a segment doesn't contain any users, or find out which users are contained in a given segment, you will need to have some sort of reference associating segment IDs with the segment uploads that populated their users.","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_upload](doc:segment_upload)", "3-1": "Schedule a bulk file of user-segment associations to be processed.", "5-0": "[segment_tag](doc:segment_tag)", "5-1": "Retrieve a tag to use on your website or app to place a user into a Segment", "6-0": "[event](doc:events)", "6-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", "7-0": "[segment_lookup](doc:segment_lookup)", "7-1": "GET a list of Segments shared with the requesting Account", "8-0": "[segment_category_lookup](doc:segment_category_lookup)", "8-1": "GET a list of Segment Categories shared with the requesting Account", "4-0": "[segment_update](doc:segment_update)", "4-1": "Use the API to map a cookie or unique identifier to a Segment (similar to Segment Upload)" }, "cols": 2, "rows": 9 } [/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 users who have large customer databases they wish to use for bidding. The workflow for uploading files is straight-forward: 1. For cookie-based users only: 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 set up by an administrator. 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 uploads files to an S3 bucket, then uses the Buzz API to POST the location of these files. The `segment_upload` method includes instructions and sample POSTs. 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 [block:api-header] { "title": "Segment Upload Best Practices" } [/block] **Best Practice #1: Don't alternate ADD and REMOVE operations. Instead, submit like operations consecutively.** Beeswax processes segment uploads in the order they are received and uploads with the same value for the `operation_type` field are processed simultaneously. An upload pattern with alternating operation types (e.g. `ADD_SEGMENTS, REMOVE_SEGMENTS, ADD_SEGMENTS, REMOVE_SEGMENTS, ADD_SEGMENTS, REMOVE_SEGMENTS `) might take 3 times as long as if the same uploads were submitted in like order: `ADD_SEGMENTS, ADD_SEGMENTS, ADD_SEGMENTS, REMOVE_SEGMENTS, REMOVE_SEGMENTS, REMOVE_SEGMENTS`. In the first scenario, Beeswax will process one upload at a time, serially, but in the second scenario, Beeswax will process all three ADD uploads at the same time followed by all three REMOVE uploads at the same time. **Best Practice #2: Submit larger uploads.** In general, larger uploads are more efficient to process. The worst case is to submit many medium-sized uploads; it is much better to submit fewer, larger uploads. Beeswax can handle uploads that contain hundreds of millions of records and are up to 10GB in size. **Best Practice #3: Batch multiple files into a single upload.** If you already have your files broken up into multiple small or medium sized files, submit them in a single, batched, segment upload. Beeswax will process the batch as if they were a single file, which will be much faster and more efficient than if they were created as individual segment uploads. **Best Practice #4: Track Which Segment IDs Are Contained in Each Upload.** In the event you or the Beeswax team need to troubleshoot why a segment doesn't contain any users, or find out which users are contained in a given segment, you will need to have some sort of reference associating segment IDs with the segment uploads that populated their users.