Instant Audience Service
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 the AppNexus 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.
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 support.appnexus.com and provide the following information:
- Are you using external user IDs (i.e. you use mapUID to store the mapping in AppNexus)? If you use another member's external user IDs, include their
- Do you need to populate segments belonging to other members? If so, provide the associated
- 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.
- 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?
Refer to the Authentication Service for a general overview on how to make calls to the AppNexus 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.:
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.
The following example demonstrate how to assign a user to two segments. In this example, the member is adding user ID 12345678900987654321 (this is an AppNexus user id) to segments 10001 and 10002, setting both associations with value = 1 and expiration within 1440 minutes.
This would either be the AppNexus
|N/A||At least one|
|array||Array of segment blocks for segments to associate with the user (see segment block structure below).||N/A||At least one|
Type of identifier being used in the request, such as an AppNexus user ID (represented with
sha1mac was deprecated as of May 7th, 2019. Do not use.
|int||The AppNexus segment ID||N/A||If not using |
A user-defined name for the segment.
You may either include
|N/A||If not using |
|int||A numeric value you would like to assign to a segment.||0||No|
|int||The lifetime of the user-segment association in minutes, starting from when we read it. A value of ||0||No|
|int||The member ID of the segment owner for the seg_block.||null||If using |
|string||Describes whether the add/remove went through or resulted in an ereor|
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.
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
|REST API call|
|REST API call|
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:
Example Error Scenarios