​​​This technical implementation guide shows Adobe implementation specialists how to send data captured by Adobe Analytics (AA) to Adobe Audience Manager (AAM).

This guide is intended for Adobe Consultants, Adobe Partners, and other experienced implementation specialists. Configuring this integration requires a full understanding of the implementation process for each individual solution covered in this guide.

Adobe customers can contact Adobe Professional Services or an Adobe Partner to learn more about this integration. 

Integration Options

When Adobe Analytics is present in the website, it is usually considered the primary source of information for Audience Manager. There are two methods of performing this integration:

 

  • Server-side Inte​​​​​​​​​​​gration (recommended): Data is sent from Analytics to Audience Manager in a server-to-server method, with no direct information being sent from the browser to AAM. In this case, the The Audience Management Module is inserted into AppMeasurement Library.
  • Client-side Integration: DIL (Legacy): We deploy the Data Integration Library code (also referred as DIL code) on the site. In this case, the data is directly sent from the browser to AAM DCS server in a server call.

This guide covers guidelines for both integration types.

​Method​​
Advantages Disadvantages

​Server-side Integration
(Audience Management Module)​

  • Only one server call (through Analytics)
  • Dynamic variables are resolved before being sent to AAM
  • Forward compatible (recommended by product management)
  • Only way to get Heartbeat video calls into AAM.​​
  • ​Requires Visitor ID service 2.0+ (SSF works with version 1.8+ but versions below 
    2.0 may cause some issues with Marketing Cloud ID service)​
  • Requires AppMeasurement library 1.8+​
  • ​​​More difficult to debug, as the integration is S2S
  • No processing rules, VISTA rules, Marketing Channels rules
  • Only AA variables can be used (but you can use context data variables for non-AA data)​​
Client-side Integration
DIL (Legacy)
  • ​Any information on the page can be used as a signal, not just eVars/props/events/context data
  • No requirement for Adobe Marketing Cloud
  • Easier to debug, as calls to AAM are sent from the browser
  • Can use both H-version s_code or AppMeasurement library
  • It can send data other than Analytics (e.g. from a data layer)
  • ​Calls are duplicated: one to ModStats, one to AAM DCS
  • No support for dynamic variables (D=)
  • No processing rules, VISTA rules, Marketing Channels rules
  • Legacy method (not recommended by product management)
  • ​For video tracking, only the initial video start hit is received

Solution Planning And Integration Architecture

Pre-requisites (License, Connectivity, Initialization)​

Server-side Integration​

  • ​The AAM account has been fully provisioned
  • The AA implementation is finished
  • Analytics collections servers are provisioned in RDC (in the next section named 'Set-up / Provisioning', it is explained how to verify this)
  • Adobe Analytics s_code - AppMeasurement (version 2.0 or higher)

Client-side Integration

  • The AAM account has been fully provisioned

  • The AA implementation is finished (In general, an AAM implementation comes after an AA implementation, so this step should already be finished when the AAM implementation starts or, at least in development)

  • Either H-code or AppMeasurement (Both H-version of the s_code and AppMeasurment library are supported by DIL)

You can verify the code version by using the Digital Pulse Debugger, a packet sniffer or the network tab of your browser. The following screenshot illustrates use of Digital Pulse Debugger to view the version of Adobe Analytics s_code.

aa-aam1

AppMeasurement Audience Management Module – The Audience Management module can be obtained from the Admin UI in Analytics and you should use the version of module that came building with whatever AppMeasurement version is running on the site.

Marketing Cloud Visitor ID service (version 2.0 or higher) – The Marketing Cloud Visitor ID service should be implemented, and the version of file should be 2.0+. Server-side forwarding works with version 1.8 or higher, but the one recommended by the product is at least 2.0.
The implementation of the Marketing Cloud Visitor Service can be verified by looking for the parameter "mid" in the Adobe Analytics Image Request:

aa-aam2

The version of Marketing Cloud Visitor Service can be confirmed by filtering for demdex in the network tab of the browser:

aa-aam3

Implementation Architecture

aa-aam4
aa-aam5

