Adobe Analytics Connector Setup Guide

Universal Data Hub

Getting Started

Introduction to Universal Data Hub

Collecting Data

Enriching Data

Visitor & Audience Data

Sending Data

Storing Data

Visualizing Data

Administration

Managing User Permissions in UDH

Advanced Topics

FAQ

Adobe Analytics Connector Setup Guide

by - edited (1,314 Views)

The Adobe Analytics Connector in the Tealium Universal Data Hub uses Adobe's Data Insertion API to send analytics data server-side, in place of using the JavaScript beacon on each web page/app event. This reduces the amount of data transmitted from the client-side, and also offers the advantage of being able to pass Audience/Visitor data from AudienceStream to Adobe Analytics if you are licensed for Tealium AudienceStream.

This document is applicable whether you are using AudienceStream, EventStream, or both.

Connector Configuration
1. Title
2. Data Insertion Domain
3. Report Suite ID
4. Available Actions
5. Pick a data source
6. UTF-8 Encoding
Mappings
7. Report Suite IDs
8. General Attributes
9. Link Type
10. Context Data
11. Analytics eVars
12. Analytics Property Name (s.props)
13. Events (s.events)
14. Event Value Mapping
15. Products
16. Product Event Value Mapping
17. Product Merchandising eVars
18. Hierarchy Data
19. List Data
Visitor & Marketing Cloud IDs
Use Case 1: No prior Adobe Analytics implementation
Use Case 2: Migrating from existing Adobe Analytics client-side JavaScript
Debugging Common Issues

Connector Configuration

1. Title

Specify a title for the connector.

2. Data Insertion Domain

Insert your Adobe data collection domain.

3. Report Suite ID

Insert your Report Suite ID. May be a comma-separated list of report suites if you need to send data to multiple destinations.

This value may be overridden by mapping

4. Available Actions

The first step to configure the connector is to choose an action. For web data sources, you should choose "Post Data to Adobe Analytics". For mobile data sources (e.g. a mobile app or IoT device), you should choose "Post Data to Adobe Analytics (Mobile Optimized)".

5. Pick a data source

Connectors can be triggered by either an EventStream source (filtered stream/event spec), or AudienceStream source (audience).

6. UTF-8 Encoding

Unless you are sure that all values being passed in your Data Layer are already UTF-8 encoded, you should always enable this option. If not enabled, event attributes containing characters such as the ampersand character (&) may cause errors when the connector is triggered.

Mappings

7. Report Suite IDs

Here, you can specify a report suite ID, which will override any value previously entered in the Connector Configuration UI. If you do not need to override that value, you can leave this field blank. You can use either a data layer variable, or a "Custom Value". If you wish to send data to multiple report suites, you may use a comma-separated list.

8. General Attributes

This list highlights some of the most commonly-used attributes required for the Adobe Analytics connector, and how to set them. For a full reference, including details on exactly what each field should contain, please refer to Adobe's API documentation.

