Execute JS let you build ad or creative with custom JavaScript code. The Bonzai JS API is the hidden backbone that 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 3 dots ( More icon ) and click Execute JS icon.
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 + icon 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 window, document, 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.
On the workspace, select an image. A green selection highlight appears on the active asset.
Click Events
3. In the Event list, select Click/Tap option. The Action list box appears.
4. In the Action list, select Execute JS option under RunJS. The Execute JS drop down appears.
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
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.
On the preview window, click on
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.