Installation, Provisioning and Configuration

Provisioning

To use the Server-side integration, your Marketing Cloud Organization must be provisioned to use the Audience Library. If the Audience Library has already been provisioned and you just need to add new Analytics servers, contact your Adobe representative.

​​Before submitting any request, you need to gather the following information:

  • Adobe Analytics Login company name 

  • Marketing Cloud Organization ID (this is visible in the Admin Console)

  • AAM company name and Partner ID

  • Analytics Tracking Servers (including omtrdc.net and first party domains for both HTTP and HTTPS)

​​​For this last point, you need to make sure you get them all. Here you have some potential sources of information, in order to gather these domains:​​

  • Asking the implementation specialist

  • Checking the analytics implementation using the Digital Pulse debugger:

aa-aam5a

Now, with all of this information, go to https://adobe.allegiancetech.com/cgi-bin/qwebcorporate.dll?idx=X8SVES and request the provisioning. Read carefully all the information in the form. Set the following answers:

  • For which capabilities are you requesting provisioning? Shared Audiences
  • Has the customer purchased Adobe Audience Manager? Yes​

Remember to include all tracking servers that will be used in server-side forwarding in the section "What Analytics Tracking Server(s) will be used with this Implementation". Do NOT include tracking servers on domains that will maintain legacy DIL code.

Solution Implementation

​Server-side Integration

  1. In Analytics, browse to Admin > Code Manager.

  2. Download the "JavaScript (new)" ZIP file.

    aa-aam6
  3. Extract the file "AppMeasurement_Module_AudienceManagement.js".

  4. Paste the contents of this file in the client's AppMeasurement.js file, just above the DO NOT ALTER ANYTHING BELOW THIS LINE ! warning.

  5. Just above the pasted code (above the line starting with function AppMeasurement_Module_AudienceManagement(d)), add the following line of code:

    s.loadModule("AudienceManagement");
  6. In the doPlugins section (do not put it outside this section, as it will not work), initialise the module:

    s.AudienceManagement.setup({
        "partner": <partner name>,
        "containerNSID": 0,
        "uuidCookie": {
            "name":"aam_uuid",
            "days":30
        }
    });

    The must be replaced with the demdex.net subdomain for this customer.

If you are using DTM, you need to disable/remove the Audience Manager tool, in case it was enabled. This tool is only for deploying the DIL code, which we are not using in this document. At the moment of writing this, there is a limitation with DTM and the Audience Management module, which forces to use the custom code option in the Analytics tool:

aa-aam7

The code you need to put is something similar to:

var s = s_gi(_satellite.getToolsByType("sc")[0].settings.account);
/*************** DO PLUGINS ***************/
function s_doPlugins(s) {
    // Initialisation
    s.AudienceManagement.setup({
        "partner": <partner name>,
        "containerNSID": 0,
        "uuidCookie": {
            "name":"aam_uuid",
            "days":30
        }
    });
}
s.doPlugins = s_doPlugins;
s.usePlugins = true;
s.loadModule("AudienceManagement");
function AppMeasurement_Module_AudienceManagement(d)
// Paste the whole AppMeasurement Module for Audience Management here
/*
 ============== DO NOT ALTER ANYTHING BELOW THIS LINE ! ===============
AppMeasurement for JavaScript version: 1.6
Copyright 1996-2016 Adobe, Inc. All Rights Reserved
More info available at http://www.adobe.com/marketing-cloud.html
*/
function AppMeasurement()
// Paste the whole AppMeasurement code here

