Server-side Audience Manager

24 Jun 2018 » AAM , Server Side

Let’s continue with the server-side implementation of the Adobe SaaS solutions. The next is the list is Audience Manager. This is probably one of the simplest implementation of all solutions. However, beware of server-side Audience Manager: it might not be what you are looking for.

Does it make sense?

When I wrote about the server-side ECID and server-side Analytics, I did not question the validity of the reasons why you would want to implement them ([UPDATE] now I have questioned ECID server-side in web environments). In fact, there are multiple valid reasons to go for it. And it is not only me saying that: colleagues and customers are more interested today in server-side everything than ever before.

However, server-side Audience Manager is a completely different thing. Remember the main reason of a DMP: manage audiences for a more efficient media spend. In order to achieve this, we need 3rd party cookies and ID syncs. However, if we create a server-side implementation, none of these two features happen:

  • 3rd party cookies. By using a server-side implementation, we are not storing any cookies in the browser, except for one to uniquely identify the visitor, which will be in a 1st party context. Even if we wanted to set a 3rd party cookie, it would be impossible, as browsers do not allow this.
  • ID syncs. There are two reasons why this feature is not available. On the one hand, ID syncing usually requires JavaScript executed client-side, which we have decided to remove. On the other hand, even if we could include the HTTP calls in the page, ID syncing requires 3rd party cookies.

In summary, if you have plans to use Audience Manager as a full DMP, forget about a pure server-side implementation. There are solutions for the previous issues, but they require client-side code. I may explain it in a future blog post.

When to implement server-side Audience Manager

There are, though, some reasons why you would still a server-side implementation for AAM:

  • Use only with Adobe products. If you plan to use AAM only as the place to manage segments for Target and Analytics, then you can continue with your server-side implementation. All you need is the ECID, which you already know how to get it.
  • Browser-less implementations. This type of implementations are becoming more popular. Examples are: kiosks, voice assistants, desktop applications… In this case, you can use AAM for better segmentation and to enrich the authenticated profile of the users. For the latter, remember that, if you use the same customer identification method everywhere, you can use this profile when the user goes back to the website, thanks to the profile merger rules.

If you still think you need server-side Audience Manager, read on!

Adobe Analytics server-side forwarding

The typical implementation will use Analytics server-side forwarding. Obviously, this only makes sense if you use Adobe Analytics. Basically, Analytics collection servers will forward the call to Audience Manager collections servers (DCS). This needs to be configured, either by enabling it in Adobe Analytics or via Shared Audiences. I will consider that you have followed my previous blog post on server-side Analytics for the rest of this section.

This option should work both with POST and GET methods. However, the POST method will not return any data and I will not cover it. Regarding the GET method, follow the steps in the aforementioned post, with the following additional conditions:

  • Replace the “0” at the in the path with “10”; this indicates you want the response from the AAM collection servers
  • Add d.&nsid=0&jsonv=1&.d to the query string; these are parameters which are specific to AAM
  • Include the MID (mid), the AAM blob (aamb) and the DCS region (aamlh) in the URL; take a look at the example aa-get.txt, where I am already using these parameters

So, the Analytics URL will look something like (the new lines are only to make it more readable, it should be one string):

https://[namespace].sc.omtrdc.net/b/ss/[rsid]/10?
    d.&nsid=0&jsonv=1&.d&
    mid=[MID]&aamlh=[REGION]&aamb=[BLOB]&
    key1=val1&key2=val2...

Once you compose the URL and submit it, the response you get will look something like:

{
  "dcs_region": 6,
  "stuff": [
    {
      "cn": "aam_perso",
      "cv": "everyone=true",
      "dmn": "",
      "ttl": 30
    },
    {
      "cn": "aam_check",
      "cv": "everyone=6",
      "dmn": "",
      "ttl": 30
    },
    {
      "cn": "at_adobeinternalxyz",
      "cv": "segments=3414853",
      "dmn": "api-adobe.com",
      "ttl": 1
    }
  ],
  "tid": "UxlGj+abSgI=",
  "uuid": "37172981710700735473004790906027438312"
}

