How do I use custom mappers with Google Analytics and Acoustic Exchange?

You can create a custom mapper object to suit your business needs. By creating a custom mapper, you can map custom event types, attributes, and identifiers in Google Analytics to the Acoustic Exchange naming convention and syntax.

There might be some cases where you want to capture nonstandard events, attributes, or identifiers in Google Analytics that are not listed in the Acoustic Exchange mapper, but still recognized by Acoustic Exchange. If that is the case, you can use your own mapper object.

For Acoustic Exchange to receive event data from your custom mapper, the Acoustic Exchange Capture code snippet and your mapper must load on the same page.

Mapping custom Google Analytics events to Acoustic Exchange

Google Analytics gives you the flexibility to create your own custom event types to suit your business needs. Acoustic Exchange respects that flexibility and customization by accepting custom Google Analytics events that are mapped to Acoustic Exchange supported event types. As such, you can override an existing event type in the Acoustic Exchange mapper and send any event that is supported by the Google Analytics endpoint. To do so, you must create custom identifier and attribute mapper arrays and pass the event data directly in the sendHitTask override.

By passing the event directly in the sendHitTask override, the custom event pulls identifier and attribute data from the custom mappers, packages the data under the event name, and sends it to Acoustic 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 Acoustic 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);
        });
});

Mapping custom Google Analytics identifiers to Acoustic Exchange

In some cases you might find it necessary to deviate from the default set of identifiers that Google Analytics provides and create custom identifiers. If you choose to do so, you can send the custom identifiers to Acoustic Exchange by creating a custom identifier mapper array. The identifier mapper array is a JSON object that maps custom Google Analytics identifiers to existing Acoustic Exchange identifiers by using the keys googleName and ubxName.

For example, the custom Google Analytics identifier dimesion6, parameter name cd6, can be mapped to an Acoustic 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 Acoustic Exchange identifier name is cookieId. This method of mapping will prove successful as long as the custom Google Analytics identifiers can be mapped to existing Acoustic Exchange identifiers. If you attempt to map a custom Google Analytics identifier with an identifier that does not exist in the Acoustic Exchange identifier repository, this method will fail.

To add a custom identifier to the Acoustic Exchange identifier repository, contact Acoustic 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 Section 7 in 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 UBX 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)>;
		});
	});

Mapping custom Google Analytics attributes to Acoustic Exchange

If you have custom attributes in Google Analytics and would like to send them to Acoustic Exchange, you can do so by creating a custom attribute mapper array. The attribute mapper array is a JSON object that maps custom attributes to Acoustic Exchange attributes by using the keys googleName and ubxName.

For example, the custom Google Analytics attribute dimesion7, parameter name cd7, can be mapped to an Acoustic 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 Acoustic 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 Acoustic 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 Acoustic 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>)>;
		});
	});