Skip to end of metadata
Go to start of metadata

Splits Service

This offering is a beta feature that is subject to change. For more information about future developments, reach out to your AppNexus representative.

The Splits Service creates and modifies programmable splits for augmented line items. When you create a line item, you specify the inventory you'd like to target, the budget you'd like to spend over the flight, how you want to track revenue, and how to use AppNexus optimization. Programmable splits can further target subsets of that total inventory, allocate the specified budget to different targets, set bidding criteria, and distribute creatives. The targeting on the line item acts as a filter; impressions must match the criteria specified by the line item before they'll be passed on to splits. For more information on how splits work, see Understanding Splits (login required).

The Splits Service allows you to specify:

  • Targeting conditions
  • Bidding rules
  • Budget allocation
  • Which creatives are associated with a split

Using splits with custom models is not currently supported. You will receive an error if you attempt to create or modify splits on a line item that has a custom model attached.


On This Page

REST API

The Splits service works a little differently from most other AppNexus API services. By default, the budget-splitter (Splits) service creates or modifies all the splits on the line item at the same time instead of creating or modifying a single split. Rather than creating a single split, the service creates a budget-splitter object (an array) that is associated with the line item. The budget-splitter array contains two or more splits, and must meet the following requirements:

  • The sum of the budget allocation for all splits on a line item must always equal 100. This ensures that all impressions for a line item are accounted for by at least one split.
  • Each split must be assigned a priority, which determines the split to which an incoming impression will be assigned if the impression meets the targeting requirements for more than one split. The same priority cannot be used for more than one split.
  • One split must be defined as the default split. This is the fallback split to which impressions will be assigned if they don't meet the conditions of any of the other splits. The default split is referred to as the "Line Item Remainder" in the UI.
  • The default split must be named "Default" or "default" and appear as the last split listed in the budget-splitter array. It cannot be assigned any conditions or assigned a capped (constrained) allocation strategy, because it is meant as a fallback in case other conditions don't apply. You can, however, allocate 0% of your budget to the default split, which means it will never serve.
  • The default split may only have a bid modifier of "1" or null.
  • The default split must be assigned an order, but no matter what order it is assigned, it will be prioritized last.

The POST method is not supported for the Split service.

To modify an individual split, you must use the PATCH method as described in the examples below.

You cannot use the PATCH method to modify split allocation. Because the sum of the budget allocation for all splits on a line item must equal 100, it is not valid to change the allocation on one split without changing the allocation on at least one other split.

Unlike other AppNexus API services, the JSON for the budget-splitters array does not appear inside a wrapper named after the object. It appears simply as an unnamed array. For example, this is the JSON file to create a budget-splitters array with three splits:

Example budget-splitter object

Add splits to a line item which has none:

View all splits for a line item:

Update all splits for a line item:

Delete all splits from a line item:

This will delete all splits from the line item permanently. The information for past splits traffic will still appear in reporting.

Modify a single split:

JSON Fields

Field

Type

Description

Default

Required On

id

int

The ID of the split.

Example:

Auto-generated number

PUT/PATCH/ DELETE, in JSON

namestring

The name you assign the split.

Example:

The default split must be named "Default" or "default".

  
is_defaultboolean

Specifies whether this is the default split, which is used when an impression does not meet the targeting requirements for any other splits. Every line item must have one and only one default split. The default split must be named "Default" or "default" and cannot have any conditions. Possible values are "true" and "false".

Example:

  
conditionsarray

The targeting conditions for the split. A condition is specified by an array containing a field, an operator, and a value.

Example:

See Conditions below for more information.

  
activeboolean

Specifies the status of a split. Possible values are "true" or "false".

Example:

  
orderint

The priority of this split in the budget_splitters array. (In the UI, this field is referred to as "Priority".)

If an impression meets the targeting requirements for multiple splits, the priority determines the split to which the impression will be assigned. For example, suppose that Split A (priority 1) is targeting "domain=cnn.com" and Split B (priority 2) is targeting "city=Boston", and an impression is available from a user in Boston visiting cnn.com. The impression will be assigned to Split A because it has a higher priority than Split B.

You cannot set the same priority for multiple splits.

The order can start at any value, so long as the values are sequential. For example, the order for three splits can be 0, 1, 2 or 4, 5, 6.

Example:

  
allocation_percentint

The percentage of the line item budget assigned to this split. The allocation for each split should be between 0 and 100. The sum of the allocation percentages for all splits in a line item must equal 100.

Example:

  
allocation_strategyenum

Specifies how to handle conflicts between the split allocation goal and the line item delivery goal. Possible values are:

  • "unconstrained" - Line item delivery is prioritized over allocation. When a line item with uncapped splits is underdelivering, the uncapped splits are permitted to exceed the allocation goal to reach the line item delivery goal. In the UI, this state is called "uncapped".
  • "constrained" - Allocation is prioritized over delivery. Even when line items are underdelivering, capped splits are not permitted to exceed the allocation goal to help the line item reach its delivery goal. This will prevent overspend on a split, but may cause the line item to underdeliver. In the UI, this state is called "capped".

