Mutations

Mutations are simple functions that provide a way to dynamically modify the existing event data sent to collection. They provide access to the entire message, can alter the data payload as it passes through the event tracking pipeline, and can specify different communication protocols and destinations. Mutations are not plugins.

Note: For more details about this implementation, contact your Oracle Infinity solutions consultant.

In this topic:

See Tracking Reference to learn about using the core features of Oracle Infinity tracking and testing your tracking calls.

Mutations have the following priority ordering:

  1. System-level transforms
  2. User-level transforms (the default level)
  3. Final-level transforms

If a mutation lacks a specified priority, the default level is used (2). If multiple mutations share the same priority level, their ordering cannot be predicted.

    var testMutation1 = function(msg){
        msg.payload["addedVal1"] = "value1";
    };

    ORA.analytics.addMutation("myunique id", testMutation1);
    var testMutation2 = function(msg){
        msg.payload["addedVal2"] = "value2";
        ORA.analytics.rmMutation("mutationId2")
    };

    ORA.analytics.addMutation("myunique id", testMutation2);

Mutation methods

ORA.analytics.addMutation(mutantId, mutation)

You can add a mutation to alter any data sent to Oracle Infinity servers:

  • mutant_ID {string}: A unique string identifier that is just a label used in debug messages
  • mutation {function}: A function which takes a msg object as an argument

ORA.analytics.rmMutation(mutantId)

Remove a mutation to alter any data being sent on the pipeline:

  • mutant_ID {string}: A unique string identifier that is just a label used in debug messages

Message methods

The mutation function is called with a single argument containing the message object. Methods of that message object include:

  • setParam(key, val)
  • getParam(key)
  • ORA.common.TrackingPipeline.listMutations()

setParam(key, val)

This sets a parameter of lower case key to the value val:

  • key {string}: Unique key for payload parameter
  • val {string}: Value to set
    var testMutation1 = function(msg){
        msg.setParam("key1", "value1");
    };

    ORA.analytics.addMutation("myunique id", testMutation1);

getParam(key)

Returns the value of key lowercase, or null if key is not currently defined in the message payload.

  • key {string}: Unique key for payload parameter
    var testMutation1 = function(msg){
        console.log(msg.getParam("key1"));

    };
    ORA.analytics.addMutation("myunique id", testMutation1);

ORA.common.TrackingPipeline.listMutations()

Sends list of mutation IdGenerator's to debug output and returns an array containing a mutation tuple, which includes both the ID and mutation function.

   var res = ORA.common.TrackingPipeline.listMutations();
    // res[x] = {
    //    "id":"mutationId"
    //    "mutant": mutationFn
    // }

Troubleshooting/Developing Mutations

Any variable/data can be just passed to the tag as a key/value pair since we use a schema-less collection model (i.e. you don’t need to “pre-configure” parameters we collect). For example, if you open this URL in a browser:

https://shop.maxymised.com/?myvar=test

You’ll see that “myvar” come through on the event in Infinity Streams as:

Once you define a schema for whatever datapoints you need for reporting, you can then pass those as custom variables either on the URL bar, as the example above did, or as a mutation that we include in the tag.

For your own testing, after tagging your site, you can add/register mutations dynamically using the console window in your browser. For example, here you can see I manually register a mutation that adds another parameter “CustomVar2” with a value of “test2” to any event sent by the tag. Then, when I call the ORA.click() method again, you can see that the register mutation fires and adds those parameters into then click event.

Test Mutation:

ORA.analytics.addMutation('myMutation',function(p){p.setParam("CustomVar2","test2")},1);

Console view showing registering and firing the mutation:

The following screenshot from Infinity Streams showing the CustomVar2 parameter added by the mutation (and a CustomVar1 parameter I added manually to the URL bar):

Using this is the method of testing, you can use to develop/test mutations before deploying them into your tag permanently.

 

 

Learn more

Oracle CX Tag - Implementation - Implementation Guidelines for the Oracle CX Tag.

Oracle CX Tag - Event Tracking Functions - Learn how to send view, click and custom event calls to Oracle Infinity using the available Oracle Infinity Web Tracking Functions.

Oracle CX Tag - Tracking Reference - Core tracking features and testing guidelines for Oracle Infinity.

mutation, priority ordering, transform, payload, mutation API, message API