Reference summary

This section provides reference documentation for version 1.2 of the Maxymiser Campaign Design Javascript API (API)

Below is a summary of the available methods, functions, properties and variables to enable you to design campaigns using the API.

Methods

The following table shows all the available methods:

Properties

The following table shows all the available properties:

Functions

The following table shows the available function:

Variables

The following table shows the available variables:

Examples

• Skip rendering of the default experience (basic example)
• Apply dynamic variant (basic example)
• Persistent data storage (basic example)
• Process variant content from a campaign script (advanced)
• Share variables across campaign scripts (advanced)

Campaign

Use the Campaign module in campaign scripts to retrieve data for a campaign.

Reference table

Members

events - implement events localized on a campaign level (see the Events module for more information about event-driven scripts).

Methods

clearData( name )

Removes custom variable data from the campaign's persistent storage.

Parameters

Code example

getData( [name] ) → {*}

Retrieves the value of the custom variable from the campaign's persistent storage.

Parameters

Code example

getElements() → {Object}

Gets the content of all variants generated for the given visitor on the current page in JSON format.

Returned object nesting

Code example

getExperience() → {Object}

Gets information about the variants generated for the current campaign.

Returned object nesting

Code example

getName() → {String}

Gets the campaign name.

Code example

getStyles( [idAttribute] ) → {Array<String>}

Retrieves CSS text from campaign's HTML sources of the variants generated on the current page.

Parameters

Code example

isDefault() → {Boolean}

Identifies whether only default variants were generated on the page for the given campaign.

Code example

setData( name, value [, expires] )

Saves the value of the custom variable to the campaign's persistent storage, so it can be retrieved on other site pages using the campaign.getData() method.

Parameters

Code example

Properties

scope → {Object}

Editable property to be used for data sharing between different scripts on a page.

Code example

Examples

Basic example - skip rendering of the default experience

After your campaign arrives to the page with the Content Generator response, you can check the experience that was generated. When the experience to be shown is the default content, you can skip content hiding, using a campaign script, since content replacement is not required. See the following example:

Basic example - apply dynamic variant

If you have several alternative variants based on the same HTML/CSS template, it may be easier to combine common logic and experiences using a campaign script. See the following example:

The following example shows the HTML for the variant:

Basic example - persistent data storage

To pass information between pages or browser sessions for a specific visitor, you can use cookies to automatically store custom visitor data, and then use a campaign script that is mapped to the campaign page, to pass the visitor data to storage. See the following example:

To retrieve the data from storage, use a campaign script that is mapped to the action page. See the following example:

Advanced example - process content from a campaign script

You can specify how content is applied to a page (i.e. how experiences are rendered on a page), by using the campaign.getElements() method in a campaign script.

Advanced example - share variables across campaign scripts

Campaign scripts and campaign variants do not share namespaces to avoid code conflicts. To pass data between scripts, you need to use campaign.scope:

Site

Use the Site module within site and campaign scripts to store the experiences generated for all active campaigns on the current page. The Site module also provides a shared namespace for all campaigns.

Reference table

Examples

• 3rd-party integration
• Sharing data across campaigns

Methods

getPageExperiences() → {Object}

Gets information about the variants generated for all campaigns on the current page.

Returned object nesting

Code example

Properties

scope → {Object}

Editable property to be used for data sharing between different scripts on a page.

Code example

Examples

3rd-party integration

You can use a site script to integrate with a 3rd-party application that accepts generated campaign info as an argument. See the following example:

Sharing data across campaigns

You can share data between different scripts or define functions that will be available across a site. See the following example for the code in a site script:

The following example shows the code in a campaign script:

Dom

Use the Dom module within site and campaign scripts for DOM manipulation.

Reference table

Example

• Apply Variant CSS

Methods

addCss( css [, alias] ) → {Dom}

Applies CSS rules to a page.

Parameters

Code example

addListener( selector, eventName, handler )

Assigns DOM event handler to the selected elements.

Parameters

Code example

bringToFront( element [, zIndex] )

Changes the z-index value of the target node to the highest value across all the DOM nodes on the page.

This method iteratively waits (with a 50 ms interval) for the target nodes to appear, so that the change can be applied even if content arrives asynchronously.

Parameters

Code example

changeImageBanner( element, properties )

Updates an existing image or banner.

This method iteratively waits (with a 50 ms interval) for the target nodes to appear, so that the change can be applied even if content arrives asynchronously.

Parameters

Code example

changeLinkUrl( element, value )

Sets the 'href' attribute value of the target node.

This method iteratively waits (with a 50 ms interval) for the target nodes to appear, so that the change can be applied even if content arrives asynchronously.

Parameters

Code example

changeStyle( element, cssRules )

Updates the inline style of the target node.

This method iteratively waits (with a 50 ms interval) for the target nodes to appear, so that the change can be applied even if content arrives asynchronously.

