Skip to end of metadata
Go to start of metadata

Segment Service

The Segment Service lets you create segment IDs, which are then used to create segment pixels for placement on inventory pages. If you are working with third-party data providers through the AppNexus platform, it will also show you a list of segments for those providers.

  • Segments are associated with members, and can optionally be associated with a particular advertiser.
  • All segment data will be stored in the server-side cookie store and passed to the bidder associated with the owning member on every bid request.
  • An advertiser association is for reference and use in our Console user interface.

The shared "birthday cookie" segment has an ID of 1 and is available to all platform members. For more information, see AppNexus Birthday Cookies (Customer login required).

Once you have a segment ID, the basic format of a segment pixel is <img src="http://ib.adnxs.com/seg?add=123" width="1" height="1"/>, where 123 is the segment ID. For more information about segment pixels, see Working with Segments (Customer login required).

Be sure to wait approximately 20 minutes before trying to add users to any newly created segments (to allow these segments to be propagated to all servers in our cloud). In addition, as a best practice, try to minimize the creation of new segments, re-use existing segments where possible or use segment "values" to further sub-divide users within existing segments. These practices will ensure successful user uploads to segments. For details on creating segment "values", see Segment Pixels Advanced and Segment Targeting.

On This Page

REST API

Add a new segment:

Add a new advertiser segment:

Modify an existing segment:

Modify an existing advertiser segment:

To change a segment from advertiser-owned to network-owned, make a PUT call, passing the segment ID and member ID in the query string and setting advertiser_id to null in the JSON file. See this example for a demonstration.

View all segments:

View multiple segments by ID using a comma-separated list:

View a particular segment:

Search for segments with IDs, short names, or codes containing certain characters:

Delete an existing segment:

JSON Fields

Field

Type

Description

Default

Required On

id

int

The AppNexus ID assigned by the API to reference the segment. When switching a segment from advertiser-owned to network-owned, you must pass this information in the querystring.

 

PUT, in querystring

code

string(50)

The user-defined code for calling the segment. For more information, see Working with Segments (Customer login required).

  

state

enum

The state of the segment. This determines whether the segment can be used. Possible values: active or inactive.

active

 

short_name

string(255)

The short name used to describe the segment.

  

description

string

The optional description for this segment.

  

member_id

int

The ID of the member that owns this segment.

When switching a segment from advertiser-owned to network-owned, you must pass this information in the query string. See this example for more details.

  

category

string

Deprecated. This field is read-only.  

price

double

The flat CPM price of the segment - only applicable if the segment will be sold to other members.

0

 

expire_minutes

int

The number of minutes the user is kept in the segment. If you want to keep the user in the segment for retargeting purposes, set to the desired number of minutes (or null for system maximum value 180 days). If you want to add the user to the segment only for the duration of the ad call, set to 0. Changing this value does not retroactively affect users already in the segment. Also, if a user is re-added, the expiration window resets.

To keep users in the segment for the 180 day maximum, set this to null.

  

enable_rm_piggyback

boolean

If true, piggybacking RM pixels is enabled.

  

max_usersync_pixels

int

The maximum number of third-party user sync pixels to piggyback onto the segment pixel. Set to 0 to block all third-party user sync pixels. If blank (null), the segment will usersync with multiple other providers.

  

last_modified

timestamp

The date and time when the segment was last modified.

  

provider

string

Not yet supported.

null

 

advertiser_id

int

The ID of the advertiser using the segment if the segment should be on the Advertiser level rather than the Network level. If null, the segment will be usable by all advertisers for that member. This information is for reference in Console.

null

 

piggyback_pixels

array

The URLs of the pixels you want us to fire when the segment pixel fires. See Piggyback Pixels below for more details.

  

parent_segment_id

int

The ID of the parent segment. If the parent segment is targeted in a profile, the direct child segments are targeted as well.

The parent-child logic extends only one level deep. Example: Segment A is the parent of segment B and segment C, and segment C is the parent of segment D. When segment A is targeted, segment B and segment C are targeted as well, but segment D is not.

  

querystring_mapping

object

A query string that allows you to assign a set of parameters and values to a segment. See About Query Strings for a general description of query strings and Query String Mapping for more details.

Invalid if a querystring_mapping_key_value object is also included.

  
querystring_mapping_key_valueobject