Map From	Map To	Notes	Sample Connector Output
UDH attribute containing a persistent visitor ID, e.g. tealium_visitor_id	visitorID*	Make sure this is a visitor-level persistent value (e.g. Tealium Visitor ID)	<visitorID>01619ea9a91a001af7e29b75797104079005c07101008M</visitorID>
UDH attribute containing a page name/title	pageName	String value	<pageName>Homepage</pageName>
UDH attribute containing the current URL (e.g. built-in "Current URL" attribute)	pageURL	String value	<pageURL>http://www.tealium.com\</pageURL>
UDH attribute containing the Adobe Marketing Cloud ID	marketingCloudVisitorID*	Usually retrieved via the Visitor API JavaScript tag implemented in Tealium iQ	<marketingCloudVisitorID></marketingCloudVisitorID>
UDH attribute containing the link name	linkName	String value (e.g. tealium_event)	<linkName>Buy Now</linkName>
UDH attribute containing the URL of the link clicked	linkURL	String value	<linkURL>https://www.tealium.com/products/widgets/buynow\</linkURL>
UDH attribute containing the order ID	purchaseID	String value, e-commerce order ID	<purchaseID>ORD12345</purchaseID>
UDH attribute containing the document referrer	referrer	Recommend using built-in "Referring URL" attribute	<referrer>https://www.tealium.com/shop\</referrer>
UDH attribute containing the timestamp from the time the event occurred	timestamp	Unix epoch time or ISO-8601 timestamp. Hits without a timestamp may be ignored.	<timestamp>1519207951063</timestamp>
UDH attribute containing the IP address of the visitor	ipaddress	To use this optional attribute, you must have enabled the Visitor IP Attribute in your account. Speak to your account manager if you need this feature.	<ipaddress>127.0.0.1</ipaddress>
UDH attribute containing the user agent of the browser/device	userAgent	Recommend using the built-in User Agent attribute in UDH	<userAgent>Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/64.0.3282.167 Safari/537.36</userAgent>
UDH attribute containing the transaction ID for a custom event (not order ID)	transactionID	This is not the same as purchaseID. Please see the Adobe Analytics documentation for details.	<transactionID>CMPSUMMER18</transactionID>

* Please see section "Visitor & Marketing Cloud IDs" below

9. Link Type

This field is used for link tracking, and allows setting of a Link Type.

Map From	Map To	Description	Example	Sample Connector Output
Select any attribute from dropdown, or enter custom value	Link type: "d" - Download Link "e" - Exit Link "o" - Custom (other) Link	Sends a Link Type to Adobe Analytics only if the attribute selected has a value*	Map: (Custom Value): "true" to "o"	<linkType>o</linkType>

If the attribute selected has a value of null, undefined or "" (empty string), the Link Type will not be set on the outgoing request.

10. Context Data

Context Data may be used as a more user-friendly alternative to props and eVars. You may map any event attribute or visitor attribute to Context Data variables in Adobe Analytics. Context Data variables may have any name, but Adobe's best practice is to prefix all variables with a unique key, such as your company name. Some variables are reserved and may only be used for pre-determined functionality, such as Lifecycle Metrics; these variables are prefixed with "a.".

Map From	Map To	Description	Example	Sample Connector Output
Select any attribute from dropdown, or enter custom value	companyname.someproperty	Maps a defined UDH attribute to a Context Data attribute	Map: (UDH Attribute) Campaign Name to "tealium.productColor"	<contextData><tealium.productColor>Red</tealium.productColor></contextData>

11. Analytics eVars

This field is used to map UDH attributes to eVars. eVars must be specified using the word "eVar" (not case-sensitive), plus the number of the eVar, e.g. "eVar11". Valid range is 1 through 250.

Map From	Map To	Description	Example	Sample Connector Output
Select any attribute from dropdown, or enter custom value	eVarX, where X is an integer in the range 1 - 250	Maps a defined UDH attribute to an eVar in your analytics reports	Map: (UDH Attribute) Campaign Name to "eVar75"	<eVar75>Summer2018</eVar75>

12. Analytics Property Name (s.props)

This field is used to map UDH attributes to props. Props must be specified using the word "prop", plus the number of the prop, e.g. "prop4". Valid range is 1 through 75. List props are supported, but these require prior configuration in your Adobe Analytics Report Suite admin interface.

Map From	Map To	Description	Example	Sample Connector Output
Select any attribute from dropdown, or enter custom value	propX, where X is an integer in the range 1 - 75	Maps a defined UDH attribute to an prop in your analytics reports	Map: (UDH Attribute) Link Name to "prop4"	<prop4>Buy Now</prop4>

13. Events (s.events)

Events allow you to measure how frequently a particular event is occurring on your website or in your app. The events variable is a comma-separated string listing all the events that should be counted for a particular analytics event. Both predefined events and custom events are sent in the same string.

In the Adobe Analytics connector, there are 2 ways to specify events:

