Add dynamic elements to your HTML ads using a code editor – Amazon Ads Help Center

Note

Note: To learn more about Dynamic Creative Optimization (DCO), or to view guides about other authoring tools, see Introduction to dynamic creative.

Overview

The following sections describe how to define dynamic elements manually for HTML ads that are hand-coded in a code editor.

The Dynamic Creative feature uses the Amazon Ad Server (AAS) creative AdKit for developers. AdKit includes ad-related functionalities that provide quick and easy development of your HTML ads.

Important

Important: Make sure to properly load the AdKit API before building your dynamic creative. For more information, see Load and Initialize the API.

AdKit implements Dynamic Creative with the following dynamic data types:

HTML Components: HTML code fragments that are inserted automatically into HTML 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.

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

File	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, and serves as the main configuration file for the creative AdKit.

Configuring Dynamic Elements

Use one or both of the following methods to configure dynamic data types:

Method A: Define variables inside your config.js file, and use the AdKit API to access these variables inside your JavaScript code.
Method B: Map HTML tag IDs from your index.html file to items in your config.js file, to automatically update the index.html with dynamic adkit-components.

You can use both methods in the same ad.

Example

The following example uses both methods to demonstrate how to convert a div that has the ID BookPrice into a dynamic element.

Procedure

Open your index.html file.
Create a div with the ID BookPrice.
```
<div id="BookPrice">
</div>
```
Save your file.

Before starting to configure the dynamic elements, create a div, and make sure its ID is defined.

Important

Important: Please note that if you are using a dynamic video element, it will be tracked automatically. You should not manually include or initialize the Video Module, as this can result in duplicate tracking of video progress and events.

Define variables inside your config.js file, and use the AdKit API to access these variables in your project.

You can add variables for dynamic elements anywhere within the ad's JavaScript code. Dynamic elements are retrieved using the AdKit API. The following table describes the types of dynamic elements.

SV: svData	Description
string	To create a Dynamic Element based on a string (raw text).
html	Create a dynamic element based on an HTML string.
image	Create a dynamic element based on an image.
video	Create a dynamic element based on a video.

Procedure

Open your config.js file.

Add a JSON object to your file, as shown in the following example:

define(
{
    "SV": {
        "svData": [{
            "svKey": "dynamicPrice",
            "svType": "html",
            "value": "<b>7.99</b>"
        }]
    }
}
);

Save your file.

Note

Note: To validate your JSON code, copy the JSON section to an online JSON parser. Before running the test, make sure that you exclude the define(); wrapper. In our example, it is the first and last lines of the code.

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

function handleSVData(data) {
    document.getElementById("BookPrice").innerHTML = adkit.getSVData("dynamicPrice");
}
adkit.onReady(handleSVData);

The JSON object in our example includes this section:

SV: Defines the dynamic elements, svData. An element named dynamicPrice is of an html string type, with the default value of 7.99 that will display in bold thanks to the html <b> tag
- svKey: ID of the dynamic element.
- svType: An element named dynamicPrice is of an html string type.
- value: The complete list of values that a dynamic element can be populated with is defined later in AAS , for each specific version. The config.js file simply includes the first possible/default value, 7.99.
  
  Note
  
  Note: Make sure that you use UTF-8 Encoding.

The JavaScript function uses the following AdKit API methods. For more information about these methods, see 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)`

In our example, when AdKit is ready, the getSVData function retrieves the value of the dynamic element (svKey) called dynamicPrice, which is inserted automatically into the BookPrice div. Once the ad is served, this value is different for each ad version.

You can add the dynamic element in the ad's config.js file by referencing the relevant div id. The following table describes the types of dynamic elements.

Items: Type	SV: svData	Description
Not required	string	To create a Dynamic Element based on a string (raw text).
adkit-html	html	Create a dynamic element based on an HTML string.
adkit-image	image	Create a dynamic element based on an image.
adkit-video	video	Create a dynamic element based on a video.

Procedure

Open your config.js file.

Add a JSON object to your file, as shown in the following example:

define(
{
    "ITEMS": [{
        "id": "BookPrice",
        "type": "adkit-html",
        "svKey": "dynamicPrice"
    }],
    "SV": {
        "svData": [{
            "svKey": "dynamicPrice",
            "svType": "html",
            "value": "<b>7.99</b>"
      }]
   }
}
);

Save your file.

Note

Note: To validate your JSON code, copy the JSON section to an online JSON parser. Before running the test, make sure that you exclude the define(); wrapper. In our example, it is the first and last lines of the code.

The JSON object in our example includes these sections:

ITEMS: Assigns the ID of the HTML tags from the ad’s index.html file, and notifies AdKit that the listed items will be populated with dynamic data.
- An AdKit item with the ID BookPrice is defined. This item correlates to an HTML tag with the ID BookPrice inside the index.html file.
- The BookPrice item is of an html string type adkit-html.
- This item is linked to a dynamic element with the svKey (Dynamic Key) dynamicPrice.
SV: Defines the dynamic elements, svData. An element named dynamicPrice is of an html string type, with the default value of <b>7.99</b> that will display in bold due to the html <b> tag.
- svKey: ID of the dynamic element.
- svType: An element named dynamicPrice is of an html string type.
- value: The complete list of values, with which a dynamic element can be populated, is defined later in AAS for each specific version. The config.js file simply includes the first possible default value, <b>7.99</b>.
  
  Note
  
  Note: Make sure that you use UTF-8 Encoding.

Creating Ad Versions in Amazon Ad Server

Once you upload your ad to AAS , the Versions tab is available from the Ad Setup page. The Versions page includes the HTML and variable items that you defined in the config.js file. For more information about versioning, see Work with versions of a dynamic creative ad.

Note

Overview

Important

Configuring Dynamic Elements

Example

Important

Note

Note

Note

Note

Creating Ad Versions in Amazon Ad Server

Comments