Client-Side Integration

  1. Contact your Adobe representative to get the latest version of the DIL code.

  2. Add the custom JavaScript code:

    • Initialization of the library: depending on whether the Visitor ID service is in use, the code will be one or another; beware, adding both pieces of code will probably have unintended results.

    • Initialization of the Analytics module

  3. Make sure the Visitor ID service is deployed and that Adobe Analytics is already using it. The easiest way to see that is using the DigitalPulse Debugger, where you should see an mid parameter in the Analytics call:

    aa-aam6a
  4. Once you are sure the Visitor ID service is working, with the DIL code just downloaded, edit the file and, at the bottom of it, add the following code:

    var dil = DIL.create({
        partner: <partner name>,
        visitorService: {
            namespace: <marketing cloud ID>
        }
    });

    The <partner name> must be replaced with the demdex.net subdomain for this customer. 

    The <marketing cloud ID> can be retrieved from the Admin Console.

  5. Below the initialisation of the DIL library (i.e. after 1.1 or 1.2), the following code must be added.

    var _scDilObj = s_gi(s_account);
    DIL.modules.siteCatalyst.init(_scDilObj, dil, {
        names : ['pageName', 'channel', 'campaign', 'products', 'events', 'pe', 'referrer', 
    'server', 'purchaseID', 'zip', 'state'],
        iteratedNames : [{
                name : 'eVar',
                maxIndex : 100
            }, {
                name : 'prop',
                maxIndex : 75
            }, {
                name : 'pev',
                maxIndex : 3
            }, {
                name : 'hier',
                maxIndex : 4
            }
        ]
    });

    Regarding these parameters:

    • The list of properties of the s object in the "names" array above is the default list. If requested by the customer, this list can be edited; for example, if some variables contain PII, they should not be captured.

    • The "maxIndex" value for eVars needs to be adjusted for each client, depending on the contract:

    • 75 for customers with old contracts

    • 100 for Adobe Analytics Standard customers

    • 250 for Adobe Analytics Premium customers

    The SiteCatalyst module is standard in the DIL library; all confguration options can be found here: https://marketing.adobe.com/resources/help/en_US/aam/r_dil_sc_init.html.

  6. Add the standard library section of the DIL either at the top of the Analytics s_code or reference it on the page/add it to a file that is called before the Analytics s_code is called.

    Add the custom section of the DIL right before the closing of the s_doPlugins(s) function of the Adobe Analytics s_code (recommended approach).

If you are using Adobe Dynamic Tag Manager, please follow the steps indicated below:

  • Log on to DTM.

  • Choose the Web Property within DTM on which you want to set up AAM.

  • Click on Add a Tool.

  • Select Audience Manager from the drop down, give the tool a name and add the partner (subdomain) ID

  • Click on create tool and on the next window, click on the General tab.

  • Select the code version – reach out to your Audience Manager consultant for suggestions on what version of the code to use.

  • If you use Adobe Analytics, click on integrate with Adobe Analytics & check the box for Adobe Analytics under modules.

  • If you do not use Adobe Analytics, leave the integrate with option as default (none).

  • If you use Google Analytics, check the box for Google Analytics under modules.

  • Click on Customize Page Code > Open Editor and the Editor paste the custom section of the AAM DIL code from the previous step.

  • Save the changes – test in QA/Staging/Development environment using the instructions provided in the next step and publish the changes once validation is complete.

Testing

Server-Side Integration Test

One important difference between the client-side AA-AAM integration and the server-side integration is that it is not possible to debug directly the data being sent to AAM. This happens server-side and, as such, we do not have direct access to it. However, there are some indirect methods that will help you debug it.

Using the DigitalPulse Debugger. It is recommended that you unselect "Friendly Format", as there is a glitch with it for this integration. In fact all screenshots from now on will have this feature disabled. You should see some additional parameters in the Adobe Analytics image request, that were not there before adding the Audience Management module: a callback and some parameters under the "d" namespace. 
In older versions of VisitorAPI.js and Audience Management module, the callback function is passData(), but in newer versions you will see doPostbacks().

aa-aam8
aa-aam9

Using a full HTTP debugger, like Charles or HTTPFox, to visualise the full HTTP request.

The analytics request URL should now contain a "10" in the path, instead of the typical "1":

aa-aam10

The content type of the HTTP request is "application/x-javascript", instead of an image:

aa-aam11

The contents is some JavaScript code; it should not contain just the code "status" :"SUCCESS":

aa-aam12

Client-Side Integration Test

Adobe Audience Manager sends requests to Audience Manager servers just like Adobe Analytics/other Marketing Cloud Products.
It is suggested that the DIL code be validated at two levels – one as a standalone code to see if the DIL set up is fine, and then with the Analytics module (if present) as discussed above.

DIL Validation on the browser console

  1. Open the browser console, and paste the AAM DIL code in entirety (standard library and the custom section) on to the console. If you use a packet sniffer, ensure it is turned on and then hit the enter key. Fire the Adobe Analytics call (typically by calling the s.t() function)

  2. Look into the network tab of your browser/packet sniffer and filter by requests to the URL ".demdex.net".

    Ensure that all the data collection sources are being realized into Audience Manager. For example, if you have set up the DIL to collect Adobe Analytics, referrer, URI and object data look at the headers and the parameters sent across in the request and ensure all the data points are captured. Following screenshots indicate what to look at in the network tab of the browser or Charles, follow the same for any other packet sniffer that you might be using.

    aa-aam13

    Network call in browser's network tab of the browser:

    aa-aam14

    Request in Charles Packet Sniffer:

    aa-aam15

Validation in the Audience Manager UI

This step is similar for both the integration types: Client-side and Server-side. Data should start coming through to Audience Manager when the DIL is deployed and validated as mentioned above. The next step is to confirm reception of data at Audience Manager servers – Unused signals report and Trait creation/verification.


1. Unused Signals Report

  • The DIL sends data to Audience Manager servers as key/value pairs, these key/value pairs are referenced as signals

  • If there aren't any traits set up, all the key/value (signals) pairs with more than 100 instances show up in the Unused signals report

  • This report can be accessed from the Audience Manage UI – Analytics > Other Reports > Unused Signals

  • The presence of data in this report confirms successful implementation/setup of the DIL

2. Creating and verifying Traits

  • Traits can be created in the Audience Manager UI – Manage Data > Traits

  • Click on Add a new Rule Based Trait

  • Specify the Basic Information:

    • Name: Specify the name of the trait based on its function

    • Description (not mandatory) : Provide a detailed description of the trait

    • Data Source: Select the Data Source

    • Event Type (not mandatory): Select the type that most accurately applies to this trait; this value has no effect on the processing, it is just for classification purposes

    • Store In: Select an existing folder or create a new one; if a taxonomy has been defined, select the folder according to that taxonomy

  • Specify Advanced Information:

    • Set the expiration of the trait – for example 2 for days.

    • To set the trait to never expire specify 0

  • Specify the Trait Expression

    • Setup the Trait Expression

    • Various comparison operators are available: "==", "<=", "contains", "matchesregex"

    • You can make use of AND, OR and AND NOT Boolean operators

  • Note : Dynamic Variables (which are of the form "D=") set up in Adobe Analytics are NOT resolved, and therefore should not be used to create traits

  • Save the trait. Be sure to create a trait that would definitely have qualifications

  • Log on to Audience Manager after 24 hours and view the trait that you created. The trait graph should have a value greater than 0 for Uniques

DIL Validation on production website

  1. Deploy DIL on your website as described in "How-to" Deployment.

  2. Look into the network tab of your browser/packet sniffer and filter by requests to the URL ".demdex.net".

  3. Ensure that all the data collection sources are being realized into Audience Manager. For example, if you have set up the DIL to collect Adobe Analytics, referrer, URI and object data look at the headers and the parameters sent across in the request and ensure all the data points are captured. Following screenshots indicate what to look at in the network tab of the browser or Charles, follow the same for any other packet sniffer that you might be using.

    Network call in browser's network tab of the browser:

    aa-aam16

    Request in Charles Packet Sniffer:

    aa-aam17

Other Resources

FAQs

https://marketing.adobe.com/resources/help/en_US/aam/c_aam_faq_intro.html

Useful links/ Documents

Analytics Data in Audience Manager
Data Collection With Data Collection with DIL

Best Practices​

  1. It is very important to note that both implementation methods are mutually exclusive one one site. The moment the Audience Library is enabled and AA data collection hosts are configured by Adobe, all Analytics data will start to flow to AAM server-side. So, if the client keeps both DIL and AppMeasurment module, the data will be sent twice to AAM.​

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy