Bidders - Legacy BSS file format
The Batch Segment Service provides the ability to upload segment data files in a variety of formats. For more information, see the examples below.
Note
The Avro format described in BSS Avro File Format, provides support for a broader variety of user identifiers.
The method described in this topic has been the standard format in the past, but it is expected to be deprecated in the future as user identification increasingly relies on EIDs (extended IDs) and publisher first-party identifiers rather than cookies.
Tip
Speak with your account representative for assistance with configuring our system to accept your particular file format.
Format overview
Each line of the file will specify a minimum of one UID (user ID) and one or more SEG blocks. The separators are configurable.
The following table describes the ordering of the blocks and separators that compose each line.
| UID | SEPARATOR1 | SEG | SEPARATOR2 | SEG | SEPARATOR4 | SEG | SEPARATOR2 | SEG | SEPARATOR5 | DOMAIN |
UID
| Name | Type | Description | Example |
|---|---|---|---|
UID |
int | The Xandr user ID being added to, or removed from, a segment. | 5727816213491965430 |
SEG block
The SEG block describes the segment(s) to which the user is being added or removed and it will contain data such as segment ID or a user-defined segment code.
Construct a SEG block as follows:
| SEG_FIELD | SEPARATOR3 | SEG_FIELD |
SEG_FIELD block
The following table list the possible values that may be included in the SEG_FIELD block. Where defaults exist, they will be applied unless otherwise specified. Note that each SEG block must be regular, meaning that it must have all fields that you have chosen to include. For example, if you have included the VALUE field but don't have a value for a particular user, you should use 0 as the value.
| Name | Type | Description | Default | Example |
|---|---|---|---|---|
SEG_ID |
int | The Xandr segment ID. | This is generated by the system when the segment is created. | 1234567890 |
SEG_CODE |
string | A user-defined name for the segment. You may include SEG_CODE or SEG_ID but not both. |
"18-35_autobuy" |
|
EXPIRATION |
int | The lifetime of the segment, starting at the value of TIMESTAMP. Specified in minutes. A value of 0 means that the user will expire in the segment after the maximum allowed 180 days; -1 means that the user will be removed from this segment. |
The default value is specified on the segment level when the segment is created. If none exists there, your Batch Segment API configuration setting is used. Using this field will override the default. | 1440 |
TIMESTAMP |
int | The time at which you would like your segment to go into effect. A UNIX timestamp, down to the second. If a timestamp is submitted to greater specificity (down to the millisecond, for example) then the user will not be properly written to the segment upon upload. | The current time. | 1278250469 |
VALUE |
int | A numeric value you would like to assign to a segment. | 310Note: The maximum accepted value is 2147483647. (If a value above this is included, there may be behavior unpredictability such as the pixel fire not processing. Therefore, the user will not be added to the segment. Other times, it will be processed, however the value set will be much smaller than what was passed.) |
|
MEMBER_ID |
int | This field is required only if you use a SEG_CODE and upload other members' data in addition to your own. |
The member_id. |
958 |
DOMAIN
| Name | Type | Description |
|---|---|---|
DOMAIN |
string | You may optionally specify a domain to associate with this user ID. |
Separators
Read on for definitions of each separator type. Each separator must be different, except for SEPARATOR1 and SEPARATOR3, which may be identical (SEPARATOR2 and SEPARATOR4, cannot be identical). Each separator must be only 1 character in length.
Warning
Disallowed characters
The following characters are not allowed as separators:
[ ] ( ) { } $ \ / | ? * + -
SEPARATOR1
Separates the user ID from the segment list (or SEG block). There may be only one per line. Required.
SEPARATOR2
Separates segments within the segment list. There may be many per line, since multiple segments can be associated with a single UID. Required if there is more than one segment.
SEPARATOR3
Separates fields within each SEG block. If set, it must remain the same for each line of the file (except after SEPARATOR4). Required if there is more than one field within the SEG.
SEPARATOR4
The user will be removed from any segments appearing after this separator. Optional.
SEPARATOR5
The user will be added to the DOMAIN or looked up in the set designated directly after this separator. Optional.
Note
Mobile Device ID Data Fields
In order to pass in device IDs from mobile devices, pass in SEPARATOR5 at the end of a line followed by one of the numbers shown in the table below. Each number corresponds to a different mobile device identification scheme. This table assumes ^ is used as SEPARATOR5:
| Separator and Number | Value |
|---|---|
| ^3 | idfa |
| ^4 | sha1udid |
| ^5 | md5udid |
| ^7 | openudid |
| ^8 | aaid |
| ^9 | windowsadid |
| ^10 | rida |
| ^11 | tifa |
| ^12 | vida |
| ^13 | lgudid |
^6 sha1mac was deprecated as of May 7th, 2019. Do not use.
Examples
The following examples illustrate scenarios derived from real use cases.
Note
The examples below show separator values that may differ from the ones that were set up in your initial batch segment configuration. Contact our Services team, if you wish to update your configuration settings.
Example 1
A client is adding user 12345678900987654321 to segments 10000 and 10001 with an expiration time of 1440 (one day). The client is also removing user 12345678900987654321 from segments 10002 and 10003.
| Field | Value |
|---|---|
UID |
Xandr user ID. |
SEPARATOR1 |
"," |
SEPARATOR2 |
";" |
SEPARATOR3 |
":" |
SEG_FIELD |
[SEG_ID, EXPIRATION] |
12345678900987654321,10000:1440;10001:1440;10002:-1;10003:-1
Example 2
A client is adding user 12345678900987654321 to segments with codes "auto_intender" and "nike_shopper" with the default expiration time. The client is also removing (using SEPARATOR4) user 12345678900987654321 from segments with codes "bicycle_intender" and "newbalance_shopper".
| Field | Value |
|---|---|
UID |
Xandr user ID. |
SEPARATOR1 |
"," |
SEPARATOR2 |
";" |
SEPARATOR4 |
"\t" |
SEG_FIELD |
[SEG_CODE] |
Note
\t refers to the horizontal tab character. It moves the cursor a tab width. The example below is using \t to show where the space will appear.
12345678900987654321,auto_intender;nike_shopper\tbicycle_intender;newbalance_shopper
Example 3
In the example, below, the client is adding user 12345678900987654321 to segments 10000 and 10001 with no expiration (which means the user will expire in the segment after the maximum allowed 180 days), and they are removing the user from segment 10002.
| Field | Value |
|---|---|
UID |
Xandr user ID. |
SEPARATOR1 |
"\t" |
SEPARATOR3 |
"\t" |
SEG_FIELD |
[TIMESTAMP, SEG_ID, VALUE, EXPIRATION] |
Note
\t refers to the horizontal tab character. It moves the cursor a tab width. The example below is using \t to show where the space will appear.
12345678900987654321\t1320689131\t10000\t0\t0
12345678900987654321\t1320689131\t10001\t0\t0
12345678900987654321\t1320689131\t10002\t0\t-1
Example 4
A client is adding user "abcdefg" to segments 10000 and 10001 with an expiration time of 1440 (one day). The client is also adding user "abcdefg" to cross-segments 10002 and 10003.
Tip
This client is set as an XSEG member.
| Field | Value |
|---|---|
UID |
Xandr user ID. |
SEPARATOR1 |
"," |
SEPARATOR2 |
";" |
SEPARATOR3 |
":" |
SEG_FIELD |
[SEG_ID, EXPIRATION] |
uses_external_uids |
true |
abcdefg,10000:1440;10001:1440
abcdefg,10002:1440;10003:1440
Example 5
A client is adding user 12345678900987654321 to segments with code "car_like" and "bike_like" with the default expiration time.
Tip
This client uses SEG_CODE and uploads under different member names.
| Field | Value |
|---|---|
UID |
Xandr user ID. |
SEPARATOR1 |
"," |
SEPARATOR2 |
";" |
SEPARATOR3 |
":" |
SEPARATOR4 |
"\t" |
SEG_FIELD |
[MEMBER_ID, SEG_CODE] |
Note
\t refers to the horizontal tab character. It moves the cursor a tab width.
12345678900987654321,400:car_like;500:bike_like
Example 6
A client is adding mobile user IDFA (ID for Advertisers) AEBE52E7-03EE-455A-B3C4-E57283966239 to segments 10000, 10001, 10002, 10003 for varying amounts of time, via the Batch Segment Service. This method often has low match rates on our platform because even if IDs are successfully submitted to our service, it doesn't mean that the device ID has actually been seen on our platform.
Note
Separator 5 appended which designates the use of mobile identifiers. The value "3", designates Apple's IDFA value—other values can be found above in the Mobile Device ID Data Fields table.
| Field | Value |
|---|---|
IDFA |
Apple ID for Advertisers. |
SEPARATOR1 |
"," |
SEPARATOR2 |
";" |
SEPARATOR3 |
":" |
SEPARATOR4 |
"\t" |
SEPARATOR5 |
"^" |
SEG_FIELD |
[SEG_ID, EXPIRATION] |
Note
\t refers to the horizontal tab character. It moves the cursor a tab width.
AEBE52E7-03EE-455A-B3C4-E57283966239,10000:1440;10001:1440;10002:-1;10003:-1^3