Campaign Design API > Setting up the tag

Bootstrapper

The Maxymiser tag is a JS bootstrapper applied as a single line of HTML code. The JavaScript library is called mmapi.js and performs campaign requests on the website pages. To set up Oracle Maxymiser on your site, simply insert the Maxymiser tag into the global template for your website.

For information on how to reconfigure and extend the mmapi.js library, see Configuring the tag. The library is hosted on a CDN and can be set up and deployed in the Site Settings section of the Maxymiser platform – see the following help section for more detail: Maxymiser UI > Manage Campaigns > Site Settings > Configure and Deploy JavaScript Library

Inserting the tag

The tag has to be inserted into the global template of your site before the closing head tag (</head>), and before any other scripts.

You can copy and paste the tag from the CD API Deployment section in Site Settings. For example:

<script type="text/javascript" src="//service.maxymiser.net/cdn/maxymiser/4632b5/js/mmapi.js"></script>

Below is an example of how to insert the path to mmapi.js in your page source's head:

Rules for inserting the tag

  1. The protocol (http/https) has been deliberately omitted from the tag to force the browser to download the tag using the same protocol as the page that was downloaded.
  2. Make sure you insert the Maxymiser tag in the page before the closing head tag (</head>). If this is not possible, then insert the tag at the top of the <body> before any 'renderable' content.
  3. Deploy the Maxymiser tag without the async or defer attributes set.
  4. If the Maxymiser tag is deployed using a tag container, then:
    1. Run the tag container synchronously i.e. without the async or defer attributes set.
    2. Ensure that the tag container exists before the closing head tag and can be downloaded using the same protocol as the page.
    3. Ensure that the tag container deploys the Maxymiser tag in a synchronous manner abiding by points 1 and 2.
  5. If the Maxymiser tag is deployed via another script, then the script inserting the Maxymiser tag must abide by points 1 and 2 and must use document.write to insert the Maxymiser tag.
    Using document.createElement and an insert or append command will make the Maxymiser tag run asynchronously, which means that the tag will not function as expected.

Verifying the integration

To verify that Maxymiser has integrated with your website successfully, check that requests to Maxymiser's server are visible using the network tab of your browser’s development tools. See the example below:

Configuring the tag

To configure the JavaScript library (mmapi.js), go to Site Settings > CD API Deployment to configure and deploy the JavaScript library as explained in the online help (Americas) / online help (EMEA).

The underlined areas are the options you need to configure. See the table after the code for a description of the options:

{ storageType: 'cookie', cprefix: 'mmcore', domain: 'domain.specified.in.the.Admin.UI', baseContentUrl: '//service.maxymiser.net/platform/us/api/', cookie_domain: 'place.root.domain.of.the.site.here', srv: '//service.maxymiser.net/cg/v5us/?', async: false, executionMode: 'eval', beforeInit: function( getParam, setParam, loader ){ /* custom code placeholder */ }, beforeRequest: function( setParam ){ /* custom code placeholder */ }, afterResponse: function( setParam, genInfo ){ /* custom code placeholder */ }, afterResponseExecution: function( getParam, setParam, genInfo ){ /* custom code placeholder */ } }

Below is a description of each option:

Option Description

storageType

The type of storage used to store Maxymiser data. This usually will not change. Possible values:

  • "cookie" – Use JSON-like cookie storage (default)
  • "cookie-key-value" – Use a separate cookie for every CD API storage item (designed to overcome an issue when server is configured to block requests with JSON data in headers; it should also take less space than the "cookie" storage)
  • "cookie-key-value-with-fallback" – Enable ITP 2.1 workaround for "cookie-key-value" (see more under Intelligent Tracking Prevention heading)
  • "cookie-secure" – Use HTTPS-only JSON-like storage
  • "cookie-key-value-secure" – Use a separate HTTPS-only cookie for every CD API storage item
  • "cookie-key-value-secure-with-fallback" – Enable ITP 2.1 workaround for "cookie-key-value-secure" (see more under Intelligent Tracking Prevention heading)

For all Oracle Maxymiser cookies descriptions please visit the Cookies Explained article.

The following options for cookies migration between formats are available:

  • "cookie" → "cookie-key-value"
  • "cookie-key-value" → "cookie" (with exception for expiration dates, all items will be set with 30-days lifespan)
  • "cookie" → "cookie-secure"
  • "cookie-key-value" → "cookie-key-value-secure"

cprefix (currently ignored)

The prefix used for cookies/storage names. This usually will not change. The default value is 'mmcore'

domain (required)

The domain should match the domain of the site you created in the Maxymiser UI. Note that this does not necessarily have to match the actual domain name of the website; it only needs to match what is in the UI.

baseContentUrl

This is the base path the API libraries will be loaded from, such as mmpackage-1.0js. This usually will not change although the default value depends on your region:

  • For the Americas, the default is '//service.maxymiser.net/platform/us/api/'
  • For EMEA, the default is '//service.maxymiser.net/platform/eu/api/'

cookie_domain (required)

This is the cookie domain to use. This is usually the top-level domain for the site. For example: '.domain.com' (with a preceding dot) for physical domains 'www.domain.com', 'secure.domain.com' and 'sub.domain.com'.

You can use the following code snippet to automatically calculate the proper cookie domain (in most cases):

'.'+(location.hostname.match(/[^.]+\.(\w{2,3}\.\w{2}|\w{2,})$/)||[location.hostname])[0]

srv

This is the base URL for Content Generator requests. This usually will not change although the default value depends on your region:

  • For the Americas, the default is '//service.maxymiser.net/cg/v5us/?'
  • For EMEA, the default is '//service.maxymiser.net/cg/v5/?'

async (required)

This flag controls whether or not the first request to the Content Generator is made asynchronously. Leave this value as 'false' to prevent flickering of default content.

Only set it to 'true' in the following cases:

  • If the website has the document type: “application/xhtml+xml”
  • If the library will be deployed through an asynchronous tag manager (such as Google Tag Manager) or deployed asynchronously for another reason.
Setting async to 'true' increases the risk of flicker.

executionMode

This setting switches Content Generator response format, the following options for the value are available:

  • 'eval' (default value): JSONP format with scripts wrapped into strings, so that they are evaluated
  • 'inline': JSONP format with scripts wrapped into functions that are just executed

'eval' mode makes it easier to debug the code as it creates an individual script that doesn't affect other scripts, while 'inline' mode could stop executing the whole response due to a single syntax error. The latter though doesn't use either eval(), or new Function() for the code execution, that makes it more suitable for the websites that are utilizing Content Security Policy.

These setting is available starting from CD API v.1.14 and CD API tag v.1.13.

beforeInit

This option allows you to extend the default behavior of the core library (i.e. mmapi.js) with custom functions.

beforeInit is an event triggered before the first Content Generator (CG) request on the page. See Extending the JavaScript Library for a description of the available functions.

beforeRequest

This option allows you to extend the default behavior of the core library (i.e. mmapi.js) with custom functions.

beforeRequest is an event triggered before every CG request on the page. See Extending the JavaScript Library for a description of the available functions.

afterResponse

This option allows you to extend the default behavior of the core library (i.e. mmapi.js) with custom functions.

afterResponse is an event triggered after every CG response. See Extending the JavaScript Library for a description of the available functions.

afterResponseExecution

This option allows you to extend the default behavior of the core library (i.e. mmapi.js) with custom functions.

afterResponseExecution is an event triggered after every CG response has been executed by the core library. See Extending the JavaScript Library for a description of the available functions.

Extending the JavaScript Library

You can extend the JavaScript Library (i.e. mmapi.js) to seamlessly process page or Content Generator (CG) data. Some cases where you may want to do this include:

  • To Initialize site-specific campaigns that should be executed before the first CG request or before each request.
  • To integrate single-page apps
  • To integrate with 3rd-party analytics
  • To transfer cross-domain cookies
  • To gather custom attributes

You can use four events within the mmapi.js configuration to bind your handlers:

Event Description Arguments
beforeInit Triggered before the first Content Generator (CG) request on the page
  • getParam(name, storage)
  • setParam(name, value, storage)
  • loader
beforeRequest Triggered before every CG request on the page
  • getParam(name, storage)
  • setParam(name, value, storage)
afterResponse Triggered after every CG response
  • getParam(name, storage)
  • setParam(name, value, storage)
  • genInfo
afterResponseExecution Triggered after every CG response has been executed by mmapi.js
  • getParam(name, storage)
  • setParam(name, value, storage)
  • genInfo

To identify the format of the parameter and value, look at the query string parameters in the CG request (shown in the example below):

Brief arguments description

  • getParam retrieves parameters from mmapi.js storage.
  • setParam overrides any URL parameter.
  • loader gives ability to turn off Maxymiser testing based on specific condition or switch to asynchronous request mode.
  • genInfo stores CG response data.

getParam( name, storage ) → {String|undefined}

Retrieves a GET request parameter stored by mmapi.js storage.

Parameters

Name Description Type
name

Name of the GET parameter. You can only access stored parameters.

  • pd (visitor identification data)
  • uv (actions)
  • uat (custom attributes)
  • pageid (virtual page URL)
String
storage

Storage ID where the parameter is stored.

  • 0 - 'persistent' (for 365 days), applicable to 'pd' and 'uat'
  • 1 - 'deferred request', applicable to 'uv'
  • 2 - 'request', applicable to 'uat', 'uv', 'pageid'
  • 3 - 'page'
Integer

Code example

var trackedActions = getParam('uv', 2);

setParam( name, value [, storage] )

Sets a GET request parameter using mmapi.js storage.

Parameters

Name Description Type
name

Name of the GET parameter. You can only access stored parameters.

  • pd (visitor identification data)
  • uv (actions)
  • uat (custom attributes)
  • pageid (virtual page URL)
String
value

Value of the GET parameter that is set automatically by mmapi.js

String
storage

Optional storage ID where the parameter is stored.

  • 0 - 'persistent' (for 365 days), applicable to 'pd' and 'uat'
  • 1 - 'deferred request', applicable to 'uv'
  • 2 - 'request', applicable to 'uat', 'uv', 'pageid'
  • 3 - 'page'

The default value is 1.

Integer

Code example

beforeInit: function( getParam, setParam, loader ) { function trim(str) { return str.replace(/^\s+|\s+$/gm, ''); } function setAttr(name, value, strategy) { strategy = strategy || 3; var uat = getParam('uat', strategy) || {}; uat[trim(name)] = trim(value + ''); setParam('uat', uat, strategy); } window.maxySegments = window.maxySegments || {}; Object.keys(window.maxySegments).forEach(function(segment) { setAttr(segment, window.maxySegments[segment]) }); },

loader.disable()

Cancels request to Maxymiser Content Generator. Testing becomes disabled for the current page.

This method is available in mmapi.js starting from version 1.7.

Code example

beforeInit: function( getParam, setParam, loader ) { document.cookie.split( '; ' ).forEach( function( cookie ) { var keyVal = cookie.split( '=' ); if ( keyVal[0] === 'internal_user' && keyVal[1] === '1' ) { loader.disable(); } } ); },

loader.setAsync( isAsync )

Switches to asynchronous CG request mode for the current page. Request is made in synchronous mode by default.

This method is available in mmapi.js starting from version 1.7.

Parameters

Name Description Type
isAsync

True or false value. If true – request will be made in asynchronous mode.

Boolean

Code example

beforeInit: function( getParam, setParam, loader ) { if ( location.pathname.match( /.*\/confirmation$/ ) !== null ) { loader.setAsync( true ); } },

loader.validateResponses( validator )

Validates CG response content to make decision whether to run it on the page or not.

This method is available in mmapi.js starting from version 1.11.

Parameters

Name Description Type
validator

A function that decides whether to execute a response from Content Generator.

Function

Code example

beforeInit: function( getParam, setParam, loader ) { // check if responses are valid loader.validateResponses( function( response, runResponse ) { // validation result: true or false var validationResult = true; // if validator returned a non-falsy value if ( validationResult ) { runResponse(); } } ); },

genInfo → {Object}

Returns CG response data relevant to this page.

Content Security Policy (CSP)

In case your website sends a Content-Security-Policy header or meta-tag, its value needs to include an exception for the service.maxymiser.net domain. Make sure you set the following values:

Content-Security-Policy: default-src 'self' service.maxymiser.net; img-src 'self' service.maxymiser.net; script-src 'unsafe-inline' 'self' service.maxymiser.net; style-src 'self' service.maxymiser.net 'unsafe-inline'; frame-src 'self' service.maxymiser.net

The CSP header value may need additional 'unsafe-eval' script-src exception for versions older than CD API v.1.14 and CD API tag v.1.13. To avoid having these exceptions, please update to the latest versions and use executionMode: 'inline' setting on the Maxymiser UI's "CD API Deployment" page.

Subresource Integrity (SRI)

Subresource Integrity feature is an optional feature that is supported and can be activated by adding "integrity" and "crossorigin" HTML attributes to the tag. Please note that if you utilize the integrity check, you need to maintain a valid hash of the resource. For example every time you are modifying the CD API tag in the Maxymiser UI, the SRI hash value should be re-generated and updated on all your site pages. More information on the topic is available at Subresource Integrity W3C specification.

Intelligent Tracking Prevention (ITP)

Apple have released an updated version of its Intelligent Tracking Prevention (ITP) with the latest updates to Safari on MacOS and iOS devices. ITP is aimed to protect user privacy by restricting the ability of advertisers and other services to track people around the web. In the latest ITP 2.* versions this is done by limiting the lifetime of first-party cookies to a 7-day window.

As a result, visitors using Safari are no longer recognized as "returning" if more than a week has passed from their last visit. Though it's hard to predict how many visitors will be affected and if there's a substantial impact on reporting, as it depends on the Safari browser userbase and their recency of visits on the site.

We have developed a workaround that replicates Maxymiser cookies into the browser’s localStorage. Every time a cookie is updated, it also gets a backup value to prevent ITP erasing it.

A note for campaign developers: it's important to understand that while cookies spread across sub-domains seamlessly, localStorage is origin-dependent. And if the Maxymiser cookies are cleared, only the data synced on the last visit to the current sub-domain will be restored.

So if a visitor's journey is limited to a specific hostname, there's nothing to worry about. In case a visitor would go to sub-domain #1 on day one, and to sub-domain #2 on day two, there's a risk of cookies being restored only from the sub-domain #1 session window. There's no evidence that it can happen often, but we just need to bear that in mind.

To switch it on, please set the storageType value to 'cookie-key-value-with-fallback' and update the Maxymiser tag to the latest version. This can be done on CD API Deployment page of the Maxymiser UI.





Next steps

Get started by looking at the tutorial on how to develop your first campaign with the API.