DocumentationAudience ManagerAudience Manager User Guide

Real-Time Outbound Data Transfers real-time-outbound-data-transfers

Last update: Wed Oct 12 2022 00:00:00 GMT+0000 (Coordinated Universal Time)

The outbound real-time data transfer process delivers user data as a series of JSON formatted messages to a destination platform.

Recommendations

To use this method, the destination platform must meet the following requirements:

  • It must provide an endpoint URL that can scale to receive a high volume of messages from Audience Manager;
  • It must accept data in JSON format (Content-type: application/json);
  • It must accept secure HTTPS data transfers. Audience Manager will not send messages through the unsecure HTTP protocol.

Frequency

This data transfer method can send data in near real-time as users qualify for segments. Real-time messages are only delivered while the user is online and actively visible to the Audience Manager Edge network. Optionally, this method can also send batches of offline or onboarded data as frequently as every 24-hours.

Batch Transfers

Both real-time and batch transfers are sent to the same endpoint and use the same message format. When batch transfers are enabled, the destination platform will see a spike in message volume while the batch messages are delivered. Many of the segment qualifications sent through real-time messages will be repeated in the batch messages. Batch transfers will include only the segment qualifications (or un-qualifications) that have changed since the last batch was delivered.

Rate Limits

There are no rate limits set on the throughput of delievered messages. Setting rate limits could lead to data loss.

Required Responses

By default, the recipient server must return the 200 OK code to indicate successful receipt. Other codes will be interpreted as failures. This response is expected within 3000 milliseconds. In response to a failure, Audience Manager will make one retry attempt only.

Parameters

The following table defines the elements in the JSON data file that you send to the destination.

Parameter
Data Type
Description
ProcessTime
DateTime
Time when the request was executed.
User_DPID
Integer

An ID that indicates the type of device IDs contained within the message, in the User.DataPartner_UUID property.

  • Android IDs (GAID): 20914
  • iOS IDs (IDFA): 20915
  • Web/Cookie IDs: varies by destination platform
Client_ID
String
Represents the target account in the destination platform. This ID originates from the destination platform.
AAM_Destination_ID
Integer
The ID of the Audience Manager "destination" object. This ID originates from Audience Manager.
User_count
Integer
Total number of users in the POST request.
Users
Array
An array of user objects. By default, each message will contain between 1 and 10 users, to keep the message size optimal.
User.AAM_UUID
String
The Audience Manager UUID.
User.DataPartner_UUID
String
Destination platform UUID or the global device ID.
User.AAM_Regions
Array
The Audience Manager region ID where we've seen this device. For instance, if the device had some activity in Paris (Europe), the region ID would be 6. See DCS Region IDs, Locations, and Host Names.
Segments
Array
An array of segment objects. For real-time messages, the array contains all of the segments the user belongs to. For batch messages, the array contains only segment changes since the last batch.
Segment.Segment_ID
Integer
The identifier for the segment. In most cases, this is the segment ID generated by Audience Manager (an integer). In some cases, if the destination platform allows, customers can define the segment identifier in the Audience Manager user interface (open text field), which would then reflect in this property.
Segment.Status
Integer

Defines the status of a user in the segment. Accepts the following values:

  • 1: Active (default)
  • 0: Inactive, opted-out, or unsegmented.

Users are unsegmented when they are:

  • Removed from a segment based on the segment rule.
  • Removed from a segment based on the segment's time-to-live interval.
  • Moved to an inactive state if they have not been seen for the last 120-days.
  • Removed due to a privacy change request (i.e. GDPR)

All partner IDs that are synced to an Audience Manager ID will receive the "Status":"0" flag when a user is unsegmented.

Segment.DateTime
DateTime
The time when the user-segment qualification was most recently verified.

Security

You can secure your real-time outbound data transfer process by signing HTTP requests using private keys or by having Audience Manager authenticate through the OAuth 2.0 protocol.

Request

A real-time request can look similar to the following:

{
"ProcessTime": "Wed Jul 27 16:17:42 UTC 2016",
"User_DPID": "12345",
"Client_ID": "74323",
"AAM_Destination_Id": "423",
"User_count": "2",
"Users": [{
   "AAM_UUID": "19393572368547369350319949416899715727",
   "DataPartner_UUID": "4250948725049857",
   "AAM_Regions": ["9"],
   "Segments": [{
            "Segment_ID": "14356",
            "Status": "1",
            "DateTime": "Wed Jul 27 16:17:22 UTC 2016"
         },
         {
            "Segment_ID": "12176",
            "Status": "0",
            "DateTime": "Wed Jul 27 16:17:22 UTC 2016"
         }
      ]
   },
   {
   "AAM_UUID": "0578240750487542456854736923319946899715232",
   "DataPartner_UUID": "848457757347734",
   "AAM_Regions": ["9"],
   "Segments": [{
            "Segment_ID": "10329",
            "Status": "1",
            "DateTime": "Wed Jul 27 16:17:21 UTC 2016"
         },
         {
            "Segment_ID": "23954",
            "Status": "1",
            "DateTime": "Wed Jul 27 16:17:21 UTC 2016"
        }]
    }]
}
recommendation-more-help
de293fbf-b489-49b0-8daa-51ed303af695