Digital Platform API - Legacy BSS file format

發行項
02/13/2024

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

共用方式為

Digital Platform API - Legacy BSS file format

Format overview

UID

`SEG` block

`SEG_FIELD` block

`DOMAIN`

Separators

SEPARATOR1

SEPARATOR2

SEPARATOR3

SEPARATOR4

SEPARATOR5

Examples

Example 1

Example 2

Example 3

Example 4

Example 5

Example 6

其他資源

共用方式為

Digital Platform API - Legacy BSS file format

Format overview

UID

SEG block

SEG_FIELD block

DOMAIN

Separators

SEPARATOR1

SEPARATOR2

SEPARATOR3

SEPARATOR4

SEPARATOR5

Examples

Example 1

Example 2

Example 3

Example 4

Example 5

Example 6

其他資源

`SEG` block

`SEG_FIELD` block

`DOMAIN`