Getting data in Audience Manager using DCS API calls

[#1]

If you are working with Adobe Audience Manager, you have come across this challenge: you want to target your visitors instantly, as soon as they visit your website/app. This is achievable when you make users qualify based upon their real time activity on the site/app. But, if you have offline data available to be onboarded, then AAM system takes some time to process data (onboarded traits method). The way AAM processes on-boarded data is as follows:

• You upload your CRM data to AAM, either to an SFTP location or an S3 bucket.
• Every 12h, AAM reads all on-boarded data and processes it, converting the signals into traits.
• The traits are stored in the core servers.
• A visitor logs in for the first time.
• Since the communication between the browser and AAM is done through the edge servers, these servers have at this moment in time no on-boarded information for that visitor.
• The edge servers where this visitor activity has happened, request the on-boarded traits to the core servers.
• In a batch process, core servers send to the edge server the visitor’s on-boarded information.

This whole process can take 24h, and also the visitor needs to come back again after this period, in order to be targeted on site using the on-boarded information.

Real-Time Data Transfers with the DCS API

Fortunately, AAM has a solution for that: Send the data directly to the edge servers through the DCS API.

Let's see the steps that are involved in getting data into AAM with this approach:

Step 1: Create rule-based trait:

Depending upon the offline data that you already have available, you can create rule-based traits for that data.

For Example, consider that you already have list of customers in your CRM/Database that have placed an order for android device from your ecommerce site. If you want to push these details to your instance of AAM, you can create rule-based trait(s) for this.

Create a rule-based trait in AAM using a key value pair like: “c_product_purchased” contains “android”

When we are calling DCS APIs, an HTTP call is being made to Adobe Audience Manager. This HTTP call contains two important pieces of information:

• the Audience Manager user id
• the data signals (“c_product_purchased” = “android”) //assignment

https://subdomain.demdex.net/event?c_product_purchased=android

When we make the above call, it will realize the device or customer id for the rule-based trait at real time.

What is an Audience Manager ID?

The AAM ID is NOT a cross device id. Therefore, if the user has 3 devices, it will have (at least) 3 AAM IDs. The AAM ID is stored in a third-party cookie. If you happen to have and use two browsers on your device, these will not share the cookie storage. As such, we will get two distinct Audience Manager IDs, one for each browser.

What happens on mobile apps, where we don't have cookies?

The mobile apps using the AAM SDK, will store the Audience Manager ID in the app's internal storage. Multiple apps installed on the same device, will have different AAM ids.

How do we obtain an AAM id?

In our case we are dealing taking an example of an ecommerce website. The website is integrated with the VisitorID.js library, maintained by the Adobe Audience Manager system. This javascript library takes care of generating an Audience Manager ID, when none is available. It does so by triggering a call from the browser to the Visitor ID service.

Step 2: Generating Device IDs using DCS API (if in case you don’t have list of Device IDs):

Emulate the Visitor ID call to Audience Manager, which the VisitorID.js library is making from the browser.

Open the Terminal, then copy paste this HTTP call command and press enter:

curl "http://<subdomain>.demdex.net/id?d_visid_ver=3.3.0&d_rtbd=json&d_ver=2&d_orgid=yourCompanyMCOrgID%40AdobeOrg"

HTTP parameters sent:

Name	Description
d_visid_ver=3.3.0	The VisitorID.js library version
d_rtbd=json	This parameter instructs AAM to return a json response
d_orgid=	Represents the IMS organization id, which uniquely identifies the Audience Manager client which is making the call (eg. PopularRetailer)

Notice that the HTTP API contains <subdomain>.demdex.net, which is the Audience Manager's company sub domain.

The formatted Visitor ID json response will look like this:

{

"d_mid":"88819962471507989271280036438453367558",

"id_sync_ttl":604800,

"d_blob":"cIBAx_aQzFEHcPoEv0GwcQ",

"dcs_region":7,

"d_ottl":7200,

"ibs":[

{

"id":"411",

"ttl":10080,

"tag":"img",

"fireURLSync":1,

"syncOnPage":1,

"url":[

"//cm.everesttech.net/cm/dd?d_uuid=89334862240161643561259517779946724685"

]

}

   ],

"subdomain":"<subdomain>"

}

Notice the d_mid parameter, which represents the Experience Cloud ID. The MID can be decoded by Audience Manager to obtain an AAM ID.

We have an AAM ID. How do we send the data?

In our situation, we want to notify Audience Manager that the current visitor has ordered an android device in the past from ecommerce store. We do this by making a data collection HTTP call to Audience Manager with device ID and rule based trait’s signal, as explained in next step.

Step 3: Send real time data to Audience Manager:

Open up the Terminal. Then copy paste this HTTP call command and press enter:

curl -v "https://<subdomain>.demdex.net/event?d_mid=88819962471507989271280036438453367558&d_orgid=YourComp anyMCOrgID%40AdobeOrg&d_rtbd=json&d_full=1&c_product_purchased =android"

HTTP parameters sent:

Name	Description
c_product_purchased=android	The signal sent to AAM. This notifies AAM that the visitor has ordered android device from ecommerce site. We have already created a trait, whose rule states that c_product_purchased contains "android". Because of this we will qualify this device for the Product Purchased Android trait.
d_rtbd=json	This parameter instructs AAM to return a json response
d_orgid=...	Represents the IMS organization id, which uniquely identifies the Audience Manager client which is making the call. This is Experience Cloud Organization account specific.
d_mid=...	Represents the Experience Cloud ID. Audience Manager will decode this id and will obtain an AAM ID. The resulting trait will be stored keyed of this device id. (Ultimately MID gets generated from AAM UUID)

The formatted json response will look like this:

{"stuff":[{"cn":"aam_aa","cv":"aamaa=12080591|aamaa=10209650","ttl":30,"dmn":""},{"cn":"co okie_destination","cv":"a=10209650","ttl":30,"dmn":""}],"uuid":"21700556125849053274229415 398555317701","dcs_region":3,"tid":"qvbE0F3iQ9w=","data_collection":{"request_ids":[{"name space":4,"id":"22159308628525867984209987767182328452","type":"INTERNAL"}],"primary_device _id":{"id":"21700556125849053274229415398555317701","type":"INTERNAL"},"device_metadata":{ "is_robot":"1"},"request_target_url":"/event","request_method":"GET","request_headers":[{" key":"X-Forwarded-For","value":"xx.xx.xx.xx"}],"request_params":[{"key":"d_mid","value":"2 2159308628525867984209987767182328452"},{"key":"d_full","value":"1"},{"key":"c_evar1","val ue":"2"},{"key":"d_orgid","value":"YourCompanyMCOrgID@AdobeOrg"},{"key":"d_rtbd","value":" json"}],"request_is_secure":true,"request_user_agent":"curl/7.55.1"}}* Connection #0 to host subdomain.demdex.net left intact

When checking the UUID in the Visitor Profile Viewer tool in AAM UI, you will see the trait and segment qualification for which we passed signal.

In the previous HTTP calls made to Audience Manager, we noticed the marketing cloud identifier was being sent to Audience Manager (the `d_mid` parameter). It turns out we can actually send multiple identifiers to AAM in a single HTTP call: - device identifiers (Marketing Cloud IDs / AAM IDs) - cross-device ids (eg. CRM id) - mobile ids (eg. Apple's IDFA or Google's Advertising Id)

How can we send Customer ID/CRM ID via DCS APIs?

Whenever a user authenticates, we get access to the authenticated id (the customer id): labuser20. Since this same customer id can be used to authenticate from multiple devices, we call it a cross-device id.

Step 4: Sending customer ID with signals using DCS API

In this step, we will be syncing Device ID with Customer ID. You can also send only the Customer ID with some data (signals) for a cross device data source.

Open up the Terminal. Then copy paste this HTTP call command and press enter:

curl -v "https://<subdomain>.demdex.net/event?d_mid=88819962471507989271280036438453367558&d_orgid=YourComp anyMCOrgID%40AdobeOrg&d_rtbd=json&d_full=1&d_cid=231731%01labuser20"

HTTP parameters sent:

Name	Description
d_rtbd=json	This parameter instructs AAM to return a json response
d_orgid=...	Represents the IMS organization id, which uniquely identifies the Audience Manager client which is making the call (eg. PopularRetailer)
d_mid=...	Represents the Experience Cloud ID. Audience Manager will decode this id and will obtain an AAM ID.
d_cid=126066%01labuser20	Represents the cross-device customer id. Visit the documentation page here. Authenticated activity is stored keyed of cross-device ids, unauthenticated activity is stored keyed of device ids. If the HTTP call contains a valid cross-device customer id, AAM treats the call as authenticated activity. As a result, since our call does have a cross-device id declared on the HTTP call, the traits will be stored keyed of this cross-device customer id. The traits will NOT be stored on the device id for this specific call, since the cross-device id takes precedence.

The formatted json response will look like this:

{"stuff":[{"cn":"aam_aa","cv":"aamaa=12080591|aamaa=10209650","ttl":30,"dmn":""},{"cn":"Co okie_Destination","cv":"a=10209650","ttl":30,"dmn":""}],"uuid":"21700556125849053274229415 398555317701","dcs_region":3,"tid":"SOlR8wKFS+U=","data_collection":{"request_ids":[{"name space":4,"id":"22159308628525867984209987767182328452","type":"INTERNAL"},{"namespace":231 731,"id":"labuser20","type":"CROSS_DEVICE"}],"primary_device_id":{"id":"217005561258490532 74229415398555317701","type":"INTERNAL"},"device_metadata":{"is_robot":"1"},"request_targe t_url":"/event","request_method":"GET","request_headers":[{"key":"X-Forwarded-For","value" :"xx.xx.xx.xx"}],"request_params":[{"key":"d_mid","value":"2215930862852586798420998776718 2328452"},{"key":"d_full","value":"1"},{"key":"d_orgid","value":"YourCompanyMCOrgID%40Adob eOrg"},{"key":"d_rtbd","value":"json"},{"key":"d_cid","value":"231731\u0001labuser20"}],"r equest_is_secure":true,"request_user_agent":"curl/7.55.1"}}* Connection #0 to host subdomain.demdex.net left intact

Notice the object cross device ID above that has been returned in JSON. This is the CRM ID/Customer ID with which multiple device IDs are stitched. The above call simulates the behaviour when the user signs in and customer ID sync call fires.

• In our example, we generated MID first, and then made that MID qualify for a rule-based trait. Then we passed on the same MID and sent customer ID in a single call to sync both IDs.
• In real scenario, where we will have multiple Device IDs or Cross Device IDs, we can also automate using a batch job process. But that requires some custom scripting.

You can comment here and let us know if you need clarification on any specific step. Also, you can comment and share which approach you use when you work with DCS APIs.

[#2]

Nice one Varun, I recommend for the subdomain to point to specific AAM edge where your users are based. This will ensure that the AAM edge profiles are updated consistently.  This is to avoid any network routing factors.