Follow

Overview

This article describes how to manually define Dynamic Creative (DCO) for HTML5 ads that are uploaded to Sizmek’s MDX platform 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 Creative AdKit Suite for HTML5 ad developers, which contains ad-related functionalities that provide quick and easy development of your HTML5 ads. The Sizmek Creative AdKit Suite implements HTML5 Dynamic Creative with the following dynamic data types, which are part of the Sizmek 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.

Procedure
  1. Open index.html in a text editor.
  2. 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.

    Creative AdKit Ebloader declaration code

     http://ds.serving-sys.com/BurstingScript/adKit/adkit.js

  3. 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).

    EBLoader load-wait code

       if (!EB.isInitialized()){
                EB.addEventListener(EBG.EventName.EB_INITIALIZED, startAd);
                     }else{
                            startAd();
       }   

    Replace with the following AdKit load-wait code.

    AdKit load-wait code

      adkit.onReady(startAd);   

  4. 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. This is described in the following 'Configure and Apply a Dynamic Creative Variable' section. 

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: You can use both Adkit data and Variables in the same ad.

Procedure
  1. Open a text editor and create a file named config.js.
  2. Add a JSON object to your config.js, as displayed in the the following example. 

 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: Ensure your 'Value' field is configured with UTF-8 Encoding when applying any of the following languages: Greek, Swedish, Spanish or Russian.

  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.

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 the using the SV or MV mechanisms. 

 Example

<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
  1. Open a text editor and create a file named config.js
  2. Add a JSON object to your config.js, as displayed in the following example. 

 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.  
  1. 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.
  2. 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/.
  3. 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 OVERVIEW: Uploading and Managing Additional Assets for Workspaces.

Procedure
  1. Create a dedicated AdditionalAssets folder and copy your additional assets to it. Do not save images within subfolders in this folder.
  2. Open a text editor and create a file named config.js.
  3. Add a JSON object to your config.js, as displayed in the following example. 

 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".
 SV 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.
  1. Validate that the JSON code runs correctly, 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.
  3. Create a zip file that includes the Workspace and the Additional Assets folder.
    After the Workspace is uploaded to the platform,  the AdditionalAssets folder is automatically created and viewable by all users. The AdditionalAssets folder is parallel to the Workspace folder. The Workspace name is added as a prefix to the asset folder's name as follows: <Workspace Name>_AdditionalAssets. 

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

Procedure
  1. Open a text editor and create a file named config.js.
  2. Define an SV element. An SV element has the following properties:
    •  svKey – the ID of the SV element
    • svType – html 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. 

 Example

    define({   
                "SV": {
                "svData": [
                {
                   "svKey": "varName",
                   "svType": "string",
                   "value": "War and Peace"
                }

              ]
           }
   });
  1. 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/.
  2. 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.

Example: Combining adkit-HTML Components and Variables

  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"
              }              ]
          }  }); 

 

Index.html Example

An index.html file can contain both variables and HTML components. 

 Example

<!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 Sizmek Platform

Prerequisites

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

Procedure
  1. Place all ad assets, and a default image, into a folder.
  2. Compress your folder to a ZIP file.
  3. Upload the ZIP to the Sizmek MDX platform 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.

Procedure

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

  1. Select the "Dynamic Creative" tab.
  2. Preview the ad and verify that you can create versions for it by using the platform

 

Was this article helpful?
2 out of 5 found this helpful
Have more questions? Submit a request

Comments