Overview
The API uses a JavaScript SDK and HTTP API instanced by a bootstrapper called mmapi.js (Maxymiser tag), which sits on all the website pages.
The bootstrapper requests JSON content that is generated by the Maxymiser server (Content Generator) using automatically collected information such as visitor idnetificator, page URL, device type, etc. and the Maxymiser UI configuration for a particular site.
When a Maxymiser campaign needs to be applied to a page for a specific visitor, the Content Generator provides a static package of functional API modules together with the campaign code, so that the API can be used by a developer to render content and track actions.
The following steps summarize how the API is made available for use:
- mmapi.js initiates a Content Generator request to pass information which identifies the current page and visitor.
- The Content Generator responds with the relevant data in JSONP format.
- Based on the Content Generator response, mmapi.js loads API modules and utilities, such as QA Tool or Mobile Preview Tool (MPT).
- Campaign content is applied to the page based on the logic defined in site and campaign scripts.
Using the API
Campaign developers can use the API from three areas in the Maxymiser UI (UI):
- Site scripts - In site scripts, you can use the site, actions, visitor, events and Deferred modules.
- Campaign scripts - In campaign scripts, you can use all of the API modules.
- Content variant scripts - In variant scripts, you can use all of the API modules, and HTML and CSS variables.
The code relevant code blocks for pages are returned from the Content Generator and made available from the API modules.
The API modules represent a library of campaign design templates that you can call to communicate with the Content Generator, and apply campaign content to webpages. The following is the list of the pre-defined variables within the available scripts:
The scripts that you create in the UI can use methods, functions, properties and variables in the API. Bear in mind that the site and campaign scripts created in the UI are executed automatically when they arrive at the target pages while variants are rendered using the renderer.runVariantJs method called from a campaign script.
For more information about the public interface for the API, see API Reference.
Debugging the API calls
CD API campaign development may require iterative code changes (even line by line). These operations may need a lot of time with the need to save the code in Maxymiser UI every time.
To facilitate campaign developers CD API provides the ability to use the browser console (usually activated by pressing F12 button in your browser window) to execute API functions for debugging purposes.
How-to guide to start debugging API calls
- Make sure you are an authorized user
You should be logged in to Maxymiser UI or added to Company IPs list
- Enable Debug utility
This can be done by adding mmcore.un=debug as a URL parameter or via executing mmsystem.enableUtility('debug');location.reload(); in the browser console - A new object mmsystem.debug becomes accessible via browser console (see syntax below).
CD API debugging syntax
mmsystem.debug.getResponses() → {Array<Object>}
Returns an array of JSON responses from Maxymiser Content Generator that arrived to the current page.
Code example
mmsystem.debug.site() → {Object}
Returns an object where references to all site modules (available in the site scripts) are stored.
Code example
mmsystem.debug.campaign( campaignName ) ? {Object}
Returns an object where references to all site modules (available in the campaign scripts) are stored.
Parameters
| Name | Description | Type |
| campaignName |
Name of the campaign you would like to retrieve modules of. Is a required argument, because every campaign has its own scope and data space. |
String |
Code example
What if more than one CD API version exists on the page?
If you have campaigns / scripts of different CD API versions (e.g., 1.5 and 2.1) on the same page, mmsystem.debug becomes extended with both versions as its branches:
How the API code is applied
When a visitor loads a webpage in their browser, the generated experience is delivered and applied to the page on top of the original content using a process of content application known as 'rendering'.
The renderer module in the API uses a JavaScript interface to apply campaigns to the test areas (i.e. elements) on the identified webpage.
Page rendering process
There are four stages in the page rendering process:
- Request is sent to the Content Generator (i.e. Content Generator)
- Response from the Content Generator, hide tested areas
- Wait for test areas to be parsed by the browser
- Show the test areas
Stage 1 - Request to the Content Generator
The Content Generator delivers dynamic script content to pages, tracks visitor actions, and displays experiences to visitors. Maxymiser JavaScript (mmapi.js) uses HTTP requests to communicate with the Content Generator.
The visitor's browser gets the Campaign Design API bootstrapper (mmapi.js) which gathers the initial parameters and makes the first Content Generator request. This request is performed on all webpages where mmapi.js is present and cannot be configured in the UI. The request initiates a connection between the visitor and Maxymiser to start delivering campaigns onto the requested pages.
Stage 2 - Response from the Content Generator
The Content Generator returns a JSON response with campaign content for the particular page and the visitor currently identified.
The JSON response is a container for all the dynamic content associated with a specific page, which includes:
- Unique identifiers used for visitor tracking
- Site scripts
- Campaign scripts
- Variant HTML (including JavaScript and CSS assets)
- References to additional utility scripts to be loaded, for example, the QA Tool
JSON is parsed immediately after the response is received by the visitor’s browser. Site and campaign scripts are executed at this stage so you can start applying your campaign to a page by using the renderer module to hide the test areas for content replacement.
Stage 3 - Wait for test areas to be parsed by the browser
The API engine waits for the original content of test areas to be fully parsed and applied by the browser. The rendered areas are still hidden (if applied at stage 2) so that the original content can be replaced with no flickering on the page.
As soon as the targeted areas are readily available within DOM (even before the DOM 'ready' state), the API engine can replace the original HTML with alternative HTML code received from the Content Generator. Campaign variants containing JavaScript constructs can also be executed seamlessly.
Stage 4 - Show test areas
The DOM loading process replaces test content and shows areas one at a time. Alternative test content (i.e. alternative variants) can include HTML, CSS and JavaScript, which you apply using the corresponding API methods.
The campaign rendering process is not visible to website visitors and does not compromise visitors' experience on the site.
To apply the alternative variants for the campaign, use the renderer module.
