Execute JS let you build ad or creative with custom JavaScript code.  The Bonzai JS API is the hidden backbone which allows developers or anyone with knowledge of JavaScript to create customized creative.

The Bonzai JS API provides you with the flexibility to add vanilla or raw JavaScript code and to modify the creative. You can integrate any third-party javascript library to add additional features.

Work with Execute JS

Execute JS is a powerful code editor with lint feature designed to enhance your productivity in building custom scripts for the creative.

To access the code editor

On the workspace, hover over  and click . The Execute JS window appears.

Execute JS on the workspace

Tip: To expand the editor in the Studio workspace, click .  

When you first open Execute JS, you have one editor file open, by default. But you can add additional files to split your code.

To add a file

On the editor, click  to add a file.

New file — on the code editor

With Execute JS, you can add identifiers to the JavaScript file to reduce confusion and aid in better organization of actions. 

To rename a file

On the editor, double-click the filename, type the required filename and press ENTER.

Renamed file — on the code editor

Tip: Addition of a new file with the ability to rename the file enables you to separate your program into different sections. Separation of concerns simplifies the creative design and development process.

The code editor in Bonzai Studio provides you with an option to understand the code at a glance. Reserved keywords are color-coded.  

The code editor scans or lint the code to analyze code quality before program execution. 

To quickly scan your code

Locate the lint  icon. The icon appears beside the line number. Hover over the icon to get an instant code quality feedback.

Write your script in Execute JS

All scripts added on the Execute JS will be wrapped in an anonymous function with windowdocument, and bz as parameters. You do not have to write the wrapper function. The function is available for your reference.

function (window, document, bz) {
    // statements
}

Function declaration

Points to remember

Here are three things to remember before you customize the creative.

Ad Container

Your code can run in a frame other than the ad container frame. 

Example - For iframe tag, the ad renders in an iframe whereas the JavaScript code runs outside the iframe.

DOM Elements

To select a DOM element, use bz.Creative.getElementById instead of document.getElementById. By default, tags have access to window and document objects.

External Scripts

To add an external library, use bz.Common.loadScripts and then use bz.Common.include to fetch the global reference of the library from the ad container.

The script tag is used to load an external script into the ad container.

Set up Execute JS script 

You need to set up the Execute JS scripts to run on any event on the page or on the elements.

The following section takes you through the process of addition of custom script to an asset (or, image) from the sample creative. 

  1. On the workspace, select an image. A green selection highlight appears on the active asset.

  2. Click 

Events pane

  1. In the Event list, select Click/Tap option. The Action list box appears.

Events pane with the selected event

4. In the Action list, select Execute JS option under RunJS. The Execute JS drop down appears.

Execute JS — Action list option 

5. In the Execute JS box, select your script. 

Custom script written in the code editor

6. Click Add. The script is added to the asset.

In the above example, the custom script executes on asset or image click. Similarly, you can add a listener to the on page load event or ad in view event, or on both to trigger the JavaScript call.

See sample case

Here is a sample scenario where a JavaScript script is used to achieve a customized effect.

‘Shake’ Gesture

In this scenario, we'll use a gesture that is the most common in mobile devices, the shake gesture. We'll use the shake gesture to modify the default page of the creative.

The sample creative contains two pages, separately designed on the Canvas. 

The shake button is assigned a name in the Studio’s Properties pane. To use the element name from the document object, we store it in the nextPage variable.

var nextPage = bz.getElementByName('nextPage').el;

Code snippet to identify the button  

The basic elements on the workspace do not support the shake movement detection out of the box. 

The JavaScript ecosystem has a number of external libraries. In this example, we are using a  shake gesture detection library and importing the library for the creative using bz.Common.loadScripts.

bz.Common.loadScripts([
    "https://cdn.rawgit.com/alexgibson/shake.js/master/shake.js"
])

Code snippet to load the external library 

As mentioned in the Points to Remember section, to add an external library, the following statement is required.

var Shake = bz.Common.include("Shake");

Code snippet to reference the external library

The shakeEvent object is created to detect the shake gesture and pass an anonymous function to select the next page using the click method called inside the conditional statement.

var shakeEvent = new Shake({threshold: 10});
    shakeEvent.start();
    window.addEventListener('shake', function(){
               
        if(!flag){
            nextPage.click();
            flag = true;
        }
    }, false);

Code snippet for the shake gesture listener

The following code block displays the contents of the Execute JS window for the creative.

var flag = false;
var nextPage = bz.getElementByName('nextPage').el;
bz.Common.loadScripts([
    "https://cdn.rawgit.com/alexgibson/shake.js/master/shake.js"
]).then(function () {
    "use strict";
    //listen to shake event
    var Shake = bz.Common.include("Shake");
    var shakeEvent = new Shake({threshold: 10});
    shakeEvent.start();
    window.addEventListener('shake', function(){
               
        if(!flag){
            nextPage.click();
            flag = true;
        }
    }, false);

    //stop listening
    function stopShake(){
        shakeEvent.stop();
    }

    //check if shake is supported or not.
    if(!("ondevicemotion" in window)){console.log("Not Supported");}
});

JavaScript code for shake gesture detection

For the specific format, there are two events, the page load event and the ad in view event. Both the events can be used to trigger actions.

In this scenario, we are adding an on page load event to call the script written on the Execute JS window.

Setting up the action pane using the Execute JS file

On Page Load - refer the Execute JS: Doc0 file

Now, the setup is complete. You can preview the creative in a mobile device and shake the device to view the additional message in the creative.

Preview Link

On the preview window, click . The QR code of the creative preview appears. You can scan the QR to get a live preview of the creative on your mobile device

To dive deeper into the internals of the Bonzai JS API, check out our API document given below.

Bonzai_JS_API_ Documentation.pdf