Customize CX tag’s Maxymiser module

Disclaimer

This tag is available to joint Oracle Maxymiser and Oracle Infinity customers. Maxymiser-only customers will be able to migrate to it at a later stage.

Module settings

After a tag is set up from within the Data Collection UI, its settings get embedded into its body. Here’s an example of Maxymiser’s module settings for reference:


{
  /* UI Site */
  'site': 'test.com',
  'storage': {
    /* Cookie domain */
    'domain': '.test.com',
    /* Cookie expiration */
    'expiration': 128,
    /* Cookie prefix */
    'prefix': 'mmapi',
    /* Secure cookies */
    'secure': true
  },
  'request': {
    /* API directory */
    'api': '//service.maxymiser.net/platform/us/api/',
    /* Campaign content */
    'server': '//service.maxymiser.net/cg/v5us/',
    /* Response format */
    'response': 'inline'
  },
  'hide': {
    /* Auto-hiding */
    'rule': `body {
      opacity: .01 !important;
      pointer-events: none !important;
      user-select: none !important;
    }`,
    /* Auto-hiding timeout */
    'timeout': 2000
  },
  /* Custom extension */
  'beforeInit': `function(loader){
    console.log('Maxymiser ready');
  }`
}

All the settings are detailed below.

UI Site

Name	site
Data type	{String}
Mandatory	Yes
Description	The Maxymiser UI site name under which your campaigns are setup. It is an identifier of your workplace selected in the top-left burger menu of the Maxymiser UI. The value does not necessarily have to match the actual domain name of your website. It means that a single tag can be placed across different domains and environments.

Cookie domain

Name	storage.domain
Data type	{String}
Mandatory	No. The value is auto detected with JavaScript if not specified. A Regular Expression is used for the detection, so non-standard domain names may end up not detected properly. These are examples of values that need to be manually set: localhost IP address a name with a long composite TLD, such as “cloudfront.com”
Description	A domain that Maxymiser cookies are set to. As sub-domains are automatically included, specify the top-level domain where your campaigns run. Setting a value different to your domain will actually disable Maxymiser.

Cookie expiration

Name	storage.expiration
Data type	{Number}
Mandatory	No. Visitor profile is stored for 365 days out-of-the-box, unless a lower value is specified.
Description	Number of days of visitor’s inactivity after which a Maxymiser cookie expires.

Cookie prefix

Name	storage.prefix
Data type	{String}
Mandatory	No. If not specified, the default value of 'mmapi' is used.
Description	A custom prefix for all Oracle Maxymiser cookies.

Secure cookies

Name	storage.secure
Data type	{Boolean}
Mandatory	No. If not specified, true is used by default.
Description	Transmit cookies over secure protocol only, such as https.

API directory

Name	request.api
Data type	{String}
Mandatory	Yes
Description	The URL where Campaign Design API modules are hosted to run campaign content on a page. It also contains supplementary libraries, helping initialize QA Tool, Debug Tool and Campaign Designer. The value depends on your Maxymiser instance: `'//service.maxymiser.net/platform/us/api/'` – for the Americas `'//service.maxymiser.net/platform/eu/api/'` – for EMEA

Campaign content

Name	request.server
Data type	{String}
Mandatory	Yes
Description	The URL for dynamic content generation. The value depends on your Maxymiser instance: `'//service.maxymiser.net/cg/v5us/?'` – for the Americas `'//service.maxymiser.net/cg/v5/?'` – for EMEA

Response format

Name	request.response
Data type	{String}
Mandatory	Yes
Description	Campaign content response format. One of the following values is allowed: `'jsonp'` (default value) – the response arrives as JavaScript, containing all campaign scripts. Every script inside it is formatted as a String. On arrival every script gets executed with the help of the Function constructor, giving it an independent scope that doesn’t affect any other campaign script. `'jsonp-inline'` – the response arrives as JavaScript, containing all campaign scripts. Every script is incapsulated into Function. On arrival every script gets executed independently, so that it doesn’t affect any other campaign script. This response type suffers from syntax errors. In case at least one gets through with a custom script, the whole response may be blocked by the browser. `'json'` – the response comes to the page as text, that consists of a JavaScript object. Every campaign script inside it is formatted as a String. On arrival every script gets executed with the help of the Function constructor, giving it an independent scope that doesn’t affect any other campaign script. `'json-inline'` – the response comes to the page as text, that consists of a JavaScript object. Every campaign script inside it is incapsulated into a Function. On arrival every script gets executed independently, so that it doesn’t affect any other campaign script. This response type suffers from syntax errors. In case at least one gets through with a custom script, the whole response may be blocked by the browser.

