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:

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

Rules for inserting the tag

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.
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.
Deploy the Maxymiser tag without the async or defer attributes set.
If the Maxymiser tag is deployed using a tag container, then:

Run the tag container synchronously i.e. without the async or defer attributes set.
Ensure that the tag container exists before the closing head tag and can be downloaded using the same protocol as the page.
Ensure that the tag container deploys the Maxymiser tag in a synchronous manner abiding by points 1 and 2.

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.enable()

Triggers a request to Maxymiser Content Generator in case the tag has been disabled. Testing becomes enabled for the current page.

Could be used in a scenario when the decision on whether to apply testing needs to be postponed till some condition fulfilled.

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

Code example

beforeInit: function( getParam, setParam, loader ) { if ( !/cookie_consent=1/.test( document.cookie ) ) { // disable the tag loader.disable(); // enable the tag when an external condition is fulfilled // window.onCookiesAllowed() call to be replaced with your code window.onCookiesAllowed( function() { loader.enable(); } ); } },

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.

Self-hosting the tag

Maxymiser tag (mmapi.js) and the Campaign Design API library (CD API, mmpackage.js) are supplied as CDN-hosted files. We do not recommend self-hosting these unless there's a strict policy restricting the hosting of 3^rd-party scripts.

The following benefits may no longer be available when self-hosting:

The tag and the CD API library can be seamlessly updated through the Maxymiser UI
The files are served through one of the world's largest CDNs, which implies low latency and stable connection

The tag and the CD API library are released and updated independently. The tag (mmapi.js) controls network requests and is configured per customer account. CD API (mmpackage.js) is a library of methods for building campaigns, it makes up a generic file used by all customers.

Self-hosting approach involves hosting and controlling both files yourself. You can then update them independently or together at your discretion once Maxymiser make new versions available. As additional benefit, self-hosting gives you control over the default caching policy (which is 30 minutes for mmapi.js and 1 year for mmpackage.js).

To start hosting both files you need to go through the following steps:

Upload mmapi.js to your hosting server and make sure it is set up as described above (in the "Inserting the tag" section of the article)
Upload the current version of mmpackage.js to a separate directory of your hosting, and then specify the path you used as "baseContentUrl" setting in the tag's JSON configuration section

Please note that the mmpackage.js version you need to host is set in the Maxymiser UI and can be set independently for the Sandbox and Production environment of Maxymiser campaigns. This file is used to render all the campaigns on your site, so needs to be synced with the selected version to make sure the testing is active. For instance, if version 1.22 is selected in "Site Settings" > "Site API Versions", you would need to have mmpackage-1.22.js hosted on your side. In case you were wondering, all those versions are hosted in the same directory on Maxymiser side as well, so you can simply access any version by manually changing it in the address bar.

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)

Note that this solution is not effective as of ITP 2.3 release. In case it was enabled for your site, please disable it in the Maxymiser tag configuration by removing -with-fallback from the storageType setting.

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.

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.

SameSite=Lax cookie attribute

Google have implemented a secure-by-default model for the Chrome browser cookies. It assumes any cookie should be protected from external resources (i.e., another site, a 3^rd-party) if no access scope is specified for it. This means that scripts that are utilized in cross-domain scenarios may stop working due to previously set cookies being unavailable between domains for users on Chrome 80 or newer browsers.

Secure-by-default model sets SameSite=Lax cookies if those don't have the SameSite attribute defined, which can be interpreted as "Do not send the cookie with the following cross-origin requests: non-GET, AJAX, iframe, image, etc." Only cookies with the specified SameSite=None; Secure setting will be available and only via HTTPS connection.

In the scope of Campaign Design API there's only one solution that requires accessing cookies from another site – it's Cross-domain visitor ID transfer. So if you are using Solution #2: iFrame, make sure you have Maxymiser Tag v.1.16 at least, the tag is configured with storageType: 'cookie-key-value-secure' and all your website pages are accessible through HTTPS connection only.

Next steps

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

Campaign Design API > Setting up the tag

Bootstrapper

Inserting the tag

Rules for inserting the tag

Verifying the integration

Configuring the tag

Extending the JavaScript Library

Brief arguments description

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

Parameters

Code example

setParam( name, value [, storage] )

Parameters

Code example

loader.disable()

Code example

loader.enable()

Code example

loader.setAsync( isAsync )

Parameters

Code example

loader.validateResponses( validator )

Parameters

Code example

genInfo → {Object}

Self-hosting the tag

Content Security Policy (CSP)

Subresource Integrity (SRI)

Intelligent Tracking Prevention (ITP)

SameSite=Lax cookie attribute

Next steps