Add Dynamic Creative Functionality to Your HTML5 Ads Using Workspaces – Sizmek Help Center

Overview

This article describes how to manually define Dynamic Creative (DCO) for HTML5 ads that are uploaded to Sizmek MDX by using Workspaces. This procedure is performed prior to uploading your HTML5 ad to the platform in your Workspaces.

Ad developers use Dynamic Creative to create ads that contain dynamic content. After a Dynamic Creative ad is uploaded to the platform, the ad's content can be manipulated through the platform to create different versions of the master ad, without changing the original creative files.

The HTML5 Dynamic Creative (DCO) feature uses the Sizmek Ad Suite (SAS) Creative AdKit Suite for HTML5 ad developers, which contains ad-related functionalities that provide quick and easy development of your HTML5 ads. The SAS Creative AdKit Suite implements HTML5 Dynamic Creative with the following dynamic data types, which are part of the SAS Creative AdKit Suite:

HTML Components (such as adkit-HTML): HTML code fragments that are automatically inserted into tags in the ad’s index.html file.
Variables: String variables that are accessible for use by the ad’s javascript code. The AdKit API retrieves values for these variables. An HTML5 ad’s Workspace contains various files: html, script and asset (image, audio, video) files.

Adding Dynamic Creative to HTML5 ad requires configuring and placing the following files in the root folder of the Workspace.

Field	Description
Index.html	The ad’s main creative file. Includes the AdKit script that runs the config.js.
config.js	The config.js file includes the Dynamic Creative ad configuration. This serves as the main configuration file of the Creative AdKit.

Perform the following workflow to add Dynamic Creative items to your HTML5 ad.

Add the Creative Adkit Declaration to the Index.html File

The Creative AdKit declaration replaces the standard EBLoader declaration. This action automatically updates the index.html with dynamic adkit-HTML data when the ad is served.

Open index.html in a text editor.
Add the Creative AdKit Ebloader declaration code to the index.html file which replaces the existing EBloader declaration. If you are using the following EBloader declaration, replace this declaration because AdKit references the EBLoader, while retaining all the existing EBLoader functionality.
```
http://ds.serving-sys.com/BurstingScript/adKit/adkit.js
```
Add the AdKit load-wait code which replaces the EBLoader load-wait code.

Many ads use EBLoader APIs to perform a variety of actions, and include code which waits for EBLoader to load before referencing any API functions.

The EBLoader code segment usually looks like this: (In this example, "startAd" is the name of the JS function which executes after EBLoader has loaded).
```
if (!EB.isInitialized()){

EB.addEventListener(EBG.EventName.EB_INITIALIZED, startAd);

}else{

startAd();

}
```
Replace with the following AdKit load-wait code.
```
adkit.onReady(startAd);
```
Test your ad to see that this transition is successful, and that your ad previews and serves correctly.

Configure the Dynamic Creative Elements in Your Ad

The config.js file contains the HTML5 ad Dynamic Creative schema which is configured using dynamic data types. You can either add one or both of the following dynamic data types to the config.js file:

Option 1: Map tags from your index.html file to items in your config.js. file, to automatically update the index.html with dynamic adkit-components.
Option 2: Define Dynamic Creative Variables inside your config.js file, and use the AdKit API to access these variables inside your Java Script code.

Note

Note You can use both Adkit data and Variables in the same ad.

The following dynamic data components can be configured in the config.js file.

Note

Note: You can use both Adkit data and Variables in the same ad.

Procedure

Open a text editor and create a file named config.js.
Add a JSON object to your config.js, as displayed in the following example.
```
define(  
{      
 "ITEMS": [ 
            {                    
 "id": "BookPrice",                    
 "type": "adkit-html",                    
 "svKey": "Price"              
 } 
 ],     
 "SV": {                 
  "svData":    [                                      {                   
 "svKey": "Price",                   
 "svType": "html",                 
 "value": "7.99"      
              }        
    ]  

   }
});
```
The following sections are described as follows:
- The ITEMS section.
  
  This section designates tags from the ad’s index.html file, telling AdKit that they will be populated with Dynamic Creative data.
  In the above example:
  - An AdKit item with the id "BookPrice" is defined. This item, therefore, correlates to a tag with an ID of "BookPrice" inside index.html file.
  - The "BookPrice" item is of an HTML type ("adkit-html"). This item is linked to a Dynamic Creative element with the svKey (Dynamic Creative Key) "Price".