Auto-hiding

Name	hide.rule
Data type	{String}
Mandatory	No
Description	As Oracle Maxymiser executes in an asynchronous mode by default, you should specify a CSS rule to hide your original tested content. This is done to avoid flicker (also known as Flash of Original Content) when original content gets replaced with one from a variant. The following CSS rule is normally used to accommodate for any area rendering: `body { opacity: .01 !important; pointer-events: none !important; user-select: none !important; }`

Auto-hiding timeout

Name	hide.timeout
Data type	{Number}
Mandatory	No. If not specified, the default value of 2000 (2 seconds) is used.
Description	A timeout in milliseconds for Maxymiser’s dynamic content to arrive. When it expires, the auto-hiding CSS rule is removed.

Custom extension

Name	beforeInit
Data type	{Function} wrapped into {String}
Mandatory	No
Description	Extend the default behavior of the Maxymiser module with custom functions. Available methods are described under the “Customize with code” heading.

Customize with code

The following custom extensions can be setup inside the beforeInit setting value:

Settings override – control the data sent over to Maxymiser
Module activation – disable and enable the tag module conditionally
Visitor data manipulation – override visitor-specific data stored in the browser
Module 'request' event – override request parameters with the "before request" event handler
Module 'response' events – parse response with the "response arrived" event handler, perform post-processing on "response executed" event
Visitor tracking control – comply with cookie consent solutions
Response verification – validate the dynamic content arriving from Maxymiser

All the custom code in the beforeinit function runs after the information required to generate Maxymiser campaigns request is collected.

Settings override

Syntax	loader.settings
Returns	{Object}
Description	Maxymiser module settings accessible with custom code. The settings can be either read or updated prior to the Maxymiser campaigns call.

Code example #1
Request campaigns for a different Maxymiser site (workplace).

if (/staging/.test(location.hostname)) {
  loader.settings.site = 'staging.site.com';
}

Code example #2
Turn on synchronous request mode.

loader.settings.request.syncRequestFunction = function(attrs) {
  var scriptTagAttrs = Object
                         .entries(attrs)
                         .map(attr => `${attr[0]}="${attr[1]}"`)
                         .join(' ');

  document.write('<script ' + scriptTagAttrs + '></script>');
}

Code example #3
Define a custom CSS selector for auto-hiding.

if (location.pathname === '/') {
  loader.settings.hide.rule = `.home_cta {
    visibility: hidden !important;
  }`;
}

Module activation

Syntax	loader.disable()
Description	Stop requesting Maxymiser campaigns.

Syntax	loader.enable()
Description	Start requesting Maxymiser campaigns. Effective after a loader.disable() call.

Code example #1
Disable experience optimization on a page.

if (/internal_user=1/.test(document.cookie )) {
  loader.disable();
}

Code example #2
Trigger Maxymiser campaign request at a later point.

if (!/cookie_consent=1/.test(document.cookie)) {
  loader.disable();

  // Enable when an external condition is fulfilled
  // window.onCookiesAllowed is used as an example
  window.onCookiesAllowed(function() {
    loader.enable();
  });
}

Visitor data manipulation

Syntax

Syntax	loader.storage.storeStrategies.*
Description	Constants to set storage data strategy. One of the values below can be used as an argument for loader.storage.get() or loader.storage.set() methods: `loader.storage.storeStrategies.persistent` – stored in the persistent storage, for a year by default. Applies to pd (historic visitor profile) and uat (custom atrributes). `loader.storage.storeStrategies.deferredRequest` – effective until a request to Maxymiser fires. True for uv (actions). `loader.storage.storeStrategies.request` – stored within the current browser tab only prior to a request to Maxymiser. Works for uat (custom attributes), uv (actions), pageid (custom page URL). `loader.storage.storeStrategies.page` – stored in memory, so gets sent for every request to Maxymiser from the browser tab.