The “stuff” parameter is an array with cookie-based destination.Since, in a server-side implementation, there are no cookies, it is up to you how to store this response. Each element in the array consists of:

  • cn: Cookie name
  • cv: Cookie value
  • dmn: Domain
  • ttl: Expiration of the cookie in days

The particular case of the cookie with name starting with “at_” can be ignored, as this is related to the AAM-AT integration.

DCS API

This is the original method, created by the AAM development team, before the server-side forwarding was implemented. However, I do not recommend this alternative method, unless you do not have Adobe Analytics. The DCS API supports both GET and POST methods. Both are basically the same, as opposed to the Analytics data insertion API, so I will only cover the GET method. You have the full documentation here.

The URL that you need to use is:

https://[partner].demdex.net/event?key1=val1&key2=val2&...

If you do not know the [partner] parameter of your account, get it from Adobe client care. Regarding the key/value pairs, there are certain restrictions:

  • AAM only supports a subset of keys.
  • Only use d_ keys if you know what you are doing
  • For all custom keys, you should always use c_ keys

Besides, if you want to create traits based on IP location or browser, you also need additional HTTP parameters in the calls:

  • X-Forwarded-For with the IP address of the client
  • User-Agent with the corresponding string from the browser making the request

Let’s see an example of a call to the DCS API:

GET /event?c_test=serverside HTTP/1.1
Host: [partner].demdex.net
Accept: */*
Cookie: demdex=37172981710700735473004790906027438312
User-Agent: Mozilla/5.0 (Android 4.4; Mobile; rv:41.0) Gecko/41.0 Firefox/41.0
X-Forwarded-For: 192.168.0.10

This call will return a 1×1 pixel in GIF format. However, you will probably want to get the response of the DCS. For this, you need to add additional query string parameters: d_rtbd=json&d_jsonv=1&d_dst=1:

GET /event?c_test=serverside&d_rtbd=json&d_jsonv=1&d_dst=1 HTTP/1.1
Host: [partner].demdex.net
Accept: */*
Cookie: demdex=37172981710700735473004790906027438312
User-Agent: Mozilla/5.0 (Android 4.4; Mobile; rv:41.0) Gecko/41.0 Firefox/41.0
X-Forwarded-For: 192.168.0.10

which gets you a JSON object:

{
  "stuff": [
    {
      "cn": "aam_perso",
      "cv": "everyone=true",
      "ttl": 30,
      "dmn": ""
    },
    {
      "cn": "aam_check",
      "cv": "everyone=6",
      "ttl": 30,
      "dmn": ""
    },
    {
      "cn": "at_adobeinternalxyz",
      "cv": "segments=3414853",
      "ttl": 1,
      "dmn": "api-adobe.com"
    }
  ],
  "uuid": "37172981710700735473004790906027438312",
  "dcs_region": 6,
  "tid": "AiLs4FpVRwY="
}

I am sure you will have noticed that this response is almost the same as the one received from server-side forwarding.

Finally, if you are using ECID, be it either client-side or server-side, you must user the same demdex cookie in both ECID and AAM calls. Remember that the ECID is generated by AAM servers: dpm.demdex.net.

Sample code

As usual, I am sharing with you a couple of scripts I have used to test the previous examples. I am fully aware that this not cover all potential cases, but this should be enough for most of the use cases.

Download the scripts:

I assume that you already have ecid.sh from a previous post and it works. Further instructions:

  1. Download the files and store them in the same directory as ecid.sh.
  2. Rename them, changing the extension from .txt to .sh.
  3. Edit them and set the collection server and report suite ID or partner ID, depending on the file
  4. If necessary, give the scripts executable permissions: chmod a+x aam-ssf.sh aam-dcsapi.sh.
  5. For aam-dcsapi.sh
    • You do not need to run ecid.sh beforehand; however, to test that the same demdex cookie is used, run this script and check it generates the ecid.json and cookies.txt files.
    • Run the script: $ ./aam-dcsapi.sh
  6. For aam-ssf.sh
    • Make sure ecid.sh has already run and generated the ecid.json and cookies.txt files.
    • Run the script: $ ./aam-ssf.sh

Feel free to modify these files until you get what you are looking for. Let me know in the comments if you run into any issues.

Related Posts