Segments 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:
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.
Associate a Segment with a Segment Category. A Segment may be associated with zero, one, or many Segment Categories.
Enable another Account on the same Buzz instance to use the Segment.
Schedule a bulk file of user-segment associations to be processed.
Use the API to map a cookie or unique identifier to a Segment (similar to Segment Upload)
Retrieve a tag to use on your website or app to place a user into a Segment
An Event may include an optional
GET a list of Segments shared with the requesting Account
GET a list of Segment Categories shared with the requesting Account
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:
- 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.
- The customer creates Segments using the Segment method, and optionally uses the
alternative_idfield to map the customer's IDs into Buzz.
- The customer uploads files to an S3 bucket, then uses the Buzz API to POST the location of these files. The
segment_uploadmethod includes instructions and sample POSTs.
- A server-side process (not documented here) picks up the files, and attempts to insert the records into the user data store.
- When complete, the server-side process updates the
segment_uploadrecords with a status and any error messages.
- 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 = the user id
segment_ID1=the segment key to be updated in the format
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. Values must be specified as a float (number). Strings will not be accepted, and the row may be not be written.
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: Only include one file per upload.
Our system is optimized to "group" segment uploads together into batches in order to process then in the most efficient manner. As such, try to only include one file in each of your 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.
Updated about 2 years ago