loader.storage.storeStrategies.*

Description

Constants to set storage data strategy. One of the values below can be used as an argument for loader.storage.get() or loader.storage.set() methods:

loader.storage.storeStrategies.persistent – stored in the persistent storage, for a year by default. Applies to pd (historic visitor profile) and uat (custom atrributes).
loader.storage.storeStrategies.deferredRequest – effective until a request to Maxymiser fires. True for uv (actions).
loader.storage.storeStrategies.request – stored within the current browser tab only prior to a request to Maxymiser. Works for uat (custom attributes), uv (actions), pageid (custom page URL).
loader.storage.storeStrategies.page – stored in memory, so gets sent for every request to Maxymiser from the browser tab.

Syntax	loader.storage.get(name, strategy)
Accepts	`name` {String} `strategy` – one of the loader.storage.storeStrategies.* values
Returns	{Any}
Description	Retrieve a visitor-specific parameter from the browser storage.

Syntax

Syntax	loader.storage.set(name, value, strategy)
Accepts	`name` {String} `value` {String} `strategy` – one of the loader.storage.storeStrategies.* values
Description	Set a visitor-specific parameter into the browser storage. The parameter is then sent to Maxymiser until it expires (according to the passed strategy value). Please note, that the parameter’s value may need to be merged with the existing value in the storage if required.

loader.storage.set(name, value, strategy)

Accepts

name {String}

value {String}

strategy – one of the loader.storage.storeStrategies.* values

Description

Set a visitor-specific parameter into the browser storage. The parameter is then sent to Maxymiser until it expires (according to the passed strategy value).

Please note, that the parameter’s value may need to be merged with the existing value in the storage if required.

Code example #1
Capture visitor historic profile.

loader.on('responseExecuted', function(response) {
  window.captureVisitorId(
    loader.storage.get('pd', loader.storage.storeStrategies.persistent)
  );
});

Module 'request' event

Syntax

Syntax	loader.on('request', handler)
Accepts	`handler` {Function}
Description	Set an event handler that runs before every Maxymiser campaigns request. The handler’s argument may be used to read or update the request URL parameters. To find out the proper format for a URL parameter, please look at the query string of the Maxymiser campaigns request sent from your webpage: URL parameters you might want to use: `pd` – historic visitor profile `uv` – actions submitted with a request `uat` – custom attributes sent with a request `pageid` – custom page URL `ids` – optional customer identifiers

loader.on('request', handler)

Accepts

handler {Function}

Description

Set an event handler that runs before every Maxymiser campaigns request. The handler’s argument may be used to read or update the request URL parameters.

To find out the proper format for a URL parameter, please look at the query string of the Maxymiser campaigns request sent from your webpage:

URL parameters you might want to use:

pd – historic visitor profile
uv – actions submitted with a request
uat – custom attributes sent with a request
pageid – custom page URL
ids – optional customer identifiers

Code example #1
Capture Custom Attributes from a webpage.

loader.on('request', function(request) {
  // Update a value with request.params.key = 'value'
  // Read it by calling request.params.key directly

  function trim(str) {
    return str.replace(/^\s+|\s+$/gm, '');
  }

  function setAttr(name, value) {
    var uat = request.params.uat || {};
    uat[trim(name)] = trim(value + '');
    // Set custom attributes
    request.params.uat = uat;
  }

  window.maxySegments = window.maxySegments || {};
  Object.keys(window.maxySegments).forEach(function(segment) {
    setAttr(segment, window.maxySegments[segment]);
  });
});

Module 'response' events

Syntax	loader.on('response', handler)
Accepts	`handler` {Function}
Description	Set an event handler that runs before Maxymiser campaign scripts run. The handler’s argument may be used to read the response object.

Syntax

