Edit

Share via

Digital Platform API - 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

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 Example
SEG_ID int The Xandr segment ID.
Default: 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.

Default: 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.
Default: The current time.		 1278250469
VALUE int A numeric value you would like to assign to a segment. 310

Note:
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.
Default: 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.

Caution

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

^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]

Warning

\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, separator5 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
  • Last updated on