Segments

Overview

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:

API Call	Purpose
segment_category	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.
segment_category_association	Associate a Segment with a Segment Category. A Segment may be associated with zero, one, or many Segment Categories.
segment_sharing	Enable another Account on the same Buzz instance to use the Segment.
segment_upload	Schedule a bulk file of user-segment associations to be processed.
segment_update	Use the API to map a cookie or unique identifier to a Segment (similar to Segment Upload)
segment_tag	Retrieve a tag to use on your website or app to place a user into a Segment
Events	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
segment_lookup	GET a list of Segments shared with the requesting Account
segment_category_lookup	GET a list of Segment Categories shared with the requesting Account

Segment Uploads

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_id field 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_upload method 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_upload records 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>|<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. Values must be specified as a float (number). Strings will not be accepted, and the row may be not be written.

Segment Upload Best Practices

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' segment_file_list array.

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.