Map an array value containing a list of event names that has been populated elsewhere (e.g. an extension in Tealium iQ, an Enrichment, or directly in your data layer).

Map From	Data Type	Example Input	Sample Connector Output
UDH attribute representing a list of events	Array	["event1", "event5", "event9"]	<events>event1,event5,event9</events>

Specify an array of string values which map to specific event numbers, and specify the event number mappings in the "Custom Event Mapping" section as follows:

Map From	Map To	Example Event Array	Example Input	Sample Connector Output
Custom text value containing a string to look up in the Events array	Name of event to trigger, e.g. event8	["newsletter_registration", "homepage_viewed"]	"newsletter_registration"	<events>event8</events> (because string "newsletter_registration" appeared in the events array)

14. Event Value Mapping

This field allows numerical values to be assigned to events. This field is not correlated to the "Custom Event Mapping" field; that is, if "event2" is specified in the "Custom Event Mapping" and is also specified as a "Value" event, it would be included in the event variable twice - once with no value, and once with.

Map From	Data Type	Map To	Example Input	Sample Connector Output
UDH attribute representing a numerical value	Number	eventX, where X is the number of the event	Map "9" to "event5"	<events>event5=9</events>

15. Products

The Products variable is used wherever it is necessary to capture e-commerce information about one or more products on a particular page (Category, Product ID, Price, Quantity).

Only UDH attributes with Array data types may be used to populate the Products variable. All arrays must be equal in length (i.e. if there are 5 products on the page, Product ID, Quantity, Price, and Category must all be 5 elements in length).

Map From	Data Type	Map To	Example Input Data	Sample Connector Output
UDH attribute representing Product Category	Array	Products Category	["Shoes", "Shirts"]	<products>Shoes;;;,Shirts;;;</products>
UDH attribute representing Product ID	Array	Products ID	["ABC123", "EFG234"]	<products>;ABC123;;,;EFG234;;</products>
UDH attribute representing Quantity	Array	Products Quantity	["1", "2"]	<products>;;1;,;;2;;</products>
UDH attribute representing Price	Array	Products Price	["149.99", "79.80"]	<products>;;;149.99,;;;79.80</products>

16. Product Event Value Mapping

This field allows a custom conversion event to be assigned to each product in the Products variable, and a numerical value to be assigned to each event.

If a "simple" variable is mapped (singular value, or custom text value), then the same value is applied to all products in the list. If a list (array) value is mapped, then the array must have the same length as the rest of the product arrays, and each item in the array will have a different value (according to its position in the array).

For these examples, assume the following product arrays are present as event attributes:

Product Category: ["Footwear", "Apparel"] Product ID: ["Running Shoes", "T-Shirt"] Quantity: ["1", "1"] Price: ["99.99", "49.99"]

Map From	Data Type	Map To	Example Input Value	Sample Connector Output
Custom text value containing a numerical value	String	Name of event to trigger, e.g. event8	"9.99" (custom value)	<events>event8</events><products>Footwear;Running Shoes;1;99.99;event8=9.99,Apparel;T-Shirt;1;49.99;event8=9.99</products>
UDH attribute representing array of numerical data	Array	Name of event to trigger, e.g. event12	["1.99", "4.99"]	<events>event8</events><products>Footwear;Running Shoes;1;99.99;event12=1.99,Apparel;T-Shirt;1;49.99;event12=4.99</products>

17. Product Merchandising eVars

This field allows eVars to be assigned to each product in the Products variable.

It works in the same way as the "Product Event Value Mapping" field, detailed above.

Map From	Data Type	Map To	Example Input Value	Sample Connector Output
Custom text value containing an eVar value	String	Name of eVar to trigger, e.g. eVar4	"my_custom_value"	<products>Footwear;Running Shoes;1;99.99;event8=9.99;eVar4=my_custom_value,Apparel;T-Shirt;1;49.99;event8=9.99;eVar4=my_custom_value</products>
UDH attribute representing array of eVar values (e.g. Product Color)	Array	Name of eVar to trigger, e.g. eVar6	["red", "green"]	<products>Footwear;Running Shoes;1;99.99;event8=9.99;eVar6=red,Apparel;T-Shirt;1;49.99;event8=9.99;eVar6=green</products>

18. Hierarchy Data

Page Hierarchy helps to classify a page within your site/app's navigation structure. There are 5 available slots: hier1 - hier5. The only supported UDH attribute type that can be used as a hierarchy var is an Array.

Map From	Data Type	Map To	Description	Example	Sample Connector Output
Select any attribute from dropdown, or enter custom value	Array	hier1 - hier5 (dropdown selection)	Maps a defined UDH attribute in Array format to a specified hierarchy var in Adobe Analytics	Map: (UDH Attribute) Page Classification to "hier1"	<hier1>Article</hier1>

19. List Data

List Variables are delimited strings containing multiple values, and are often used for attribution purposes. A maximum of 3 list variables is available for each Report Suite. The only supported UDH attribute type that can be used as a list var is an Array.

Map From	Data Type	Map To	Description	Example	Sample Connector Output
Select any array attribute from dropdown	Array	list1, list2, list3 (dropdown selection)	Maps a defined UDH attribute in Array format to a specified list var in Adobe Analytics	Map: (UDH Attribute) Referrer List to "list1"	<list1>google.com</list1>

Visitor & Marketing Cloud IDs

Please see the Adobe Analytics documentation on Visitor IDs, and the order of preference in the event that multiple IDs are provided.

Use Case 1: No prior Adobe Analytics implementation

If this will be a brand new Adobe Analytics implementation, 100% server-side, you may use your own unique visitor ID, and pass it to the visitorID attribute in the connector. You will need to decide what consitutes a suitable visitor ID, within the constraints set out by Adobe.

Use Case 2: Migrating from existing Adobe Analytics client-side JavaScript

If you are migrating from a JavaScript-based Adobe Analytics tag to the server-side connector, you will need to keep a consistent visitor ID to avoid "losing" visitors when/if you migrate fully. You will also need to migrate the visitor IDs if you are implementing the Adobe Analytics UDH connector as a secondary collection mechanism (where you are still using the JavaScript tag on your web pages or in your apps as the primary collection mechanism).

Step 1: Configure the Adobe Marketing Cloud ID tag

Follow these instructions to set up the tag in Tealium iQ.

Step 2: Store the Visitor ID/MCID in a cookie

In this step, you will store the Adobe visitor IDs in a first-party cookie. This will ensure that the value is transmitted to the UDH on each hit, without needing to re-request the value for the duration of the session.

a) In Tealium iQ, go to the Data Layer tab, and create 2 new First Party Cookie variables called "utag_main_adobe_mcid" and "utag_main_aa_vid".

You may rename these variables if you wish, but be sure to retain the "utag_main_" prefix, which will save cookie space by stacking into the utag_main cookie. If you rename the variables, you will need to also update the JavaScript snippet below.

b) Create a new JavaScript Code extension, scoped to the Adobe Marketing Cloud ID Service tag, and paste in the following code:

if (typeof vAPI !== "undefined") {
  vAPI.getInstance(u.data.adobe_org_id,
		   function (visitor) {
		     var mcID = visitor.getMarketingCloudVisitorID(),
			 analyticsID = visitor.getAnalyticsVisitorID(),
			 sessionExpiry = ";exp-session";
		     // store Adobe IDs for the session duration
		     if (!mcID) {
		       // something went wrong - the visitor IDs could not be retrieved
		       utag.DB("MCID could not be returned");
		     } else {
		       utag.loader.SC("utag_main",{"adobe_mcid" : mcID + sessionExpiry, "aa_vid" : analyticsID + sessionExpiry});
		       // optionally, trigger an empty utag.link call to trigger sending the cookie values to UDH
		       // if utag.track call is omitted (default), values will be sent on the next utag.link or utag.view call anyway
		       // utag.track is used to avoid calling other 3rd party tags; only the collect tag should respond
		       // utag.track("adobe_vid_updated", {});
		     }
		   },u.clearEmptyKeys(u.data.config), u.data.customer_ids);
}

