Integrate Acoustic Exchange and Google Analytics – Acoustic Help Center

The integration between Exchange and Google Analytics is a multi-step process that is composed of generating the Exchange Capture JavaScript snippet, placing that snippet into your website, overriding the Google Analytics sendHitTask, and enabling you application in Acoustic Exchange Capture.

Follow the steps listed in this guide to walk through and enable the Exchange and Google Analytics integration.

Before you begin

Exchange

You must have an Acoustic Exchange account.
You must be a licensed user of an Acoustic Exchange Business Partner solution.

If you do not have an Acoustic Exchange account and are a licensed user of Exchange or an Exchange Business Partner, you can request an Exchange account through our support.

Google Analytics

Ensure that you have a Google Analytics account and that you have configured your site according to Google Analytics' requirements. For more information, see the Google Analytics user help.

Register Google Analytics as an endpoint

To begin sharing Google Analytics data with Exchange and Exchange Business Partner Solutions, you need to register Google Analytics as an endpoint. This enables you to leverage the data collected by Google Analytics to retarget customers with timely and relevant offers.

Exchange requires Read permissions and a refresh token for your Google Analytics account to register as an endpoint. By granting read permissions you are allowing Exchange to communicate with your Google Analytics account.

Log in to Exchange.
On the Endpoints tab, click Register new endpoint to display the endpoint registration wizard.
Select Google Analytics, click Next, and follow the onscreen instructions to complete the registration.

Find your event-level authentication key

In the Acoustic Exchange and Google Analytics integration, the event-level authentication key is required to enable the Capture JavaScript snippet and provide a secure means of communication between the two platforms. The event-level authentication key is generated when you register an endpoint in Exchange.

In Exchange, navigate to the Endpoints tab.
Click and select Endpoint details.
Copy and save the key.

Add the sendHitTask override

By adding the sendHitTask override JavaScript snippet to your web page, you are overriding the sendHitTask in Google Analytics. The JavaScript snippet performs a custom function that causes event data to flow to both Exchange and Google Analytics in real time.

The sendHitTask override captures event data as a hit and sends it to Google Analytics and the UBX file as a hitPayLoad. The GAtoUBXEventMapper.js then maps the data to a UBX naming convention and syntax.

Without the JavaScript snippet, event data does not pass through the Exchange GAtoUBXEventMapper.js or UBX.js files, and by extension no event data is sent to Exchange.

Copy and paste the JavaScript Snippet below into your web page and replace the tracker name with your tracker name.

sendHitTask override JavaScript snippet

var tracker = ga.getByName("<REPLACE_TRACKER_NAME>");
		var originalSendHitTask = tracker.get("sendHitTask");
		tracker.set("sendHitTask", function(model) {
			originalSendHitTask(model);
			var payLoad = model.get("hitPayload");
			console.log("model=" + JSON.stringify(model));
			google_ubx.sendEventFromPayload(payLoad, identifiersMapperArray);

When you include the sendHitTask override in your web page, ensure that it is placed so that it loads after the create tracker method, ga("create", "UA-XXXXX-Y", "auto");. For example:

Example


    ga("create", "UA-XXXXX-Y", "auto");
    ga(function() {
		var tracker = ga.getByName("<REPLACE_TRACKER_NAME>");
		var originalSendHitTask = tracker.get("sendHitTask");
		tracker.set("sendHitTask", function(model) {
			originalSendHitTask(model);
			var payLoad = model.get("hitPayload");
			console.log("model=" + JSON.stringify(model));
			google_ubx.sendEventFromPayload(payLoad, identifiersMapperArray);
		});
	});


Code	Function
`originalSendHitTask(model)`	Sends the `hit` to Google Analytics.
`var payLoad = model.get("hitPayload")`	Retrieves the `hitPayload`.
`google_ubx.sendEventFromPayload(payLoad, identifiersMapperArray)`	Sends the `hitPayLoad` to `GAtoUBXEventMapper.js`.

Add the JavaScript snippet

To perform an Exchange and Google Analytics integration, you need to use the JavaScript snippet.

Navigate to Exchange user interface > Tools menu > Acoustic Exchange Capture.
Copy the Embed code from Capture. If the copy embed code screen does not display when you visit Capture, click the Copy embed code icon.
Paste the code into the header of every website that also contains Google Analytics code and the sendHitTask override. The Capture snippet must be loaded after the Google Analytics JavaScript and the sendHitTask override snippet.

Enable Google Analytics in Capture

To activate the Acoustic Exchange Capture JavaScript snippet that you embedded in your web page, you need enable your application in the Acoustic Exchange Capture user interface.

Paste the event-level authentication key in its assigned field in Acoustic Exchange Capture to enable the Acoustic Exchange Capture JavaScript snippet.

Log in to Exchange and navigate to the Tools menu.
Select Acoustic Exchange Capture.
In Capture, find and select your application. Follow the instructions on screen to complete the process.

After a 2-hour activation period, Capture activates the code on your website and data begins to flow from publisher to subscriber endpoints.

Integration data flow

An event is registered on the web page and captured by the sendHitTask override JavaScript snippet.
The sendHitTask override JavaScript snippet sends the event data to Google Analytics servers and the GAtoUBXEventMapper.js. The sendHitTask override must be loaded before an Acoustic Exchange JavaScript, and it must be placed in your web page manually.
After the data is mapped, the GAtoUBXEventMapper.js sends the data to UBX.js.
The UBX.js sends the data to Acoustic Exchange.

When a web page is configured with Exchange and Google Analytics JavaScript, event data is collected as a hit and captured by the sendHitTask override. The data is then passed to both the Google Analytics server and GAtoUBXEventMapper.js as a hitPayLoad. The GAtoUBXEventMapper.js maps the hitPayLoad to the Exchange naming convention and syntax. By mapping the event data to the Exchange naming convention, the UBX.js can read and understand the event data and send it to Exchange.

Default recognized Google Analytics mappings

By implementing v2.0 or later of the Exchange-Google Analytics integration JavaScript, some of the more common Google Analytics identifiers and attributes mappings are available instantly. However, if you prefer to map identifiers and attributes on your own, you are free to do so – the common identifiers and attributes do not interfere with your mappings.

Identifiers

The following table shows the default recognized identifiers.

Exchange identifier	Mapped value	Description
adobecookie	s_fid	The value for the s_fid Adobe Analytics cookie is mapped to the adobecookie Exchange identifier.
adobecookie	s_vi	The value for the s_vi Adobe Analytics cookie is mapped to the adobecookie Exchange identifier.
googleanalyticscookie	_ga	The value for the _ga Google Analytics cookie is mapped to the googleanalyticscookie Exchange identifier.
googleadscookie	_gads	The value for the _gads Google Ads cookie is mapped to the googleadscookie Exchange identifier.
ECID	spUserID	The Campaign URL query parameter spUserID is mapped to the ECID Exchange identifier.
ECID	com.silverpop.iMA.uid	com.silverpop.iMA.uid is a Campaign tracking cookie that is mapped to the ECID Exchange identifier.
ECID	SP_IDENTITY	The value for the SP_IDENTITY Campaign tracking cookie is mapped to the ECID Exchange identifier.
DAcookieId	cmRetrieveUserID	The value for the cmRetrieveUserID tracking cookie is mapped to the DAcookieId Exchange identifier.

Recognized default attributes

Exchange	Mapped value	Description
interactionId	WCXSID	The value for the WCXSID Tealeaf cookie is mapped to the interactionId Exchange attribute.
interactionId	TLTSID	The value for the TLTSID Tealeaf cookie is mapped to the interactionId Exchange attribute.
eventName	eventCode	If the eventName attribute is not defined for an event, then the event is automatically assigned the eventCode value for eventName attribute.

Some default attributes also work with behavioral analytics platforms like Tealeaf. For this Exchange integration, when events from the same web or mobile session are published by multiple endpoints, they must have matching interaction IDs appearing in the same customer journey in your behavioral analytics platform. In Tealeaf, the value of the interaction ID is mapped to the Exchange attribute interactionId. If an Exchange interactionId is already set and a Tealeaf interaction ID is detected, the interactionId is overridden by Tealeaf interaction ID.

Events

For this integration, we identified and defined recognized events typically registered by Google Analytics.

If you would like to augment the default recognized Google Analytics events with your own custom attributes, you can do so by modifying the corresponding attribute mapper object. For example, if you have a custom Google Analytics attribute prdes, and want to map it to the Acoustic Exchange attribute productDesc in ibmproductView event, then it would be mapped as:

google_ubx.googleToUBXProductViewEvent.attributesMapper.push
(
 {
 "googleName":"prdes","ubxName":"productDesc","type":"string"
 }
);

Recognized default events

Google attribute	Acoustic Exchange attribute	Attribute Type	Acoustic Exchange mapper field	Mapper Object	Description
pr1id	productID	string	ga('ec:setAction', 'detail');	google_ubx.googleTo UBXProductViewEvent	The mapper checks for enhanced commerce plug-in fields to find product information. The Google name in the mapper is the protocol parameter for the field.
pr1nm	productName	string
pr1ca	category	string
pr1va	color	string
pr1pr	basePrice	number
pr1qt	quantity	number
dl	productURL	string
cid	interactionID	string

Google Analytics reference documentation:

cartAdd

Google attribute	Acoustic Exchange attribute	Attribute Type	Acoustic Exchange mapper field	Mapper Object	Description
pr1id	productID	string	ga('ec:setAction', 'add');	google_ubx.googleTo UBXAddToCartEvent	The mapper checks for the enhanced commerce plug-in fields to find product information. The Google name in the mapper is the protocol parameter for the field.
pr1nm	productName	string
pr1ca	category	string
pr1va	color	string
pr1pr	basePrice	number
pr1qt	quantity	number
dl	productURL	string
cid	interactionID	string
cu	currency	string

Google Analytics reference documentation:

cartRemove

Google attribute	Acoustic Exchange attribute	Attribute Type	Acoustic Exchange mapper field	Mapper Object	Description
pr1id	productID	string	ga('ec:setAction', 'remove');	google_ubx.googleTo UBXRemoveFromCartEvent	The mapper checks for Enhanced commerce plug-in fields to find product information. The Google name in the mapper is the protocol parameter for the field.
pr1nm	productName	string
pr1ca	category	string
pr1va	color	string
pr1pr	basePrice	number
pr1qt	quantity	number
dl	productURL	string
cid	interactionID	string

Google Analytics reference documentation:

ibmcartPurchase

Google attribute	Acoustic Exchange attribute	Attribute Type	Acoustic Exchange mapper field	Mapper Object	Description
ti	orderID	string	N/A	google_ubx.googleTo UBXCartPurchaseEvent	By default, the ibmcartPurchaseItem event is sent automatically for each product when the event is triggered. You can turn this behavior off by setting the google_ubx.sendIndividualItemPurchaseEventWithCartPurchaseEvent = false; in the GAToUBXEventMapper.js file.
tr	orderTotal	number
cid	interactionId	number
cu	currency	number
pr<index>id	productID	string
pr<index>nm	productName	string
pr<index>ca	category	string
pr<index>va	color	string
pr<index>qt	quantity	number

ibmpageView

Google attribute	Acoustic Exchange attribute	Attribute Type	Acoustic Exchange mapper field	Mapper Object	Description
cid	interactionId	string	N/A	google_ubx.googleTo UBXPageViewEvent	N/A
dt	pageId	string
dl	pageURL	string

Custom attributes

The Google Analytics Acoustic Exchange mapper file has predefined mappings from the Google object attributes to Exchange attributes. These are attributes usually present in the Google object for most Google events and their mapping to Exchange event attributes is automatic. Because Google allows for a variety of custom attributes defined by the client for Google events, mappings from those attributes to Exchange attributes are possible by adding to the mapping objects in the Google Acoustic Exchange wrapper file. For instance, to add a product description to the Google product view event, this code must be run after the mapper file is loaded.

google_ubx.googleToUBXProductViewEvent.attributesMapper.push
(
 {
 "googleName":"prdes","ubxName":"productDesc","type":"string"
 }
);

Map custom Google Analytics events

Google Analytics gives you the flexibility to create your own custom event types to suit your business needs. You can override an existing event type in the Exchange mapper and send any event supported by the Google Analytics endpoint. To do so, create custom identifier and attribute mapper arrays and pass the event data directly in the sendHitTask override. The custom event will pull identifier and attribute data from the custom mappers, package the data under the event name, and send it to Exchange.

Use the following code as a template for your mapper arrays.

var googleToUBXIdentifiersMapper = [];
googleToUBXIdentifiersMapper.push
 ({"googleName":"googleIdentifierField1", 
 "ubxName":"ubxIdentifierField1"});
googleToUBXIdentifiersMapper.push
 ({"googleName":"googleIdentifierField2", 
 "ubxName":"ubxIdentifierField2"});
var googleToUBXAttributesMapper = [];
googleToUBXAttributesMapper.push
 ({"googleName":"googleAttributesField1", 
 "ubxName":"ubxAttributesField1", "type":"string"});
googleToUBXAttributesMapper.push
 ({"googleName":"googleAttributesField2", 
 "ubxName":"ubxAttributesField2", "type":"number"});

In the googleIdentifierFieldN field, enter the Google identifier name.
In the ubxIdentifierFieldN field, enter the Exchange identifier name.
In the googleAttributesFieldN field, enter the Google attribute names.
In the ubxAttributeFieldN field, enter the appropriate attributes for the event type.
To finalize the customization, call google_ubx.sendEventFromPayload(payLoad, <identifiersMapperArray>, <custom event name>, <attributeMapperArray>) in:

ga(function(tracker) {
		var originalSendHitTask = tracker.get('sendHitTask');
		tracker.set('sendHitTask', function(model) {
			originalSendHitTask(model);
			var payLoad = model.get('hitPayload');
			console.log(JSON.stringify(model));
			google_ubx.sendEventFromPayload(payLoad, 
         <identifiersMapperArray>, <custom event name>, <attributeMapperArray>);
		});
	});

Your final result can look similar to the following code sample.

var googleToUBXIdentifiers = [];
googleToUBXIdentifiers.push({"googleName":"cd1",
"ubxName":"recipientId"});
googleToUBXIdentifiers.push({"googleName":"cd2",
"ubxName":"cookieID"});
var googleToUBXAttributesMapper = [];
googleToUBXAttributesMapper.push({"googleName":"pr1id",
"ubxName":"productID","type":"string"});
googleToUBXAttributesMapper.push({"googleName":"pr1ca",
"ubxName":"category","type":"string"});
googleToUBXAttributesMapper.push({"googleName":"cd5",
"ubxName":"review","type":"string"});

var tracker = ga.getByName('t0');
 var originalSendHitTask = tracker.get('sendHitTask');
 tracker.set('sendHitTask', function(model) {
 originalSendHitTask(model);
 var payLoad = model.get('hitPayload');
 console.log("model=" + JSON.stringify(model));
 google_ubx.sendEventFromPayload(payLoad,
 googleToUBXIdentifiers,"wroteReview",googleToUBXAttributesMapper);
 });
});