Parameters

Code example

editHtml( element, html )

Replaces the innerHTML value of the target node.

This method iteratively waits (with a 50 ms interval) for the target nodes to appear, so that the change can be applied even if content arrives asynchronously.

Parameters

Code example

getNodesAttribute( selector, name ) → {Promise}

Reads the specified attribute values for the selected elements.

Parameters

Code example

freeMove( element, deltaX, deltaY )

Changes the relative position of the target node.

This method iteratively waits (with a 50 ms interval) for the target nodes to appear, so that the change can be applied even if content arrives asynchronously.

Parameters

Code example

guidedMove( element, index )

Changes the relative placement of the target node within its parent in relation to the siblings.

This method iteratively waits (with a 50 ms interval) for the target nodes to appear, so that the change can be applied even if content arrives asynchronously.

Parameters

Code example

hide( element )

Hides the target node.

This method iteratively waits (with a 50 ms interval) for the target nodes to appear, so that the change can be applied even if content arrives asynchronously.

Parameters

Code example

insertHtmlAbove( element, html )

Adds HTML content above the target node.

This method iteratively waits (with a 50 ms interval) for the target nodes to appear, so that the change can be applied even if content arrives asynchronously.

Parameters

Code example

insertHtmlBelow( element, html )

Adds HTML content below the target node.

This method iteratively waits (with a 50 ms interval) for the target nodes to appear, so that the change can be applied even if content arrives asynchronously.

Parameters

Code example

insertHtmlWithin( element, html )

Adds HTML content to the end the target node content.

This method iteratively waits (with a 50 ms interval) for the target nodes to appear, so that the change can be applied even if content arrives asynchronously.

Parameters

Code example

insertImageBannerAbove( element, properties )

Creates an image banner before the target node.

Parameters

Code example

insertImageBannerBelow( element, properties )

Creates an image banner after the target node.

Parameters

Code example

insertImageBannerWithin( element, properties )

Creates an image banner into the target node.

Parameters

Code example

remove( element )

Deletes the target node from the DOM.

This method iteratively waits (with a 50 ms interval) for the target nodes to appear, so that the change can be applied even if content arrives asynchronously.

Parameters

Code example

removeCss( alias ) → {Dom}

Removes the CSS that was previously added.

Parameters

Code example

removeListener( selector, eventName, handler )

Removes the specified DOM event handler from the selected elements.

Parameters

Code example

resize( element, width, height, deltaX, deltaY )

Changes the height and width of the target node.

This method iteratively waits (with a 50 ms interval) for the target nodes to appear, so that the change can be applied even if content arrives asynchronously.

Parameters

Code example

setNodesAttribute( selector, name, value )

Sets the specified attribute values for the selected elements.

Parameters

Code example

Examples

Apply variant CSS

To apply variant CSS, use the following sample code in a Content Variant:

Renderer

Use the Renderer module in campaign scripts to retrieve and display campaign content on a page.

You can either use Maxymiser's out-of-the-box logic to retrieve and show campaign content, or customize it as required.

Reference table

Examples

• Render campaign content (basic example)
• Identify if a campaign applies to a page (basic example)
• Get campaign data (basic example)
• Handle content on AJAX pages (basic example)
• Configure time before campaign content is displayed (advanced example)

Methods

getContent( [virtualUrl] ) → {Promise}

Makes additional requests to the Content Generator to get campaign content. See the Deferred module for more information on 'promise'.

Parameters

Code example

hide( cssSelector [, alias] ) → {Renderer}

Hides the test areas for replacement with alternative content.

Parameters

Code example

runVariantJs( [element] ) → {Renderer}

Applies an element to the page immediately. This method can be called when you want to replace the default content.

Parameters

Code example

show( alias ) → {Renderer}

Shows content using the given alias identifier.

Parameters

Code example

showAll() → {Renderer}

Shows all the previously hidden content for the current campaign.

Code example

unhideAfter( timeoutValue ) → {Renderer}

Automatically displays content after a specified time has elapsed.

Parameters

Code example

waitUntilDom( successCondition ) → {Promise}

Executes the when() method with the specified success() condition and pre-defined reject() condition - DOM readiness.

Parameters

Code example

waitForElement( cssSelector ) → {Promise}

Checks if the specified element exists on the page and as soon as it appears, executes success and always callbacks. The method continues with iterative checks until DOM is ready, then fail callbacks are triggered.

Parameters

Code example

when( ... ) → {Promise}

renderer.when() is an alias to when() function.

Variables

html → {String}

Stores the HTML data of the variant above the script node where the variable is called. Exists only within Variant script nodes.

html

Code example

css → {String}

Stores the CSS content of the variant above the script node where the variable is called. Exists only within Variant script nodes.

html

Code example

Examples

Basic example - render campaign content

Source code for original page:

