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.
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.
Creative AdKit Ebloader declaration code
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).
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);
Test your ad to see that this transition is successful, and that your ad previews and serves correctly.
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
Note You can use both Adkit data and Variables in the same ad.
Option 1: Configure the Dynamic Data Components in the config.js File
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.
Configure an Adkit-HTML Component
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.
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.
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.
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.
Configure an AdKit-Image Component Using a URL
You can add Dynamic Creative to images saved under a specific URL.
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.
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 }, |
Click to view the config.js Properties
Section |
Description |
Items |
Items |
This section designates tags from the ad’s index.html file and updates AdKit with the populated Dynamic Creative data. |
|
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.
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.
Configuring an Adkit-Image Component Using Additional Assets (Applies only to the MDX 2.0 platform)
Additional assets for Workspaces have unique characteristics. For more information, see Uploading and Managing Additional Assets for WorkspacesUploading and Managing Additional Assets for Workspaces
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.
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" }] }); |
Click to view the config.js Properties
Section |
Description |
Example |
ITEMS |
This section designates tags from the ad’s index.html file, updating theAdKit with the populated Dynamic Creative data. |
|
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. |
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/.
Validate that the ITEMS you defined in the config.js file correspond with the divs in the index.html file.
-
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.
Option 2: Configuring Dynamic Creative Variables Using the API
Dynamic Creative variables can be added anywhere within the ad JavaScript code and are retrieved using the AdKit API.
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
svType – 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.
Example |
|
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) |
Use Case: Combining adkit-HTML Components and Variables in config.js.
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> |
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.
Comments