Create a deluxe banner in a code editor – Amazon Ads Help Center

Note

Note: To learn more about this format, preview a demo, or to see build guides for other authoring tools, see About deluxe banner.

Creating an ad using an Amazon Ad Server template

When creating a deluxe banner in a code editor, it is recommended that you start with our official template bundle.

Files within the bundle:

README.txt

Amz_DeluxeBanner_1_0_1.zip

Amz_DeluxeBanner_1_0_1_DCO.zip

Amz_DeluxeBanner_1_0_1_Video.zip

Amz_DeluxeBanner_1_0_1_Video_DCO.zip

When you download the workspace, extract the file and make sure to preserve the structure of the directory.

deluxe banner functionality is programmed in the template files. At a minimum, the only changes you will need to make are to the loaded images and video assets, and their respective styles.

Note

Note: When updating or replacing images or videos, make sure to also update references to their file names and dimensions found in the index.html, style.css, and script.js files.

Included files

The following table describes the list of files that are included in the downloadable template.

File Name	Description	Required
`index.html`	HTML file for the banner.	Required
`config.js`	Configuration/manifest file for the ad. Used for actions such as default ad settings, and dynamic creative.	Required
`styles/style.css`	Style sheet for the banner and its HTML elements.	Required
`scripts/script.js`	JavaScript (logic and tracking) for the banner.	Required
`images/logo.png`	Amazon Ad Server logo. Replace this logo with your own logo, or delete this image if it is not needed.	Optional
`images/defaults.jpg`	Fallback image shown in unsupported browsers.	Required

Additional Files in the video template

File Name	Description	Required
`videos/video.mp4`	Temporary video that you should replace with your own video.	Required
`images/poster.jpg`	Poster image displayed in the video location in the banner before the video starts and after the video ends.	Optional

Test your deluxe banner locally

You can test your banner by opening the index.html files in your current modern browser. By changing the size of the browser window, you can get a sense of how the design will look at different sizes. However, this is not a reliable representation of how the ad will behave on a publisher's page. This will depend on the layout of the publisher's page and the custom variable settings.

Setting up your ad in Amazon Ad Server

After you finish creating your ad, proceed to setting up your ad in AAS. For more information, see Set up a deluxe banner.

Additional resources

Preparing for bulk upload

If you are planning to upload multiple ads, make sure that the Ad Creation Wizard in AAS recognizes your workspace as a deluxe banner. Verify that the config.js file contains the following JavaScript:

define({
    "adFormatId": 10366
});

For more information about uploading ads in bulk, see Set up multiple ads using Ad Creation Wizard.

Shared libraries

If you are developing ads with third-party libraries, we recommend that you call these libraries from a CDN (Content Delivery Network) when possible. This will help improve loading time and caching.

Dynamic Creative Optimization

If you need to add Dynamic Creative Optimization (DCO) elements to your creative, see Add dynamic elements to your HTML ads using a code editor.

Advanced configuration

The following sections describe common methods to use to customize your deluxe banner.

Responsive banners

A responsive banner resizes to fill whatever space is available on the screen. To create a responsive banner, set mdResizeBehavior to responsive. To ensure that your design never displays in an unsupported size, set minimum and maximum heights and widths.

Adaptive banners

An adaptive banner snaps to different preset sizes based on the available space. Set mdResizeBehavior to adaptive to make an adaptive banner. The ad will use the largest size that was set in the mdAdaptiveBreakpoints variable to attempt to resize itself to fit in the designated area.

The following describes the ways in which you can use the mdAdaptiveBreakpoints variable to the select the adaptive sizes:

If you want the ad to snap to predefined width values, for example, 300, 600, 900, 1200, set only the width breakpoints, and use the minimum height custom variable for the height. When the space that is available is greater than or equal to a breakpoint width, the ad will show that breakpoint width size.
Set specific width and height values for each breakpoint, for example, 300 x 250, 600 x 400, 900 x 750,1200 x 800. When the width available is greater than or equal to a breakpoint width, the ad will change to the width and height size set for that breakpoint.

If the space that is available is less than the smallest defined breakpoint width, the ad will use the values in the mdMinimumWidth and mdMinimumHeight custom variables as its size.

Fixed-sized banners

Perform the following procedure if you want the banner to display at a specific height and width.

Procedure

Set mdResizeBehavior to fixed.
Use the mdFixedHeight and mdFixedWidth custom variables to set a fixed and width.

Modify height and width dependencies

Use the width and height dependency custom variables when you want the banner to resize itself based on different options.

mdWidthDependency and mdHeightDependency are custom variables that you can use to determine the basis for the ad's resizing. Possible values include the following:

advertiserDiv: Ad changes width or height according to the current width of the element that contains the ad.
browser: Ad resizes according to the width of the browser window.
aspectRatio: Dimension adjusts itself proportionally according to the other dimension of the ad, and the value set for the mdAspectRatio variable.
fixed: Dimensions use the value set in the mdFixedHeight or mdFixedWidth variables.
CSS selector: Dimension is according to the element on the page that includes the CSS selector.
- Responsive ads usually resize to the same size as the element that is selected as the dependency.
- Adaptive ads use the largest adaptive breakpoint that is less than or equal to the size of the element that is selected as the dependency. The ad uses width rather than height; therefore, the height dependency custom variable is not as useful for adaptive banners.

Detect scroll position

The templates include a function that tracks the current scroll position. When the ad first loads, the current scroll position is received. On any scroll, resize, or orientation change, the new scroll position is updated.

You can access the current scroll position, scrollPos.x and scrollPos.y, in the creative script.js file from the global object and properties. Values are from 0 to 100 (percentage scrolled).

To include code that adjusts positioning when the scrollPositioning is updated, add your code in the onPageScroll function in the script.js file.

Note

Note: In some instances, there are network issues that cause the scroll detection code to fail. Make sure that you include a backup functionality for the scroll position.

Manifest configuration file

The manifest file,config.js, is a metadata file that defines certain default behaviors for an ad that is created in AAS. For more information about the manifest configuration settings, see Manifest Ad Data.

The config.js file is located in the root folder of the workspace. The file includes the predefined default settings needed for your deluxe banner. Depending on your requirements, you can modify these settings.

Important

Important: Do not modify the value for adFormatId. If the value is changed, the ad will not function correctly.

The following table describes the custom variables in the deluxe banner.

Variable name in AAS

(variable key in config.js)

Description

Type

Default and accepted values

Resize behavior

(mdResizeBehavior)

Determines whether the ad resizes responsively, adaptively, or stays a fixed size.

Note

Note: responsive_adaptive behaves responsively with respect to width, and adaptively with respect to height. Breakpoints are only used with adaptive and responsive_adaptive ads.

String

Default: Responsive

Accepted:

responsive
adaptive
fixed
responsive_adaptive

Alignment

(mdAlignment)

Determines whether the banner is justified center, right, or left.

String

Default: Center

Accepted:

center
c
right
r
left
l

Animate resize

(mdAnimateResize)

Determines whether the ad animates as it changes size.

Boolean

Default: No/false

Accepted:

Yes/No
true/false

Adaptive breakpoints

(mdAdaptiveBreakpoints)

Sets the adaptive breakpoints the ad uses when determining whether to resize.

The default value only sets width breakpoints.

Breakpoints are only used when mdResizeBehavior is set to adaptive or responsive_adaptive.

String

Default:

300
600
900
1200

Accepted: Comma delimited integers, which can also be separated by x's to specify specific heights, such as 300 x 600, 600 x 900.

Width dependency

(mdWidthDependency)

Determines which element on the site dictates the available width for the ad.

String

Default: advertiserDiv

Accepted:

advertiserDiv or 1
browser or 2
aspectRatio or 3
fixed or 4
Any CSS selector

Height dependency

(mdHeightDependency)

Determines which element on the site dictates the available height for the ad.

When setting to advertiserdiv_adaptive, the mdAutoHeightThreshold variable determines when the height should be treated as advertiserdiv, and when it should be treated as adaptive.

String

Default: advertiserDiv

Accepted:

advertiserDiv or 1
browser or 2
aspectRatio or 3
fixed or 4
advertiserDiv_adaptive or 5
Any CSS selector

Auto height threshold

(mdAutoHeightThreshold)

This variable is only used when setting mdHeightDependency to advertiserDiv_adaptive.

If the advertiser element’s height is greater than the mdAutoHeightThreshold value, the ad behaves as it would if the mdHeightDependency were set to the advertiserdiv behavior.
If the height of the element is the same or less than the value of mdAutoHeightThreshold, then the ad behaves adaptively, utilizing the breakpoints set in mdAdaptiveBreakpoints

Integer

Default: 1

Accepted: > 0

Aspect ratio

(mdAspectRatio)

Determines the aspect ratio the ad should maintain as it resizes.

String

Default: Undefined

Accepted: Two numbers separated by a colon, such as 16:9 or 3:4.

Minimum width

(mdMinimumWidth)

Determines the minimum width for the ad. Set to 0 for no minimum width.

Integer

Default: 0

Accepted: >=0

Minimum height

(mdMinimumHeight)

Determines the minimum height for the ad. Set to 0 for no minimum height.

Integer

Default: 0

Accepted: >=0

Maximum width

(mdMaximumWidth)

Determines the maximum width for the ad. Set to 0 for no maximum width.