Map custom Google Analytics identifiers

In some cases you might find it necessary to deviate from the default set of Google identifiers and create your own. You can send the custom identifiers to Exchange by creating a custom identifier mapper array. It is a JSON object that maps custom between the platforms by using the keys googleName and ubxName.

For example, the custom Google Analytics identifier dimesion6, parameter name cd6, can be mapped to an Exchange identifier by creating an array like googleToUBXIdentifiersMapper.push({"googleName":"cd6", "ubxName":"cookieId"}); and adding the name of the array to the sendHitTask override function. In this example, the Exchange identifier name is cookieId.

Note: This method of mapping will work only if the custom Google Analytics identifiers can be mapped to existing Exchange identifiers.

To add a custom identifier to the Acoustic Exchange identifier repository, contact Exchange provisioning.

For more information on custom Google Analytics identifiers, see Custom Dimensions / Metrics and the Analytics.js Field Reference in Google Analytics user help.

Note: In accordance with Google Analytics Terms of Service, personally identifiable information (PII) should not be sent to Google Analytics.

To map custom identifiers to Acoustic Exchange identifiers and events, use the following code as a template for your mapper array.

var identifiersMapperArray = [];
identifiersMapperArray.push
 ({"googleName":"googleField1","ubxName":"ubxIdentifierField1"});
