What is Smart Versioning?
Smart Versioning is a feature that enables you to create ads that contain dynamic elements (text, images, and so on). Multiple versions can then be created in the platform just by modifying these dynamic elements. For example, you can create an ad that changes daily depending on which day of the week it is. The text, image and video can change accordingly.
The workflow to create a Smart Versioning ad is as follows:
- Upload workspace to the Sizmek platform and create ad.
- In the platform, create new versions of the ad with a few clicks.
- Edit the new versions. Any content that was defined as "Smart" content can be changed to your needs.
- For example, if you created an ad called: "Holiday Sale", then create more versions of that ad, you can change the new versions' content quickly, in a spreadsheet-like workflow. The versions can then be configured to target according to the day of the week and the sale of the day, for example, "Monday Holiday Electronics Sale".
For a brief overview of Sizmek's Smart Versioning, visit this link: HOW TO: Add Smart Versioning Functionality to Your HTML5 Ads Using Workspaces
Important: This document assumes you are already familiar with the basics of using Google Web Designer (GWD) to create Sizmek compatible ads. Please refer to the document HOW TO Build a Sizmek Compatible Google Web Designer Ad for this information.
Important: A starter-kit comes preloaded with samples of Smart Versioning elements to help you understand their usage with GWD. Sizmek_GWD_Smart_Versioning.zip
Required Files for Smart Versioning
Sizmek's Smart Versioning starter-kit project contains various files: html, script and asset (image, audio, video) files. The following two files are required to configure your ad for smart versioning. They are located in your ad's root directory:
The ad's main creative file. Includes a reference to AdKit.
The config.js file includes the Smart Versioning ad configuration. It is the main configuration file of the Creative AdKit
AdKit is the Sizmek runtime delivery system. It is necessary to be included in the project's index.html file. AdKit is responsible for reading the configuration information contained in config.js, then following the instructions dictated there to make the ad dynamic. In code view, at the bottom of the file, you should see the adKit reference, like this:
If it's not there, you can copy/paste the below:
Types of Dynamic Data that can be used in HTML5 Ads
HTML5 Smart Versioning currently supports the following dynamic data types:
- HTML Components (a.k.a. adkit-HTML) - HTML code fragments which are automatically inserted into <div> tags in the ad's index.html file.
Understanding the config.js file
The config.js file contains the smart versioning schema of an HTML5 ad.
Developers can use two types of dynamic data, both configured through config.js:
- Map <div> tags from your index.html file to items in your config.js file, to automatically update the index.html with dynamic adkit-HTML data
The config.js file contains two sections:
An "ITEMS" section
This section designates <div> tags from the ad's index.html file, telling AdKit that they will be populated with Smart Versioning data.
- In our starter-kit, an AdKit item with the id "ThePrice" is defined. This item therefore correlates to a <div> tag with id "ThePrice" inside our ad.
- The "ThePrice" item is of HTML type ("adkit-html")
- This item is linked to a Smart Versioning element with the svKey "Price"
An "SV" section
- This section defines the actual Smart Versioning data for the elements.
Smart Versioning Examples Included in Starter-Kit
There are three examples of Smart Versioning items included with the starter-kit.
- Basic Text Element
- Graphic image
Basic Text Element
In the starter-kit you have open, locate the text item with the name/id "ThePrice". Let's focus on this element.
In order for the Sizmek Platform to load this as a Smart Versioning item, it needs to be referred to in the config.js file. Our starter-kit comes pre-loaded with data (see config.js image in previous section).
Experiment with changing the svData "Price" value and reloading the ad. The value set in the config.js file will be the default Smart Versioning value when uploaded to the platform.
To test Smart Versioning, verify the value of "Price" in the config.js file, then preview it locally.
Important: When you preview locally, GWD creates a directory in your project's root directory with the prefix gwd_preview_. In order for the SV data to be read during preview, the config.js file needs to be inside this directory, so make sure to copy it in there. The first time through this, you'll probably need to restart the preview.
Graphic Image Element
We'll implement the clickthrough button as an image to illustrate how to use an SV image field. The first thing we need is a placeholder div to hold the image:
As with the previous example, the element has an ID which can be found in the properties tab. We've set it to "TheImage", so we refer to it that way in the config.js file.
Add the path to where your image live when ad is running. During preview, GWD moves all the assets into the root of the preview directory. Therefore, in config.js we should use button.png instead of assets/button.png.
Use the local preview to test it. Notice the div placeholder now contains our image (and "ThePrice" text as well).
Reminder: The config.js file needs to be manually copied into preview directory, so make sure to do that manually, then restart preview if you need to.
- Switch to code view.
- Add the following code snippet at the line indicated in the image:
Prepare Workspace for Upload
Important: A Workspace is a directory that contains an index.html file which has a reference to adkit.js in it.
- Save your project.
- Publish your project. Be sure to choose "Publish Locally".
Make sure CSS prefix checkboxes are checked, but Create Zip and Minify are unchecked, then click blue Publish button.
- Now you should have a directory that is packaged, optimized and almost ready for upload. It will be in your project's directory (unless you changed its destination location).
- Copy your config.js file into published directory.
- Add a default image. All ads served on Sizmek must have a default image within the workspace folder.
The default image must be the exact dimensions of your ad. Once uploaded to the platform, the dimensions of the ad are determined by the dimensions of the backup image.Copy your default image into your published directory.
Your published directory should now look like:
- That's it, you're done. Now, zip up the published directory and upload!
Note: For detailed information on how to upload workspaces please refer to our help section here.
- Once your ad is uploaded, preview it and double check that all the analytics events fire, and SV data shows through in the ad as you would expect.
- You can now create multiple versions of your ad in the Smart Versioning section of Ad Edit page: