Integrating with Adobe AudienceManager

Integrating with Adobe AudienceManager
Integrating with Adobe AudienceManager
Overview / CQ / Adobe Experience Manager 5.6.1 / Administering / Integrating with the Adobe Marketing Cloud /
As part of the Adobe Marketing Cloud, Adobe AudienceManager consolidates audience information from
all available sources. It identifies, quantifies, and optimizes high-value target audiences, which can then be
offered to advertisers via an integrated, secure, privacy-friendly management system that works across all
advertising distribution platforms.
This page explains how to integrate your site with AudienceManager. Before reading further you should be
familiar with Adobe AudienceManager and the official AudienceManager documentation.
PREREQUISITES
In order to use this feature you must have a valid Adobe Marketing Cloud AudienceManager account.
You will be able to get the necessary technical information from your Adobe account representative or
internal AudienceManager contact.
You will need:
1. A login to Adobe AudienceManager (username and password).
2. Access to the Adobe Audience Manager Administrative UI for Audience Manager Configuration tasks.
3. An AudienceManager ClientID and ClientSecret - this is not your username and password mentioned
above. It identifies the AEM instance to the AudienceManager server and is shared by all configurations
on the AEM instance.
4. The AudienceManager partner ID.
5. The AudienceManager container ID.
You should ask your contact to ensure that OAuth refresh tokens are enabled on your account as this will
enable to to authenticate once every 30 days for administrative purposes. Without the refresh tokens you will
have to authenticate once every 11 hours.
OSGI CONFIGURATION FOR THE AEM INSTANCE
Before using the integration you must configure the AudienceManager Client with the AudienceManager
Client ID and Client Secret mentioned above. Without this all requests to the AudienceManager service will
be denied.
NOTE
You only have to perform this step once per instance.
1.
2.
Navigate to the Configuration tab of the Web Console at:
http://localhost:4502/system/console/configMgr
Click on the component named Adobe CQ Audience Manager REST Client Service which should be
near the top of the list. You will see the configuration dialog below.
© 2012 Adobe Systems Incorporated.
All rights reserved.
Page 1
Created on 2014-11-07
Integrating with Adobe AudienceManager
3.
4.
5.
Enter the value you have been given for Client ID in the field labelled Audience Manager Client ID.
Enter the value you have been given for Client Secret in the field labelled Audience Manager Client
Secret.
Click Save.
That completes the OSGi Configuration for the AEM Instance. You will not have to do this again for the
instance unless the Client ID or the Client Secret change.
ADOBE AUDIENCEMANAGER CLOUD SERVICE CONFIGURATION
Once the AEM instance has been configured with a AudienceManager Client ID and Client Secret you
are ready to configure a connection between the AEM instance and the AudienceManager service
you have been given details for. There may be many instances of AudienceManager connected to a
single AEM instance, and vice versa. If you need to connect more than one you will have to make some
configuration changes (see below) to select which instance is being used on which site. By default AEM is
configured to connect to the AudienceManager Cloud Service configuration named "test". To configure that,
follow these steps:
1.
Navigate to the CloudServices configuration page at:
http://localhost:4502/etc/cloudservices.html
© 2012 Adobe Systems Incorporated.
All rights reserved.
Page 2
Created on 2014-11-07
Integrating with Adobe AudienceManager
2.
Select the AudienceManager item and click the Configure Now button. A Create Configuration dialog
appears.
3.
4.
Enter test into the title field. This will name the configuration "test".
Click the Create button.
When the test page is created, a dialog as below will appear. It will contain 3 blank fields which are all
required. The field Token Expire Date will be generated for you and you do not have to enter a value.
© 2012 Adobe Systems Incorporated.
All rights reserved.
Page 3
Created on 2014-11-07
Integrating with Adobe AudienceManager
5.
Enter the value given to you for the AudienceManager partner into the Partner field.
6.
Enter the value given to you for the Audience Manager container ID into the Container Namespace
ID field.
Click the button marked Connect to AudienceManager.
The values for Partner and Container Namespace ID will be validated with the AudienceManager
Service. If they are found to be valid you will be shown a username and password prompt to authorize
the AEM server to communicate with the AudienceManager service on your behalf. The AEM server
will not store your username and password, but will use them to authenticate and retrieve access
tokens.
7.
8.
9.
10.
11.
Enter your AudienceManager username in the Username field.
Enter your AudienceManager password in the Password field.
Click OK.
The configuration screen will complete the configuration on your behalf and retrieve access tokens to
enable the AEM instance to configure the AudienceManager service for AEM use. Once the tokens
are retrieved you will be taken back to the AudienceManager Setting dialog where the OK button
will be enabled, and the Token Expire Date field will be filled in. You will notice that the Connect to
AudienceManager button has been replaced by a Re-Connect to AudienceManager button. If you
need to re-authenticate this configuration in the future you may come back here and click that button to
re-authenticate and connect.
Click OK to save the tokens and initiate the configuration process.
Once the configuration settings are saved you will see the AudienceManager Setting screen updated with
your values.
In the background the AEM server will be communicating with the AudienceManager service. It will be
configuring segmentation rules for all AudienceManager Segments associated with your account and will
be setting up a URL Cookie destination in the AudienceManager service. When this process completes,
you will see a log message as below in the error log. The process takes about 30 seconds for each 100
AudienceManager Segments encountered.
This completes configuration of the Cloud Service for AudienceManager. You may now configure the Client
Context to enable you to manipulate AEM segmentation using AudienceManager traits.
CLIENT CONTEXT CONFIGURATION
The AudienceManager integration provides two new components in the Client Context that allows authors to
simulate the impact of AudienceManager Traits on AEM content driven by segmentation. The components
are not configured by default, but may be added.
1.
Navigate to http://localhost:4502/miscadmin#/etc/clientcontext/default/content.
2.
Select the ClientContext you want to configure, and double click on the page (in this case default).
© 2012 Adobe Systems Incorporated.
All rights reserved.
Page 4
Created on 2014-11-07
Integrating with Adobe AudienceManager
3.
4.
5.
You will see an unconfigured Client Context with a sidekick containing an Audience Manager Segments
component and an Audience Manager Traits component:
• The Audience Manager Segments component gives the Author feedback on the Audience Manager
Segments the client context profile has triggered.
• The Audience Manager Traits component allows an Author to manipulate the Audience Manager
Traits a client context profile is triggering.
Drag and drop the Audience Manager Segments component onto the client context.
Drag and drop the Audience Manager Traits component onto the client context.
Before any Audience Manager Traits can be triggered, a selection of traits must be identified and
added to the component. In a typical AudienceManager service there may be thousands of available
traits, so we use a search dialog to find traits to which your AudienceManager service is configured to
trigger.
Double click on the Audience Manager Traits component in the Client Context (not the sidekick), or
right click and select Edit.
A dialog will appear that allows you to find Audience Manager Traits by search and add them to a list of
selected traits:
© 2012 Adobe Systems Incorporated.
All rights reserved.
Page 5
Created on 2014-11-07
Integrating with Adobe AudienceManager
6.
Enter a term into the Trait search box, for example cq, after a short pause a list of traits that matches
that term will appear. If the list is too long, try a more specific term.
7.
Click the check boxes to move the term from the Search Traits list to the Selected Traits list. If you
want to remove any selected trait, check the checkbox to remove it.
When the list is configured as you want, click the OK button.
8.
© 2012 Adobe Systems Incorporated.
All rights reserved.
Page 6
Created on 2014-11-07
Integrating with Adobe AudienceManager
NOTE
Some searches can take time to respond, if you think the searches are taking too long,
have a look in the CQ5 error log where response times will be recorded.
The Audience Manager Traits box will be updated with the traits you selected. When the slider is green, the
trait is selected. If it is red then the trait is not selected.
The Audience Manager Segments list reflects the Audience Manager Traits that the AudienceManager
service reported as being triggered.
NOTE
Depending on the location of your instance relative to the AudienceManager service, the update
of Audience Manager Segments may not be instant. The error.log will report slow requests. If you
regularly see reports of greater than a few seconds, talk to your AudienceManager contact.
In addition to the Audience Manager Segments component, the standard AEM segmentation component
will reflect changes to AEM segments that match the selection. The URL for all AEM segments derived
from AudienceManager will be /etc/segmentation/aam/. This subtree is generated during the Cloud Service
configuration. You may reuse the rules of that subtree anywhere in the AEM segmentation tree.
© 2012 Adobe Systems Incorporated.
All rights reserved.
Page 7
Created on 2014-11-07
Integrating with Adobe AudienceManager
That completes the configuration of the Client Context. The component setup, and the Audience Manager
Traits configuration is shared by all profiles associated with the Client Context. The traits that are selected for
each profile will reflect the traits that were last selected for that profile. To verify this, try switching profiles.
PUBLISH INSTANCES
The AudienceManager integration comes with client side javascript for published pages. It uses the
information entered in the configuration to retrieve the Audience Manager Segments for the user viewing
the page on page load. There is no requirement to have any special AudienceManager libraries to make this
work.
In addition to automated load of user segments deployers may trigger events and traits back to the
AudienceManager instance using the Javascript method:
CQ_Analytics.AAM.AudienceManager.invoke(mapOfSignals)
where mapOfSignals is a map containing
sid : [ array of Audience Manager Triat IDS ]
any other property: a custom signal to the Audience Manager Service
The client library is located at
• /libs/cq/personalization/audiencemanager/clientlibs/core/audiencemanager.js
And loaded with configuration by one of:
• /libs/cq/personalization/audiencemanager/components/contextstores/aamsegments/init.js.jsp
• /libs/cq/personalization/audiencemanager/components/contextstores/aamtraits/init.js.jsp
NOTE
If you have more than one AudienceManager URL or Cookie Destination you want to incorporate
you may adjust the configuration in the init.js.jsp files to add those destinations in. See Using
Client Libraries for more details.
CHANGING THE SELECTED CLOUD SERVICE CONFIGURATION
To change which Cloud Service configuration is selected, change the inherited page
property audienceManagerConfig on the page in question to the name of the configuration. It defaults
to test.
© 2012 Adobe Systems Incorporated.
All rights reserved.
Page 8
Created on 2014-11-07