Configure GA with Exchange

In order to achieve personalization, the analytics library deployed on your channel should send the visitor behavior data and channel events data to Acoustic Exchange. To achieve this, you should configure your analytics library to interact with Exchange.

If you use Google Analytics as the analytics library for your Single-Page Application (SPA) or Multi-Page Application (MPA), use this topic to configure it to interact with Acoustic Exchange.

Prerequisites

It is assumed that Google Analytics is already deployed on the channel to be personalized.
You have the Google Analytics ID (known as the GA ID) specific to the channel to be personalized. To view your Google Analytics ID, perform the following steps:

Log in to your Google Analytics account.
Click Admin.
Select an account from the menu in the Account column.
Select a property from the menu in the Property column.

Under Property, click Tracking Info > Tracking Code.

Make a note of the Tracking ID (also known as GA ID) displayed on the page.

You need to create a custom dimension in Google Analytics to include channel tenant ID as one of the attributes. This custom dimension allows Acoustic Personalization to send the channelTenantId information with the behavioral events to Exchange. Create a custom dimension in Google Analytics, with name channelTenantId. Perform the following steps:

Log in to Google Analytics account.
Create a custom dimension field, with the name as channelTenantId and with User's scope. For more information about how to create custom dimensions in Google Analytics, see this web page.

You should have the channel tenant ID that was generated when you registered the channel with Acoustic Personalization.

After you've completed these prerequisites, let's get started with configuring your Google Analytics with Exchange.

Step 1. Add the Exchange Capture Enablement code

Click the Enablement Code icon.

Copy the two lines of code that contain the enablement code. Save these lines of code in a text editor. These lines will be required in the next step.

Click Close.
Paste these two lines to your channel code.

If your channel is an SPA, paste these two lines at the beginning of HEAD tag of your index.html.
If your channel is an MPA, paste these two lines at the beginning of HEAD tag of each HTML page.

Before the setID function, add the following lines of code. This ensures that the correct pairing of your Personalization endpoint and Google Analytics endpoint is used in Exchange, by specifying the channel ID and the Events authentication for Google Analytics.

<script> ubxCapture.setTenantID("WRTP","<<channel tenant ID>>");
ubxCapture.setTenantID("GA","<< Events only authentication key for Google Analytics endpoint in UBX>>");
</script>

So, the overall code snippet would look similar to the one shown here.

<script type="text/javascript" src="//path/to/ubxCapture.js"></script>
<script> ubxCapture.setTenantID("WRTP","<<channel tenant ID>>");
ubxCapture.setTenantID("GA","<< Events only authentication key for Google Analytics endpoint in UBX>>");
</script>
<script type="text/javascript"> ubxCapture.setID("UBXCapture_EnablementKey"); </script>

📘
Ensure that the setTenantID script is always called before the setID script.

You have set up your channel to interact with Acoustic Exchange.

Step 2. Add the GA tracking code

Add the code snippet that enables Google Analytics to track the visitor behavior on your channel and share the events information with Exchange.

In case of Single-Page Application, add the following code at the beginning of HEAD tag of index.html page.
In case of Multi-Page Application, add the following code at the beginning of HEAD tag of each HTML page.

📘
Note
Update the identifiers mapper array according to the guidelines. For more information, see Exchange unique identifier types.

<script>var ubxEvents = [];</script> 
<script defer type="text/javascript">
        (function (i, s, o, g, r, a, m) {
            i["GoogleAnalyticsObject"] = r;
            (i[r] =
                i[r] ||
                function () {
                    (i[r].q = i[r].q || []).push(arguments);
                }),
                (i[r].l = 1 * new Date());
            (a = s.createElement(o)), (m = s.getElementsByTagName(o)[0]);
            a.async = 1;
            a.src = g;
            m.parentNode.insertBefore(a, m);
        })(
            window,
            document,
            "script",
            "https://www.google-analytics.com/analytics.js",
            "ga"
        );

        ga("create", "<<GA_ID>>", "auto");
        //Replace GA_ID with your GA ID
        ga("require", "ec");

        var identifiersMapperArray = [], ubxInformation;
        ga(function (tracker) {
            var clientId = tracker.get('clientId');

 /*This code snippet uses clientID as an example. You must decide the identifier and use the same. 
Refer to the guidelines for adding array for UBX identifiers. */ 

            identifiersMapperArray.push({ "name": "gaClientId", "value": clientId });
        });
        ga(function () {
            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));
                var hitType = model.get("hitType");
                google_ubx.sendEventFromPayload(payLoad, identifiersMapperArray);
            });
        }); 

    </script>

