Skip to end of metadata
Go to start of metadata

Instant Audience Service

Alpha-Beta Notice

This field or feature is part of functionality currently in either Alpha or Beta phase. It is therefore subject to change.

The Instant Audience Service is a server-side method that uses a streaming architecture to add individual or small groups of users to segments, via Xandr's API. Rather than aggregating and periodically sending large batches of data using the Batch Segment Service, the Instant Audience Service associates users to segments in close to real-time. Our target SLA for adding users to segments with this service is 2 minutes. This is useful if you have real-time audience remodeling requirements.

On This Page

Configure the Service

If you're already using the Batch Segment Service, you can skip this part and proceed to Authenticate. If you're a brand new client and wish to start using the Instant Audience Service, you will need to open a ticket with  and provide the following information:

  1. Are you using external user IDs (i.e. you use mapUID to store the mapping with Xandr)? If you use another member's external user IDs, include their member_id as well.
  2. Do you need to populate segments belonging to other members? If so, provide the associated member_ids.
  3. When you would like your segments to expire by default (e.g. never expire, expire 60 days from now, etc.)? Note that if you include EXPIRATION in your seg block, your default expiration will not be used.
  4. The following questions are for our internal capacity planning:
    • What is the number of unique user IDs per post?
    • What is the number of expected posts per day?
    • What is the number of unique segments per post?

Authenticate

Refer to the  Authentication Service  for a general overview on how to make calls to the Xandr API. Just like any other service, you'll authenticate against https://api.appnexus.com. However, subsequent calls will be made to the Instant Audience Service at https://streaming-data.appnexus.com

In the authentication response, make note of the token as it will be needed for subsequent calls to the Instant Audience Service.

Example response from the Authentication Service:

The token returned in the response must be included in subsequent calls to the Instant Audience Service in the authorization header, or as an access_token query string parameter as shown in the following examples.:

Authorization header

Query string

Adding/Removing Users from Segments

After authenticating, you're now ready to add/remove a user to/from a segment, via a JSON file.

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 add/remove to/from segments. For details on creating segment values, see "Segment Pixels: Advanced" and "Segment Targeting" in the UI documentation.

The following example demonstrates how to assign a user to two segments. In this example, the member is adding user ID 12345678900987654321 (this is a Xandr user id) to segments 10001 and 10002, setting both associations with value = 1 and expiration within 1440 minutes.

API Call
JSON Payload
Response

JSON Fields

 

Field

Type

Description

Default

Required
rt_segment array

user_id

string

This would either be the Xandr user_id or an id based on the domain, such as "AEBE52E7-03EE-455A-B3C4-E57283966239", as an example of a device identifier.

N/AAt least one
seg_block
arrayArray of segment blocks for segments to associate with the user (see segment block structure below).N/AAt least one
domain              
string

Type of identifier being used in the request, such as an Xandr user ID (represented with null) , external user ID , or device identifier (“idfa”, “sh1udid”, “md5udid”, “openudid”, and “aaid") .

sha1mac was deprecated as of May 7th, 2019. Do not use.

nullNo
seg_block array
 
 
 
 
seg_id
intThe Xandr segment IDN/AIf not using seg_code and member_id to identify segment
seg_code
string

A user-defined name for the segment.

You may either include SEG_CODE  and member_id or SEG_ID, but not both.

N/AIf not using seg_ID to identify segment
value
intA numeric value you would like to assign to a segment.0No
expiration
intThe lifetime of the user-segment association in minutes, starting from when we read it. A value of 0 means that the segment will never expire; -1 means that the user will be removed from this segment.0No
member_id
intThe member ID of the segment owner for the seg_block.nullIf using seg_code
Response
status
stringDescribes whether the add/remove went through or resulted in an ereor  
users_in_request
int

The number of users read in the request.

This will simply show the number of users initially detected in the request regardless of whether they are valid.

  
segments_in_request
int

The number of segments read in the request. 

This will simply show the number of segments initially detected in the request regardless of whether they are valid in our system and without regard to what users they are being associated with in the call.

  

Additional POST Scenarios

 1. Using device ID (IDFA)
REST API call
JSON Payload
Response
 2. Using codes for other members
REST API call
JSON Payload
Response

Service Limits

Service limits may change during alpha and beta testing of this service.

In order to adhere to a maximum of 2 minutes activation time, the Instant Audience Service currently has the following limits:

Call Rate
  • Up to 100 POST calls per second (per member) and up to 1000 GET calls per second (per member). If you exceed this rate limit, the following message will be returned: "Rate limit exceeded. You have exceeded your request limit of 1000 reads per 1 seconds to rt-segment-processed, please wait and try again or contact Xandr for higher limits "
Objects
  • Up to 1000 users per second
  • Up to 100 segments per user per call
Payload Size
  • The JSON payload should not exceed 1MB

Example Error Scenarios

 1. Adding/removing over 1000 users in a request
API Call
JSON Payload
Reponse
 2. seg_id or seg_code and member_id are not provided
JSON Payload
Response
 3. seg_block not provided
JSON Payload
Response
 4. user_id is empty
JSON Payload
Response

Related Topics