This creates a callback to the Adobe Visitor ID service which will be called when the visitor ID(s) have been successfully retrieved from Adobe's servers, and stores the Visitor ID and Marketing Cloud ID in Tealium's own first-party cookie (utag_main). The cookie will expire at the end of the session in case the Visitor ID gets updated in future. If you wish to make the cookie persistent (non-expiring), you could set sessionExpiry to "" in the above code.

c) Add a condition to the JavaScript extension "utag_main_adobe_mcid is not defined AND utag_main_aa_vid is not defined". This prevents the code from running again during this session.

Step 3: Configure UDH

i) AudienceStream

If you have AudienceStream, you may store the Adobe Visitor ID and Marketing Cloud ID as visitor-level String attributes. Do not store them as "Visitor ID" attributes. For any actions triggered by an Audience event, you may then map the new attribute to visitorID and marketingCloudVisitorID in the connector configuration.

ii) EventStream

If you have EventStream, you do not have the ability to store ID variables, which is why we stored the value in a cookie. If you have already published your Tealium iQ configuration from the previous step to Prod, you will find the new utag_main_adobe_mcid and utag_main_aa_vid values already present in your Event Attributes. If you have not published to Prod, you may manually add the Event Attributes, making sure to select the "First Party Cookie > String" attribute type. Once you have defined these attributes, you may now choose them in the Adobe Analytics connector and map them to marketingCloudVisitorID and visitorID respectively.

Debugging Common Issues

To test the connector, we recommend using the Trace tool. While running a trace, look for the "HTTP Request Body" field, which will show the formatted XML that was sent to Adobe. You can compare the XML output to the "Sample Connector Output" fields in the above tables to verify the output.
Look for any errors in the response code being returned from Adobe. Anything other than HTTP Response Status: 200/Successful indicates that there was an error with the request.
The full URL structure for the Data Insertion API follows the format http://namespace.112.2o7.net/b/ss//6. Note that the double forward slash is intentional and valid (in the JavaScript Adobe Analytics implementation, the Report Suite ID would reside here). /6 indicates that an XML payload is being transmitted, and the reportSuite value is sent as part of the XML payload. This is the value you will see when running a Trace session.

You do not need to enter the full URL value into the connector configuration; Tealium auto-generates the URL based on the Data Insertion Domain value. You will only see the full URL when running a Trace session.

For your specific implementation, you may have a different value for the Data Insertion Domain (e.g. sc.omtrdc.net), but the namespace should always precede the domain (e.g. namespace.sc.omtrdc.net), except where you have your own first-party tracking domain (e.g. smetrics.acme.com).

Adobe Analytics Connector Setup Guide

Adobe Analytics Connector Setup Guide

vendorintegration_adobe_analytics

Connector Configuration

1. Title

2. Data Insertion Domain

3. Report Suite ID

4. Available Actions

5. Pick a data source

6. UTF-8 Encoding

Mappings

7. Report Suite IDs

8. General Attributes

9. Link Type

10. Context Data

11. Analytics eVars

12. Analytics Property Name (s.props)

13. Events (s.events)

14. Event Value Mapping

15. Products

16. Product Event Value Mapping

17. Product Merchandising eVars

18. Hierarchy Data

19. List Data

Visitor & Marketing Cloud IDs

Use Case 1: No prior Adobe Analytics implementation

Use Case 2: Migrating from existing Adobe Analytics client-side JavaScript

Step 1: Configure the Adobe Marketing Cloud ID tag

Step 2: Store the Visitor ID/MCID in a cookie

Step 3: Configure UDH

Debugging Common Issues