Use the following campaign script to render campaign content:

The code results in the change highlighted in the example below:

Basic example - identify if a campaign applies to a page

There may be cases where you cannot identify your test page using the URL, for instance when several pages share the same URL. You can validate whether the campaign is applicable to the page using the following steps:

1. Iteratively check whether page-specific content has appeared on the page.
2. As soon as a decision can be made, send a request for a virtual page or finish the process.
3. Apply the campaign to the page if required.

The steps are summarised in the following sample code:

Basic example - get campaign data

You can use an auxiliary campaign module to get campaign-specific data. For example, the campaign.isDefault() method that returns 'true', if all the generated experiences are 'Default'.

See the Campaign module for more information.

Basic example - handle content on AJAX pages

On AJAX pages, content may arrive after the page load event. Use the when() method to wait for the specific element before and after DOM ready.

You can also establish the custom rendering logic. See the following examples:

Advanced example - configure time before campaign content is displayed

To minimize coding errors, the Renderer module automates the process of showing content. You can configure the time that should elapse before content is displayed:

By default, timeout is set to expire 7 seconds after the last .hide() call in a campaign.

Actions

Use the Actions module in campaign and site scripts to capture actions during a campaign and send the information to the Content Generator.

Reference table

Examples

• Track sales amount (basic example)
• Track several actions (basic example)
• Track a postponed action (basic example)
• Advanced click-through action tracking

Methods

postpone( name [, value, attribute] ) → {Actions}

Captures action data to be sent to the Content Generator in subsequent requests.

Parameters

Code example

send( [name, value, attribute] ) → {Promise}

Sends all captured action data to the Content Generator. See the Deferred article for more information on promise.

Parameters

Code example

trackClicks( element, parameters, guid ) → {Actions}

Assigns an On-Click action tracking handler to a DOM node.

Parameters

Code example

set( name [, value, attribute] ) → {Actions}

Captures action data to be sent to the Content Generator when actions.send() is called.

Parameters

Code example

Examples

Basic example - track sales amount

Tracking sales amount:

Basic example - track several actions

Tracking several actions:

Basic example - track a postponed action

Postponed actions are useful for preventing data loss when there is an immediate browser redirect to another page when a visitor leaves a page.

Applying a click handler to track a postponed action:

Advanced click-through action tracking

If there are restrictions on tracking click-through actions on a specific page, you can do the following:

1. Cancel the default behavior of the link or form that is triggered.
2. Pass information about the action to the Content Generator.
3. Replicate the default behavior of the link or form.

Here is an example:

Visitor

Use the Visitor module in campaign and site scripts to retrieve and send visitor data, such as gender or age, to the Content Generator.

Reference table

Examples

• Persistent custom attribute
  
• Custom attribute for a specific campaign

Methods

clearData( name )

Removes custom variable data from persistent storage.

Parameters

Code example

getAttr( name ) → {String}

Retrieves the value of the custom attribute that was saved using visitor.storeAttr().

Parameters

Code example

getData( [name] ) → {*}

Retrieves the custom variable value from persistent storage.

Parameters

Code example

removeAttr( name )

Removes the value of a custom attribute from persistent storage.

Parameters

Code example

requestPage( virtualUrl ) → {Promise}

Sends additional request to Maxymiser Content Generator in order to pass captured on page parameters and retrieve required for testing data.

Parameters

Code example

setAttr( name, value )

Captures custom attribute data to temporary storage to be sent to the Content Generator in subsequent page requests.

Parameters

Code example

setData( name, value [, expires] )

Saves the custom variable value in persistent storage, so it can be retrieved on other site pages using visitor.getData().

Parameters

Code example

storeAttr( name, value )

Saves custom attribute data to permanent storage to be sent to the Content Generator in subsequent page requests.

Parameters

Code example

Examples

Basic example - persistent custom attribute

Use the following code on the registration page:

The 'gender' custom attribute is captured as soon as a visitor registers.

Basic example - custom attribute for a specific campaign

Cookies

Use the Cookies module in campaign and site scripts to integrate with 3rd-party logic. To store data related to testing, use the setData() and getData() methods in the Campaign and Site modules.

Reference table

Methods

get( name ) → {String | undefined}

Reads cookie value.

Parameters

Code example

remove( name [, properties] ) → {Cookies}

Deletes a cookie.

Parameters

Code example

set( name, value [, properties] ) → {Cookies}

Sets a cookie value.

Parameters

Code example

Events

Use the Events module to delegate shared logic to an independent script, so you can have several campaign-specific handlers of visitors' activities. You can also communicate between different scripts using events.

Reference table

Examples

• Shared action tracking
  
• Campaign rendering

Methods

domReady( [callback] ) → {Boolean}

Executes a callback function when DOM is ready. Returns true if DOM is ready, false if page is still loading.

Parameters

Code example