For more information, see Understanding Splits (login required).

Example:

"unconstrained" 
bid_modifierfloat

The number used to modify the bid for this split. A bid modifier can only be applied to a split when the line item's booked revenue type is CPM and optimization is not enabled. The value of the bid modifier will be multiplied by the CPM booked revenue to serve as the maximum CPM that the split can bid.

Example:

The default split may only have a bid modifier of "1" or null. Inactive splits must be assigned a bid modifier of "0".

  
expected_valuefloat

The expected value of the impression for this split. An expected value must be included for each split when the line item's booked revenue type is cost plus or dCPM and optimization is not enabled. The expected value serves as the maximum CPM that the split can bid.

Example:

  
creativesarray of ints

Optional. The IDs of the creatives to be served on this split.

Example:

  
creative_macrosarray of strings

Optional. Any creative macros that are added to the served creative.

For more information, see Working with Creatives (login required) and Creative Macro Check Service.

  

Conditions

A condition is specified by an array containing a field, an operator, and a value.  For example, to create a condition that targets impressions from the United States, the condition is:

Country

Evaluate impressions based on the user's country.

Fieldcountry
Operator=, in, not_in
Value

Country ID or code, such as 233 or "US"

Use the Country Service to retrieve these IDs or codes.

Region

Evaluate impressions based on the user's geographic region.

Fieldregion
Operator=, in, not_in
Value

Region ID or country/region code combination, such as "US:NY" .

Use the Region Service to retrieve these IDs and codes.

City

Evaluate impressions based on the user's city.

Fieldcity
Operator=, in, not_in
Value

City ID or country/region/city code combination, such as "US:NY:New York" .

Use the City Service to retrieve these IDs and codes.

DMA

Evaluate impressions based on the user's DMA (designated market area).

Fielddma
Operator=, in, not_in
Value

DMA ID, such as 602 (for Chicago metro area).

Use the City Service to retrieve DMA IDs.

Postal Code

Evaluate impressions based on the user's postal code. Postal code is available only for some mobile impressions and impressions from external supply partners .

Fieldpostal_code
Operator=, in, not_in
Value

Postal code ID (an integer) or country/postal code combination (a string such as "CA:J0K 1B0" or "US:10010"). Includes US zip codes.

Use the Postal Code Service (documented in the Profile Service) to retrieve postal code IDs.

Size

Evaluate impressions based on placement size. Please note that in case promo_sizes are passed in the ad call, the evaluation will be performed using the primary size only.

Fieldsize
Operator=, in, not_in
Value

String representing placement dimensions, formatted as "WIDTHxHEIGHT".

Domain

Evaluate impressions based on domain.

Fielddomain
Operator=, in, not_in
Value

String representing a top-level domain name, such as "food.com" or "books" .

Mobile App

Evaluate impressions based on specific mobile apps.

Fieldmobile_app_bundle
Operator=, in, not_in
Value

Mobile app ID or names.

Use Mobile App Service to retrieve these IDs or names.

Placement

Evaluate impressions based on specific placements.

Fieldplacement
Operator=, in, not_in
Value

Placement ID.

Placement ID is listed as tag_id in log-level data.

Publisher

Evaluate impressions based on specific publishers.

Fieldpublisher
Operator=, in, not_in
Value

Publisher ID.

Publisher ID is listed as publisher_id in log-level data.

Seller Member

Evaluate impressions based on specific seller members.

Fieldseller_member_id
Operator=, in, not_in
Value

Member ID of the seller.

Deal ID

Target deal inventory.

Fielddeal_id
Operator=, in, not_in
Value

Deal ID.

Operating System Family

Evaluate impressions based on the user's operating system.

Field os_family
Operator=, in, not_in
Value

Operating System Family ID or name, such as 2 or "Android" .

Use the Operating System Family Service to retrieve these IDs and names.

Operating System Version

Evaluate impressions based on the specific version of the user's operating system.

Fieldos_extended
Operator=, in, not_in
Value

Operating System Extended ID, such as 81 for "10.8 Mountain Lion" .

Use the Operating System Extended Service to retrieve these IDs.

Operating system ID is listed as operating_system in log-level data.

Browser

Evaluate impressions based on the user's browser.

Fieldbrowser
Operator=, in, not_in
Value

Browser ID or name, such as 8 or "Chrome (all versions)" .

Use the Browser Service to retrieve these IDs and names.

Browser Language

Evaluate impressions based on the browser language.

Fieldlanguage
Operator=, in, not_in
Value

Language ID.

Use the Language Service to retrieve these IDs.

Device Type

Evaluate impressions based on specific types of physical devices.

Fielddevice_type
Operator=, in, not_in
Value