Integer

Default: 0

Accepted: >=0

Maximum height

(mdMaximumHeight)

Determines the maximum height for the ad. Set to 0 for no maximum height.

Integer

Default: 0

Accepted: >=0

Fixed width

(mdFixedWidth)

Sets a fixed width for the ad.

Integer

Default: 0

Accepted: >=0

Resize friendly iFrame

(mdResizeFriendlyIframe)

Determines whether the ad attempts to resize a friendly iFrame that contains the ad. Resizing can prevent the ad from being cropped, but may affect the layout of the publisher's page.

Boolean

Default: No/false

Accepted:

Yes/No
true/false

Auto reposition interval

(mdAutoRepositionInterval)

Ad resize/reposition interval. 0 to turn off the interval. Ad attempts to resize itself every "n" milliseconds. Even when this value is set to 0, the ad will always attempt to resize itself upon browser resize, browser scroll, or orientation change. This variable adds an interval by which to also attempt to resize/reposition.

Number

Default: 0

Accepted: >=0

Backup Img path

(mdBackupImgPath)

Relative path to the backup image, if a custom image is desired. This allows a fallback experience to display an image that is not a 1x1 even though the tag is a 1x1 tag.

For example, if this custom variable is set to images/300x250_Default.jpg, a file will attempt to load from the images folder. You must be sure this file exists in the workspace.

When set to undefined, the normal 1 x 1 fallback occurs.

String

Default: Undefined

Accepted: Valid relative path to an image resource.

Parent levels to resize

(mdParentLevelsToResize)

This variable is only used when the ad is serving a default image.

When set to any value over 0, the number of publisher parent elements of our tag resizes to the default image size, if they are smaller than the default image serving.

Integer

Default: 0

Accepted: >=0

Is domain config enabled

(mdIsDomainConfigEnabled)

Determines whether to load the domain configuration settings.

Boolean

Default: No/false

Accepted:

Yes/No
true/false

Prog settings folder path

(mdProgSettingsFolderPath)

Location from which to load the programmatic settings files.

String

Default: 0 //services.serving-sys.com/programmatic/DomainList/

Accepted: Make sure that the default value is not modified.

Recommended changes to manifest file configuration

The following describes the modifications you need to make to the manifest file:

Name: Make sure your ad is named according to your campaign/placement.
Click-through URL: Update the default click-through URL according to your campaign/placement.
Interactions: Update this section to either include all of the interactions you have in your ad's creative, or remove the section entirely and rely just on the asset scanning of the application to detect all interactions in the code.

The following describes modifications you can make to the manifest file:

Custom Variables: The template provides default behavior; however, depending on, for example, the needs of your ad, and the publishers page on which the ad will run, you may need to adjust the values of some of the variables.
Banner Dimensions: The template provided is served as a 1x1. You may need to serve a different tag size due to certain publisher restraints. Since this ad can behave responsively, you may serve any size banner. If you decide to change your banner size, change the manifest file to match.

Functions

Functions are located in the script.js file.

Function Name	Description	Additional Code Allowed
`initializeCreative`	Initializes the creative.
`initializeGlobalVariables`	Initializes the global variables declared at the beginning of the script file.
`initializeVideo`	Initializes video tracking by creating a new instance of EBG Video Module. Available only in the video template.
`addEventListeners`	Adds click event listeners for the click-through and user action buttons, as well as resizes event listeners to check video visibility and update the text displaying the ad dimensions.
`handleUserActionButtonClick`	Click event handler for user action button.
`handleClickthroughButtonClick`	Click handler for the click-through button.
`checkIfVideoIsVisible`	Resizes handler for video visibility. Available only in the video template.
`onPageScroll`	PageScroll handler to get the updated scroll position.
`displayDimensions`	Generates the dimensions and scroll position string.
`setCreativeVersion`	Sends a message to the application with creative version details.
`sendMessage`	Sends a message to the application.
`addCustomScriptEventListener`	Adds a custom script event listener,
`dispatchCustomScriptEvent`	Dispatches a custom script event
`removeCustomScriptEventListener`	Removes a custom script event listener.
`eventManager`	Manages custom script events.

Demo

Click here to preview a demo of deluxe banner format.

Note

Creating an ad using an Amazon Ad Server template

Note

Included files

Additional Files in the video template

Test your deluxe banner locally

Setting up your ad in Amazon Ad Server

Additional resources

Preparing for bulk upload

Shared libraries

Dynamic Creative Optimization

Advanced configuration

Responsive banners

Adaptive banners

Fixed-sized banners

Modify height and width dependencies

Detect scroll position

Note

Manifest configuration file

Important

Note

Recommended changes to manifest file configuration

Functions

Demo

Comments