identifiersMapperArray.push
 ({"googleName":"googleField2","ubxName":"ubxIdentifierField2"});
identifiersMapperArray.push
 ({"googleName":"googleField3","ubxName":"ubxIdentifierField3"});
identifiersMapperArray.push
 ({"googleName":"googleField4","ubxName":"ubxIdentifierField4"});

Enter the name of the mapper array in the identifiersMapperArray field.
Enter the Google Analytics custom identifier names in the googleNameN fields.
Enter the Exchange identifier names in the ubxIdentifierField1 fields.
Map the identifiers by calling google_ubx.sendEventFromPayload(payLoad, <mapper name>) in:

ga(function(tracker) {
 var originalSendHitTask = tracker.get('sendHitTask');
 tracker.set('sendHitTask', function(model) {
 originalSendHitTask(model);
 var payLoad = model.get('hitPayload');
 console.log(JSON.stringify(model));
 google_ubx.sendEventFromPayload(payLoad, <mapper name)>;
 });
 });

Map custom Google Analytics attributes

If you have custom attributes in Google Analytics and would like to send them to Exchange, you can do so by creating a custom attribute mapper array.

For example, the custom Google Analytics attribute dimesion7, parameter name cd7, can be mapped to an Exchange attribute by creating an array like googleToUBXattributesMapper.push({"googleName":"cd7", "ubxName":"productID"}); and calling the name of the array to the sendHitTask override function. In this example, the Acoustic Exchange attribute name is productID.