- The SV section.
  
  This section defines the Dynamic Creative elements. An element named "Price" is of an of "HTML" type, with the default value of "7.99" is defined.
Note

Note: Ensure your 'Value' field is configured with UTF-8 Encoding when applying any of the following languages: Greek, Swedish, Spanish or Russian.
Validate the JSON code, by copying the JSON section, (excluding the "define();" wrapper), to an online JSON Parser, such as http://json.parser.online.fr/.
Validate that the "ITEMS" you defined in the config.js file correspond with the divs in the index.html file.

In the following example, the "BookPrice" adkit-html item corresponds with the following '' in the index.html file. As a result, once the ad is served, the value defined in the "Price" svKey is inserted automatically into the "BookPrice" div. This value is dynamic, and will be different for every SV/MV version of the ad. The ad versions are created on using the SV or MV mechanisms.
```
<div id="BookPrice" style="width: 100%; height: 100%; layout: absolute; "> </div>
```
When the ad is served, the data flow is: 1 The value of the Price (svKey) for the served version -> 2 BookPrice AdKit Item > 3 BookPrice inside the index.html.

You can add Dynamic Creative to images saved under a specific URL.

Procedure

Open a text editor and create a file named config.js.

Add a JSON object to your config.js, as displayed in the following example.

define(  
{      
 "ITEMS": [   
            {                    
 "id": "logo_div",   
 "type": "adkit-image", 
 "svKey": "imgURL"   
            } 
 ],     
 "SV": {                  
 "svData":    [                                      {                   
 "svKey": "imgURL",             
 "svType": "image",      
 "value": http://br.eyeblaster.com/wp-content/uploads/2014/02/homepage_welcome-to-sizmek.png         
  },

Section	Description	Items
Items	This section designates tags from the ad’s index.html file and updates AdKit with the populated Dynamic Creative data.	The logo_div AdKit item is assigned an ID. This item correlates with the "logo_div" ID located in the index.html file. The logo_div item is an image type (adkit-image). This item is linked to a Dynamic Creative element with the svKey (Smart Versioning Key) "imgURL".
SV	This section defines the Dynamic Creative elements. An element named imgURL is of an of Image type, leading to an image located in the following URL: http://br.eyeblaster.com/wp-content/uploads/2014/02/homepage_welcome-to-sizmek.png is defined.

Validate that the ad is viewable by running the local preview by double-clicking on the index.html file.

If preview fails, perform the following steps:
1. Validate the JSON code, by copying the JSON section, (excluding the "define();" wrapper), to an online JSON Parser, such as http://json.parser.online.fr/.
2. Validate that the ITEMS you defined in the config.js file correspond with the divs in the index.html file.

Additional assets for Workspaces have unique characteristics. For more information, see Uploading and Managing Additional Assets for Wordspaces.

Procedure

Create a dedicated AdditionalAssets folder and copy your additional assets to it. Do not save images within subfolders in this folder.
Open a text editor and create a file named config.js.

Add a JSON object to your config.js, as displayed in the following example.

   define({
       "ITEMS":[
             {
                 "id": "Image_Car_div",
                 "type": "adkit-image",
                 "svKey": "myImage"
              }
    ],        
       "SV": {
                "svData": [{
                "svKey": " myImage ",
                "svType": "Image",
                "value": "2"
              }]
            },
                "AdditionalAssets":[{
                "OrdinalNumber": 2,
                "FileName" : "Mazda_2Maxxsport.png"  
              }]
 });

Section

Description

Example

ITEMS

This section designates tags from the ad’s index.html file, updating theAdKit with the populated Dynamic Creative data.

An AdKit item with the id "Image_Car_div" is defined. This item correlates with the "Image_Car_div" ID located in the index.html file.
The "Image_Car_div" item is an image type ("adkit-image"). This item is linked to a Dynamic Creative element with the svKey (Dynamic Creative Key) "myImage".

This section defines the Dynamic Creative elements. An element named "myImage" is of an of "Image" type.

An element named "MyImage" is of an of "Image" type.

In the example: Mazda_2Maxxsport.png asset has been assigned ID 2. ID2 is used when configuring the svData values.

Dynamic Creative variables can be added anywhere within the ad JavaScript code and are retrieved using the AdKit API.

Procedure

Open a text editor and create a file named config.js.
Define an SV element. An SV element has the following properties:
- svKey – the ID of the SV element
- vType – html, image, video, or string
- Value – The value of an SV element is determined by the Platform for each specific version. The config.js file contains the default value.
  
  Refer to the syntax in the following example to define a JSON object in your config.js file, which includes an "SV" section.
```
define({

"SV": {

"svData": [

{

"svKey": "varName",

"svType": "string",

"value": "War and Peace"

}

]

}

});
```
Validate that the code is correct by copying the JSON section (excluding the "define();" wrapper), to an online JSON Parser, such as http://json.parser.online.fr/.

Retrieve the variable data using the AdKit API.

Follow the JavaScript function example to invoke the AdKit API and retrieve variable data.

function handleSVData(data) {
                        var myData = adkit.getSVData("varName");
                       // your JS code which uses the variable value 
        }

   adkit.onReady(handleSVData);

This JavaScript code uses the following two AdKit API methods.

Method	Description	Syntax
adkit.onReady	Waits for AdKit to initialize and runs a callback function.	adkit.onReady(CallbackFunctionName);
adkit.getSVData	Retrieves the value of a Dynamic Creative variable by svKey.	adkit.getSVData(svKey)

The following example uses a combination of both Dynamic Data Types, namely an html component and a variable.

 define({         "ITEMS": [
             {
                    "id": "BookPrice",
                     "type": "adkit-html",
                     "svKey": "Price"
             }
   ],
   "SV": {
           "svData": [
           {
                     "svKey": "Price" , 
                     "svType": "html",
                     "value": "7.99" 
            },
            {
                     "svKey": "varName",
                     "svType": "string",
                     "value": "War and Peace"
              }              ] 
          }  });

The following is an index.html example. An index.html file can contain both variables and HTML components.

<!DOCTYPE html>
<head> <script type="text/javascript" src=" http://ds.serving-  sys.com/BurstingScript/adKit/adkit.js"></script>
  <script>
                  function handleSVData(data)
                             {var myData = adkit.getSVData("varName");
                              // your JS code 
                   }
                  adkit.onReady(handleSVData);</script></head>

<body style='margin: 0px; padding: 0px'> 
           <div id="BookPrice" style="width: 100%; height: 100%; layout: absolute; "></div>
                /* any other div elements */
</body>
</html>

Upload the Workspace to the SAS Platform

Procedure

Verify that the index.html and config.js are located in the root directory.

Place all ad assets, and a default image, into a folder.
Compress your folder to a ZIP file.
Upload the ZIP to SAS and create an ad based on that Workspace.

Test Dynamic Creative Functionality in Your HTML5 Ad

The Dynamic Creative tab contains the HTML and variable items that you defined in config.js. After you create an ad based on your uploaded workspace, you can test the Dynamic Creative functionality. Note that an ad is uploaded as a Single Versioning ad by default, but can be converted to a Mass Versioning ad through the platform.

The Dynamic Creative tab should contain the HTML and variable items defined in config.js.

Procedure

Click the Dynamic Creative tab.
Preview the ad and verify that you can create versions for it by using the platform

Overview

Add the Creative Adkit Declaration to the Index.html File

Configure the Dynamic Creative Elements in Your Ad

Note

Note

Note

Upload the Workspace to the SAS Platform

Test Dynamic Creative Functionality in Your HTML5 Ad

Comments