A query string that allows you to reuse a key and assign a single key-value pair to a segment. See About Query Strings for a general description of query strings and Query String Mapping Key Value for more details.

Invalid if a querystring_mapping object is also included.

  

Piggyback Pixels

When adding piggyback pixels, please keep the following in mind:

  • Image pixels can only piggyback off other other image pixels, and JavaScript pixels can only piggyback other JavaScript pixels.
  • Image pixels can only have one piggyback pixel. If you need to piggyback multiple pixels, be sure to use a JavaScript pixel.
  • There are no character limits to piggybacked pixels in AppNexus, but browser/server URL limits may apply.

Each object in the piggyback_pixels array contains the following fields.

Field

Type

Description

url

string

The URL of the pixel to piggyback.

pixel_type

enum

The type of pixel to piggyback. Possible values: "js" or "img".

About Query Strings

AppNexus provides two methods of query string mapping to allow publishers to pass inventory-specific or user-specific information in the query strings of their placement tags: query string mapping, in which a set of parameter values assigned to the segment; and query string mapping key value, which allows you to assign one key/value pair to a segment and then reuse the same key with a different value in another segment.

For both types of mapped query strings:

  • Whenever an ad call is made with a mapped query string, the associated user will automatically be added to the segment.
  • You can target the query string in a campaign (via the segment_targets or segment_group_targets fields of the Profile Service).

Note that you can choose how long the user will be kept in the segment. If you want to keep the user in the segment for retargeting purposes, set expire_minutes to the correct number of minutes (null will set to system maximum value 180 days). If you want to add the user to the segment only for the duration of the ad call, set expire_minutes to 0.

See Examples below for various scenarios and formatting.

Query String Mapping

Query string mapping allows you to assign a parameter to a segment using the querystring_mapping field. Multiple values can be added to a parameter. This method is useful in cases where only one value makes sense for a user: for example, a user's age, salary range, or experience. If a user is in the beginner segment but later gains more experience, the user can be moved to the advanced segment and is automatically removed from the beginner segment. See this example for more details.

In this type of query string, the parameter can be provided with no values. For example, {"param": "car_model", "value_type": "none"}. This allows any value for that parameter to be provided.

Field

Type

Description

param

string

The query string parameter.

value_type

enum

The type of value accompanying the parameter. Possible values: "text", "numeric", or "none".

values

array

The strings that can accompany the parameter when value_type is "text". If value_type is "numeric" or "none", this field cannot be used.

Need the Value IDs?

If you need the IDs of the values, pass the query string parameters show_querystring_ids=true, and values will instead be an array of objects with the keys "value" (string) and "id" (int).

allow_empty_text

Boolean

When true, the values array may be null. May only be used when the value_type is "text". Defaults to false.

publishers

array

The publishers from which you expect the query string. Users associated with these publishers' placements will be added to the segment.

sites

array

The placement groups (sites) from which you expect the query string. Users associated with these placements will be added to the segment. Note that this field overrides publishers; if you specify a site that doesn't belong to one of the specified publishers, users associated with the placements in a placement group will nonetheless be added to the segment.

placements

array

The placements in which you expect the query string. Users associated with these placements will be added to the segment. Note that this field overrides placement groups and publishers. That is, if you specify a placement that doesn't belong to one of the specified placement groups or publishers, users associated with the placement will still be added to the segment.

include_shared
BooleanSet this value to false to avoid retrieving shared segments.

Query String Mapping Key Value

Query string key/value mapping allows you to assign a single key-value pair to a segment using the querystring_mapping_key_value object. This type of query string allows a user to exist in multiple segments and is useful in cases where more than one value for a parameter makes sense: for example, a user's musical preferences. If a user is in the rock segment but also likes funk, he or she can exist in both segments simultaneously. See the key-value mapping example for more details.

In this type of query string, each qs_key must have at least one corresponding qs_value.

Field

Type

Description

qs_key

string

The query string parameter.

qs_value

string

A value for the query string key. The value can be empty or null. Multiple values can be added using the same key. A qs_value must be provided if a qs_key is used.

Examples

Create a segment
View a segment
Change a segment from advertiser-owned to network-owned
Add text query string mapping to a segment
Add numeric query string mapping to a segment
Add query string mapping without values to a segment
Use query string key-value mapping to reuse a key with multiple values