Real-Time Outbound Data Transfers

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"
        }]
    }]
}