Device type name. Possible values:

  • "pc & other devices" - Use this value to target desktops and laptops.
  • "phone" - Use this value to target mobile phones.
  • "tablet"- Use this value to target mobile tablets.

Device Model

Evaluate impressions based on specific models of physical devices.

Fielddevice_model
Operator=, in, not_in
Value

Device model ID.

Use the Device Model Service to retrieve these IDs.

Device model ID is listed as device_id in log-level data.

Carrier

Evaluate impressions based on specific mobile carriers.

Fieldcarrier
Operator=, in, not_in
Value

Mobile carrier ID or name, such as 14 or "Verizon" .

Use the Carrier Service to retrieve these IDs and names.

Predicted IAB Viewability Rate

(Previously known as "Estimated IAB Viewability Rate".) Evaluate web display impressions by how likely they are to be measured as viewable by the IAB standard, as determined by AppNexus optimization (customer login required).

Fieldpredicted_iab_view_rate

Operator

<, <=, =, >, >=                       
ValueDecimal number between 0 and 1, representing a percentage.

Predicted IAB Video Viewability Rate

Evaluate web video impressions by how likely they are to be measured as viewable by the IAB standard, as determined by AppNexus optimization (customer login required).

Field predicted_iab_video_view_rate
Operator

<, <=, =, >, >=  

ValueDecimal number between 0 and 1, representing a percentage.

Predicted Video Completion Rate

Evaluate web video impressions by how likely they are to be completed, as determined by AppNexus optimization (customer login required).

Field

estimated_video_completion_rate

Operator

<, <=, =, >, >=  

ValueDecimal number between 0 and 1, representing a percentage. 0 represents non-video inventory.

Creative

The creatives to serve on this split.

Field

creative

Operator

in

Value

List of creative IDs.

Use the Creative Service to retrieve these IDs.

Segment

Evaluate impressions based on the presence, absence, value, or segment age of the user in a first-party or third-party segment.

Field

segment[SEGMENTID,...]

where SEGMENTID is an optional list of segment IDs.

Use Segment Service to retrieve segment IDs.

Operator

<, <=, =, >, >=, present, absent

Value

A nested conditions array that specifies segment age, value, or presence.
 

  • Segment presence is "present" or "absent".
  • Segment age is measured in minutes and must be a positive integer.
  • Segment value is a non-zero, positive integer representing a user-defined value.


Segment values may be passed in a number of ways, for example, through the Batch Segment Service or a first-party or third-party segment query string. For more information on passing values through segment query strings, see Segment Pixels Advanced (customer login required).

Daily Frequency

The number of ads seen by a user for an advertiser, line item, or split on the current day.

Field

OBJECT[ID].day_frequency

where the object is advertiser, line_item, or campaign (representing split), and ID is the object ID. Use the Advertiser Service, Line Item Service, or Splits Service to retrieve IDs.

Operator

>, =>, <, =<, =

Although the operator = is supported for frequency and recency, we strongly recommend that you do not use it, as it tends to cause underdelivery. This is because when you target an impression with frequency=5, you exclude impressions with frequencies equal to 0, 1, 2, 3, or 4.
ValuePositive integer. 0 indicates no frequency information is available (the user has not seen this object on the current day).

Lifetime Frequency

The number of ads seen by a user over the lifetime of an advertiser, line item, or split.

Field

OBJECT[ID].lifetime_frequency

where the object is advertiser, line_item, or campaign (representing split), and ID is the object ID. Use the Advertiser Service, Line Item Service, or Splits Service to retrieve IDs.

Although the operator = is supported for frequency and recency, we strongly recommend that you do not use it, as it tends to cause underdelivery. This is because when you target an impression with frequency=5, you exclude impressions with frequencies equal to 0, 1, 2, 3, or 4.


Operator>, =>, <, =<, =
ValuePositive integer. 0 indicates no frequency information is available (the user has never seen this object).

Recency 

The number of minutes since a user has seen an ad. This can be determined for a user for all ads under an advertiser, line item, or split.

Field

OBJECT[ID].recency

where the object is advertiser, line_item, or campaign (representing split), and ID is the object ID. Use the Advertiser Service, Line Item Service, or Splits Service to retrieve IDs.

Operator

>, =>, <, =<, =

Although the operator = is supported for frequency and recency, we strongly recommend that you do not use it, as it tends to cause underdelivery. This is because when you target an impression with frequency=5, you exclude impressions with frequencies equal to 0, 1, 2, 3, or 4.
ValueA positive integer indicating the number of minutes since a user has seen an impression, rounded down. 59 seconds will evaluate to 0, 61 seconds will evaluate to 1. 0 means the impression was seen very recently. Null means no recency data is available (the user has not seen this impression before).

Examples

Create splits for a line item with cost-plus booked revenue and optimization disabled
Create splits for a line item with cost-plus booked revenue and optimization enabled
Create splits for a line item with CPM booked revenue and optimization disabled
Update one split on a line item

Related Topics

  • No labels