Additionally, this integration requires that an identifier mapper array and Exchange event type mapper array are called in tandem with the attributes mapper array. For example, google_ubx.sendEventFromPayload(payLoad, identifiersMapperArray, ubxEventTypeMapper, attributesMapperArray);.

To map custom attribute to Exchange attribute and events, use the following code as a template for your mapper array.

var attributesMapperArray = [];
attributesMapperArray.push
({"googleName":"googleField1", "ubxName":"ubxAttributesField1", 
"type":"string"});
attributesMapperArray.push
({"googleName":"googleField2", "ubxName":"ubxAttributesField2", 
"type":"number"});
attributesMapperArray.push
({"googleName":"googleField3", "ubxName":"ubxAttributesField3", 
"type":"string"});

Enter the name of the mapper array in the attributesMapperArray field.
Enter the Google Analytics custom attribute names in the googleNameN fields.
Enter the Exchange attribute names in the ubxattributeField1 fields.
Map the attributes by calling google_ubx.sendEventFromPayload(payLoad, identifiersMapperArray, ubxEventTypeMapper, <attribute mapper name>) in:

ga(function(tracker) {
		var originalSendHitTask = tracker.get('sendHitTask');
		tracker.set('sendHitTask', function(model) {
			originalSendHitTask(model);
			var payLoad = model.get('hitPayload');
			console.log(JSON.stringify(model));
			google_ubx.sendEventFromPayload(payLoad, <identifiersMapperArray>, 
                    <ubxEventTypeMapper>, <attribute mapper name>)>;
		});
	});

Google Analytics

Before you begin

Exchange

Google Analytics

Register Google Analytics as an endpoint

Find your event-level authentication key

Add the sendHitTask override

Add the JavaScript snippet

Enable Google Analytics in Capture

Integration data flow

Default recognized Google Analytics mappings

Identifiers

Recognized default attributes

Events

Recognized default events

cartAdd

cartRemove

ibmcartPurchase

ibmpageView

Custom attributes

Map custom Google Analytics events

Map custom Google Analytics identifiers

Map custom Google Analytics attributes

Related articles