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.
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:
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 thesendHitTask
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.
- 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.
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 theGAtoUBXEventMapper.js
. ThesendHitTask
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 toUBX.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.
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 |
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:
- https://developers.google.com/analytics/devguides/collection/analyticsjs/enhanced-ecommerce#product-detail-view
- https://developers.google.com/analytics/devguides/collection/analyticsjs/enhanced-ecommerce
- https://developers.google.com/analytics/devguides/collection/analyticsjs/field-reference#(product)_id
- https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#dl
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 |
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:
- https://developers.google.com/analytics/devguides/collection/analyticsjs/enhanced-ecommerce#add-remove-cart
- https://developers.google.com/analytics/devguides/collection/analyticsjs/field-reference
- https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters
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 |
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:
- https://developers.google.com/analytics/devguides/collection/analyticsjs/enhanced-ecommerce#add-remove-cart
- https://developers.google.com/analytics/devguides/collection/analyticsjs/field-reference
- https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters
ibmcartPurchase
Google attribute |
Acoustic Exchange attribute |
Attribute Type |
Acoustic Exchange mapper field |
Mapper Object |
Description |
ti |
orderID |
string |
N/A |
google_ubx.googleTo |
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 |
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.
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>)>;
});
});