Step 3. Add custom dimensions

Next, you will add custom dimension you had created in the Prerequisites.

If your channel is an SPA, copy and paste the following code snippet inside the BODY tag of your index.html page.
If your channel is an MPA, copy and paste the following code snippet inside the BODY tag of each HTML page.

Note The code snippet assumes that dimension1 is configured in Google Analytics. If you are using a different dimension index, then replace dimension1 with appropriate dimensionN and cd1 with respective cdN.

<script>
window.addEventListener('load', function() {
            try {
                google_ubx.googleToUBXAddToCartEvent.attributesMapper.push({ "googleName": "cd1", "ubxName": "channeltenantId", "type": "string" });
                google_ubx.googleToUBXCartPurchaseEvent.attributesMapper.push({ "googleName": "cd1", "ubxName": "channeltenantId", "type": "string" });
                google_ubx.googleToUBXCartPurchaseItemEvent.attributesMapper.push({ "googleName": "cd1", "ubxName": "channeltenantId", "type": "string" });
                google_ubx.googleToUBXFormErrorEvent.attributesMapper.push({ "googleName": "cd1", "ubxName": "channeltenantId", "type": "string" });
                google_ubx.googleToUBXPageViewEvent.attributesMapper.push({ "googleName": "cd1", "ubxName": "channeltenantId", "type": "string" });
                google_ubx.googleToUBXProductRatingEvent.attributesMapper.push({ "googleName": "cd1", "ubxName": "channeltenantId", "type": "string" });
                google_ubx.googleToUBXProductReviewEvent.attributesMapper.push({ "googleName": "cd1", "ubxName": "channeltenantId", "type": "string" });
                google_ubx.googleToUBXProductViewEvent.attributesMapper.push({ "googleName": "cd1", "ubxName": "channeltenantId", "type": "string" });
                google_ubx.googleToUBXRemoveFromCartEvent.attributesMapper.push({ "googleName": "cd1", "ubxName": "channeltenantId", "type": "string" });
                google_ubx.googleToUBXVideoCompletedEvent.attributesMapper.push({ "googleName": "cd1", "ubxName": "channeltenantId", "type": "string" });
                google_ubx.googleToUBXVideoEvent.attributesMapper.push({ "googleName": "cd1", "ubxName": "channeltenantId", "type": "string" });
                google_ubx.googleToUBXVideoLaunchedEvent.attributesMapper.push({ "googleName": "cd1", "ubxName": "channeltenantId", "type": "string" });
                google_ubx.googleToUBXVideoPausedEvent.attributesMapper.push({ "googleName": "cd1", "ubxName": "channeltenantId", "type": "string" });
                google_ubx.googleToUBXVideoPlayedEvent.attributesMapper.push({ "googleName": "cd1", "ubxName": "channeltenantId", "type": "string" });
            } catch (error) {
                console.error(error); 
            }
            ga('set', 'dimension1', "<<channel tenant ID>>" );
            
            ibm_ubx.registerCallback("WRTP", function (eventPayload) {
                if(eventPayload) {
                    ubxEvents.push(eventPayload);
                }
            });
        });
</script>

Step 4. Enable Google Analytics tagging

Next step is to enable the Google Analytics tagging for your channel, and capture the events.
As a channel developer, you can use any of the approaches available to you. Here are a couple of options that you can consider:

Option A: You can include all your events in a separate .JS file and reference that JS file in the
Option B: You can include all your events directly in the

You have now successfully configured your Google Analytics library to interact with Acoustic Exchange.

References

For more information about integrating Exchange with Google Analytics, see Integration of Exchange with Google Analytics

Next steps

After configuring Google Analytics to interact with Exchange, you should Test the events flow in Exchange to verify the events flow from Google Analytics to your Personalization application.

Prerequisites

Step 1. Add the Exchange Capture Enablement code

📘

Step 2. Add the GA tracking code

📘Note

Step 3. Add custom dimensions

Step 4. Enable Google Analytics tagging

References

Next steps

📘
Note