off( name, handler ) → {Events}

Removes event listener from a custom event.

Parameters

Code example

on( name, handler ) → {Events}

Assigns event listener to a custom event.

Parameters

Code example

trigger( name [, data, callback] ) → {Events}

Executes all the handlers assigned to a custom event.

Parameters

Code example

Examples

You can create custom events and assign handlers to internal Campaign Design API events (such as events.domReady) using one of the two scopes of the Events module:

• events - at site and campaign level
• campaign.events - at campaign level only

To use custom event management, first bind the event handlers using events.on before you fire the event using events.trigger.

Basic example - shared action tracking

To aggregate shared logic at site level and create an event called "ConfirmationAction" that will trigger all child confirmation actions for a particular campaign, an example of the code that you can use in a site script is shown:

In a campaign script, you would use the following sample code:

Campaign script from another campaign:

Basic example - campaign rendering

You can use the following sample code in a campaign script to apply campaign conditionally each time an event occurs, for example, specific AJAX content arrives on the page:

And the sample code for the variant would be:

Deferred

Use the Deferred module in campaign and site scripts to manage the results for asynchronous tasks.

Reference table

Examples

• Customize your workflow using deferred objects to manage asynchronous tasks (basic example)
• Customize renderer.when() (advanced example)

Methods

Deferred() → {Deferred}

A constructor function that returns a chainable object which lets you assign callbacks to its state change, and manually change the state in order to trigger those callbacks.

Parameters

None

Code example

promise() → {Promise}

Returns a chainable Promise object which assigns callbacks to the linked Deferred object and observes when the task finishes.

Parameters

None

Code example

always( alwaysCallback [, alwaysCallbacks] ) → {Deferred|Promise}

Adds handlers that are called when the Deferred object is either resolved or rejected.

Parameters

Code example

done( doneCallback [, doneCallbacks] ) → {Deferred|Promise}

Adds handlers that are called when the Deferred object is resolved.

Parameters

Code example

fail( failCallback [, failCallbacks] ) → {Deferred|Promise}

Adds handlers that are called when the Deferred object is rejected.

Parameters

Code example

notify( [data] ) → {Deferred}

Calls the progressCallbacks on a Deferred object with the given args.

Parameters

Code example

notifyWith( context [, data] ) → {Deferred}

Calls the progressCallbacks on a Deferred object with the given context and args.

Parameters

Code example

progress( progressCallbacks ) → {Deferred|Promise}

Adds handlers that are called when the Deferred object generates progress notifications.

Parameters

Code example

reject( [args] ) → {Deferred}

Rejects a Deferred object and calls any failCallbacks with the given args.

Parameters

Code example

rejectWith( context [, args] ) → {Deferred}

Rejects a Deferred object and calls any failCallbacks with the given context and args.

Parameters

Code example

resolve( [args] ) → {Deferred}

Resolves a Deferred object and calls any doneCallbacks with the given args.

Parameters

Code example

resolveWith( context [, args] ) → {Deferred}

Resolves a Deferred object and calls any doneCallbacks with the given context and args.

Parameters

Code example

state() → {String}

Determines the current state of a Deferred object.

Code example

then( doneCallbacks [, failCallbacks] [, progressCallbacks] ) → {Deferred|Promise}

Adds handlers that are called when the Deferred object is resolved, rejected, or still in progress.

Parameters

Code example

Functions

when( Deferred [, Deferreds ] ) → {Promise}
when( condition [, stopCondition ] ) → {Promise}

Provides a way to execute callback functions based on one or more Deferred objects or functions that represent asynchronous event(s). Returns a master-Promise object which lets you assign callbacks to its state change.

Parameters

Deferreds: As soon as all Deferred objects are resolved, done callbacks of the master-Promise are executed; as soon as at least one Deferred object is rejected, fail callbacks assigned to the master-Promise are called

Functions: In case 'condition' function that is being iteratively executed every 50ms returns true, done callbacks of the master-Promise are executed; as soon as 'stopCondition' returns true, fail callbacks are called

Code example

Examples

Basic example - customize your workflow using Deferred objects to manage asynchronous tasks

You can customize your workflow by creating Deferred objects to manage asynchronous tasks:

You can use the when() function to get a similar result by creating a Promise:

Or you can create a Promise using the .promise() method:

Advanced example - customize renderer.when()

There may be cases when you need to customize renderer.when(). For example, to render content right after AJAX content arrives at a page:

Modules

Use Modules in site and campaign scripts to introduce custom functionality into your campaigns.

Reference table

Methods

define( name [, properties], constructor ) → {Modules}

Defines a custom module.

Parameters

Code example

require( name ) → {Module}

Gets the instance of a custom module.

Parameters

Code example

Examples

Advanced example - tracking IFRAME clicks

Use custom modules to create templates for designing campaigns specifically for your site.

Go to the Top