Syntax	loader.on('responseExecuted', handler)
Accepts	`handler` {Function}
Description	Set an event handler that runs after Maxymiser campaign scripts run. The handler’s argument may be used to read the response object. Please note, that all the campaign scripts run immediately. Page content rendering may be postponed until the relevant areas are ready to be replaced.

loader.on('responseExecuted', handler)

Accepts

handler {Function}

Description

Set an event handler that runs after Maxymiser campaign scripts run. The handler’s argument may be used to read the response object.

Please note, that all the campaign scripts run immediately. Page content rendering may be postponed until the relevant areas are ready to be replaced.

Code example #1
Send integration data.

loader.on('response', function(response) {
  window.sendAnalyticsData(response.Campaigns);
});

Visitor tracking control

Syntax	loader.storage.assignToMemory()
Description	Set visitor’s historic profile storage as memory, rather than cookies (the default setting). Memory storage expires as soon as a website tab is closed, refreshed or when the visitor navigates from the page. This method does not affect any of the existing Maxymiser cookies, but rather creates an empty variable as the new source for the Maxymiser-specific data.

Syntax

loader.storage.assignToMemory()

Description

Set visitor’s historic profile storage as memory, rather than cookies (the default setting). Memory storage expires as soon as a website tab is closed, refreshed or when the visitor navigates from the page.

This method does not affect any of the existing Maxymiser cookies, but rather creates an empty variable as the new source for the Maxymiser-specific data.

Syntax	loader.storage.assignToCookies()
Description	Migrate visitor profile from the in-memory storage into the cookie storage. Cookies get cleared if a visitor doesn’t interact with the website for a year or clears browser cookies.

Syntax	loader.storage.clear()
Description	Clears the in-memory and cookie storages.

Code example #1
Store visitor’s historic data in a variable until the tracking consent is given.

var consent = window.consentDecision();
if (typeof consent === 'undefined') {
  // No decision made yet
  loader.storage.assignToMemory();
} else if (consent === false) {
  // Visitor does not agree to be tracked
  loader.disable();
}

$(document).on('consent', function(event, decision) {
  if ( decision === true ) {
    // Visitor agrees to tracking
    loader.storage.assignToCookies();
    loader.enable();
  } else if (decision === false) {
    // Visitor changes mind, does not agree
    loader.storage.clear();
    loader.disable();
  }
});

Response verification

Syntax

Syntax	loader.setValidator(validator)
Accepts	`validator` {Function} – a custom function that accepts the response body and its invoker, that can be called as a function. The idea for the validator is to decide whether the response can run on a visitor. If it is valid, then the invoker function should be called with no arguments. If not – nothing happens, and the visitor sees the original page.
Description	Verify the dynamic data arriving with the Maxymiser campaigns response. This method should be called directly from within the beforeInit callback. Placing it inside the 'response' or 'responseExecuted' event handlers will lead to unwanted duplication of the validator.

loader.setValidator(validator)

Accepts

validator {Function} – a custom function that accepts the response body and its invoker, that can be called as a function.

The idea for the validator is to decide whether the response can run on a visitor. If it is valid, then the invoker function should be called with no arguments. If not – nothing happens, and the visitor sees the original page.

Description

Verify the dynamic data arriving with the Maxymiser campaigns response.

This method should be called directly from within the beforeInit callback. Placing it inside the 'response' or 'responseExecuted' event handlers will lead to unwanted duplication of the validator.

Code example #1
Validate the dynamic content that arrives from Maxymiser.

// Check if responses are valid
loader.setValidator(function(response, invoker) {
  var result = window.isValid(response.Campaigns);
  if (result) {
    invoker();
  }
});

Oracle Maxymiser Developer Help

Get Started

What’s New

Customize CX tag’s Maxymiser module

Disclaimer

Module settings

UI Site

Cookie domain

Cookie expiration

Cookie prefix

Secure cookies

API directory

Campaign content

Response format

Auto-hiding

Auto-hiding timeout

Custom extension

Customize with code

Settings override

Module activation

Visitor data manipulation

Module 'request' event

Module 'response' events

Visitor tracking control

Response verification