Create an immersive takeover 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 immersive takeover.

Create an ad using an Amazon Ad Server template

When creating an immersive takeover in a code editor, it is recommended that you start with our official template.

Amz_ImmersiveTakeover_1_0_1_Bundle.zip

Files within the bundle:

README.txt

Amz_ImmersiveTakeover_1_0_1_ImageSkin.zip

Amz_ImmersiveTakeover_1_0_1_ImageSkin_DCO.zip

Amz_ImmersiveTakeover_1_0_1_Video.zip

Amz_ImmersiveTakeover_1_0_1_VideoSkin.zip

Amz_ImmersiveTakeover_1_0_1_VideoSkin_DCO.zip

Download the template and then select the desired folder from the list of available dimensions and options.

You can also customize the dimensions according to your requirements. Everything can be personalized, including media controls of the video.

Included files

The following tables describe the list of files that are included in each downloadable template.

ImageSkin template

File Name	Description	Required
`index.html`	The banner file that is 1x1 displayed on the page.	Required
`panels/headers/index.html`	HTML file for header panel.	Required
`panels/left_gutter/index.html`	HTML file for the left gutter panel.	Required
`panels/right_gutter/index.html`	HTML file for the right gutter panel.	Required
`styles/reset.css`	Style sheet that resets the default styles of the browser.	Optional
`styles/style.css`	Style sheet for the banner and its HTML elements.	Optional (if code is included in the HTML file)
`panels/header/styles/style.css`	Style sheet for header panel creative.	Optional (if code is included in the HTML file)
`panels/left_gutter/styles/style.css`	Style sheet for left gutter panel creative.	Optional (if code is included in the HTML file)
`panels/right_gutter/styles/style.css`	Style sheet for right gutter panel creative.	Optional (if code is included in the HTML file)
`scripts/immersiveTakeover_script.js`	Core script to use the immersive takeover to load and initialize the ad and pass the domain configuration object to custom script.	Required
`styles/immersiveTakeover_style.css`	Basic style sheet for the immersive takeover format.	Required
`scripts/script.js`	Core script for banner to load and initialize ad and pass domain configuration object to custom script.	Required
`panels/header/scripts/script.js`	Core script for header panel to load and initialize ad.	Required
`panels/left_gutter/scripts/script.js`	Core script for left gutter panel to load and initialize ad.	Required
`panels/right_gutter/scripts/script.js`	Core script for the right gutter panel to load and initialize ad.	Required
`images/1x1.jpg`	1x1 backup image for the banner.	Required
`images/background_default.jpg`	Background image asset to inject in the publisher site	Optional
`images/background_minwidth.jpg`	Background image asset to inject in the publisher site.	Optional
`images/background_mobile.jpg`	Background image asset to inject in the publisher site.	Optional
`images/background_tablet.jpg`	Background image asset to inject in the publisher site.	Optional

Video template

File Name	Description	Required
`panels/background/images/1100_width.png`	Background image asset to display in background panel.	Optional
`panels/background/scripts/script.js`	Core script for background panel to load and initialize ad.	Required
`panels/background/styles/style.css`	Style sheet for background panel ad.	Optional
`panels/background/index.html`	HTML file for background panel.	Required
`panels/header/images/video1.png`	Image on button for expanding the header.	Required
`panels/header/images/close.png`	Image on close button appearing in expanded view.	Required
`panels/header/videos/video1.jpg`	Image asset for video poster.	Optional
`panels/header/videos/video1.mp4`	Demo video in mp4 format.	Required

VideoSkin template

File Name	Description	Required
`panels/background/images/1100_width.png`	Background image asset to display in background panel.	Optional
`panels/background/scripts/script.js`	Core script for background panel to load and initialize ad.	Required
`panels/background/styles/style.css`	Style sheet for background panel ad.	Optional
`panels/background/videos/video1.jpg`	Image asset for video poster.	Optional
`panels/ background/videos/video1.mp4`	Demo video in mp4 format.	Required
`panels/background/index.html`	HTML file for background panel.	Required
`panels/controls/images/dropdown.png`	Image asset for the drop-down icon that appears in controls panel.	Optional
`panels/controls/images/mute.png`	Image asset for the mute button icon that appears in controls panel.	Optional
`panels/controls/images/pause.png`	Image asset for the pause button icon that appears in controls panel.	Optional
`panels/controls/images/play.png`	Image asset for the play button icon that appears in controls panel.	Optional
`panels/controls/images/unmute.png`	Image asset for the unmute button icon that appears in controls panel.	Optional
`panels/controls/scripts/script.js`	Core script for the controls panel to load and initialize ad.	Required
`panels/controls/styles/style.css`	Style sheet for the controls panel ad.	Optional
`panels/controls/index.html`	HTML file for the controls panel.	Required

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 an immersive takeover.

Additional tesources

Bulk upload

For the AAS Ad Creation Wizard to recognize your workspace as a immersive takeover, verify that the config.js file contains the following:

define(
{
"adFormatId": 10350
}
);

For more information, 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 tables provide additional variables, functions, and methods that are available for this format. You can use these additional items to fully customize your ad.

Custom Variables

Variable Name in AAS (Variable Key in config.js)	Description	Type	Default and Accepted Values
Right Gutter Name (`mdRightGutterName`)	Right gutter panel name as set in AAS.	String	Default: rightGutter
Left Gutter Name (`mdLeftGutterName`)	Left gutter panel name as set in AAS.	string	Default:leftGutter
Position (`mdPosition`)	Gutters `div` positioning style.	String	Default: fixed Accepted: fixed or scroll
Page Background (`mdPageBackground`)	You will be able to inject a background image only once when the ad is loaded in the publisher's page. You can select the element and the behavior to inject.	String	enabled:false, img:images/background_default.jpg, color:#000000, size:cover, position:top center, repeat:no-repeat, attach:fixed, fade:fade-in, fade_time:3000, inject:body, injectType:div, clickable:false
Auto Reposition Interval (`mdAutoRepositionInterval`)	Panel reposition interval. Set to 0 to turn off the interval. Panels reposition in every "n" milliseconds.	Number	Default: 100
Content Width (`mdContentWidth`)	Page content width.	Number	Default: 970
Eye Div ZIndex (`mdEyeDivZIndex`)	Default z-index of the eye div.	String	Default: undefined
Gutters Default Height (`mdGuttersDefaultHeight`)	Gutters default height.	Number	Default: 1000
Gutter Top Position (`mdGutterTopPos`)	Defines the top position of the gutters. JavaScript will try to get the value from the current page and apply that value to set the top position of the gutters. However, if JavaScript failed to get any value from the page, it will take the value from this custom variable.	Number	Default: 0
Header Panel Name (`mdHeaderPanelName`)	Header panel name as set in AAS.	String	Default: header
Background Panel Name (`mdBackgroundPanelName`)	Background panel name as set in AAS.	String	Default: background
Background Placement Selector (`mdBackgroundPlacementSelector`)	Div reference to inject background panel. A valid CSS selector should be present in this variable to successfully push background panel.	String	Default: body
Background Inject Type (`mdBackgroundInjectType`)	Background panel injection type.	String	Default: last Accepted values: first: Insert as a first child a div. last: Insert as a last child of a div. after: Insert after a div. before: Insert before a div.
Header Size Inheritence (`mdHeaderSizeInheritence`)	Header panel behavior will change based on the option selected.	String	Default: 0-781:450,782-1023:250,1024-4000:250 Accepted: View values [breakpoints]: Header panel height will change based on break points. If viewport falls in any of the range, that respective height will be set to the header panel. browserWidth: Header width will be the same as the browser width, and the banner height stays the same as the placement height. publisherContainerSize: Header size will be the same as the publisher ad container, including upon resize and reorientation. adaptiveOnAuto: If the publisher container is auto or undefined, then the header will be adaptive; otherwise, it will be the same as the publisher container size.
Header Expanded Height (`mdHeaderExpandedHeight`)	Header panel expanded height.	Integer	Default: 417
Min Header Width (`mdMinHeaderWidth`)	Minimum header width if custom script fails to read page content width.	Integer	Default: 970
Expand Full Screen Below (`mdExpandFullScreenBelow`)	Expand header panel to fullscreen if viewport value is less than value mentioned in this variable.	Integer	Default: 3000
Auto Collapse Timeout (`mdAutoCollapseTimeout`)	Delay, in seconds, to auto collapse header pane when panel auto expands.	Integer	Default: 10
Background ZIndex (mdBackgroundZIndex)	Background panel z-index.	Integer	Default: -1
Header Panel Top Offset (`mdHeaderPanelTopOffset`)	Top offset to display above the header panel.	Integer	Default: 0
Header Panel Bottom Offset (`mdHeaderPanelBottomOffset`)	Bottom offset to display above the header panel.	Integer	Default: 0
Show Gutters (`mdShowGutters`)	Show or hide gutters.	Boolean	Default: true
Content Offset (`mdContentOffset`)	Number of pixels of padding between the width of the content and the start of the gutter panels. Note Note: Only for VideoSkin template.	String	Default: controls
Header Expand Percentage (`mdHeaderExpandPercentage`)	Header expansion percentage. If set to 100, header will expand to fullscreen by pushing page content outside. If set to value less than 100, some part of page content may be displayed at the bottom. Note Note: Only for VideoSkin template.	Integer	Default: 100
Pushdown Animate (`mdPushdownAnimate`)	Animate expand/collapse header panel. If set to false, header will immediate expand/collapse.	Boolean	Default: true
Expand Animation Duration (`mdExpandAnimationDuration`)	Time taken by header panel to expand animate.	Integer	Default: 1000
Collapse Animation Duration (`mdCollapseAnimationDuration`)	Time taken by header panel to collapse animate.	Integer	Default: 1000
Expand Collapse Animation Easing (`mdExpandCollapseAnimationEasing`)	Easing for header panel expand and collapse animation.	String	Default: easeInOutQuint Accepted: View values easeInCubic easeInOutCubic easeInOutQuad easeInOutQuart easeInOutQuint easeInQuad easeInQuart easeInQuint easeOutCubic easeOutQuad easeOutQuart easeOutQuint linear
Auto Expand Delay (`mdAutoExpandDelay`)	Delay auto expansion by value in this variable.	Integer	Default: 0
Expand To Full Screen (`mdExpandToFullScreen`)	Expand header panel to fullscreen. Note Note: Only for VideoSkin template.	Boolean	Default: false
Backup Image Path (`mdBackupImagePath`)	Relative path to the backup image, if a custom image is required. This allows a fallback experience to display an image that is not a 1x1 even though the tag is a 1x1 tag. Template workspace includes a file that could be used here as an example, if this custom variable were set to `images/970x250_Default.jpg`. When set to undefined, the normal 1x1 fallback occurs.	String	Default: undefined
Content Alignment (mdContentAlignment)	Alignment of the content on the page. This variable is only used if `mdContentPlacementSelector` is undefined. This is used for purposes of positioning the gutter elements	String	Default: C Accepted: L (left) R (right) C (Center
Content Offset (`mdContentOffset`)	Number of pixels of padding between the width of the content and the start of the gutter panels.	Integer	Default: 0
Content Placement Selector (`mdContentPlacementSelector`)	Div reference to detect content of page. A valid CSS selector should be present in this variable to successfully detect the content location and width. When this variable is set to anything other than undefined, `mdContentWidth`, `mdContentAlignment`, and `mdContentXPosOffset` are ignored and are calculated by using the width and location of this element. This is used for purposes of positioning the gutter elements. There is a new and experimental method to get the widest element from any page automatically by enabling {"automaticDetection": true} More details about this feature below.	String	Default: 0
Align Top Scroll (`mdAlignTopScroll`)	Align gutters to top if header goes out of view.	Boolean	Default: false
Content X Pos Offset (`mdContentXPosOffset`)	Value, in pixels, to offset the detected location of the content area. Positive value moves the content location to the right; negative value moves the content location to the left. This allows for asymmetrical layouts with padding on the left/right. This variable is only used when `mdContentPlacementSelector` is undefined. This is used for purposes of positioning the gutter elements.	Integer	Default: 0
Header Inject Type (`mdHeaderInjectType`)	Header panel injection type.	String	Default: after Accepted: first: Insert as a first child a div. last: Insert as a last child of a div. after: Insert after a div. before: Insert before a div.
Header Offset (`mdHeaderOffset`)	Vertical offset from header; affects header panel and gutter panels.	Integer	Default: 0
Header Placement Selector (`mdHeaderPlacementSelector`)	Div reference to inject header panel. A valid CSS selector should be present in this variable to successfully push header panel. If undefined, will inject header at tag location	String	Default: undefined
Right Gutter Max Width (`mdRightGutterMaxWidth`)	Right gutter maximum width. Set to 0 to define if right gutters should cover available page width on right side of site content.	Integer	Default: 500
Right Gutter Minimum Width	Right gutter minimum width.	Integer	Default:100
Gutter Max Width (`mdGutterMaxWidth`)	Right gutter maximum width. Set to 0 to define if right gutters should cover available page width on right side of site content.	Integer	Default: 500
Gutter Minimum Width (`mdGutterMinWidth`)	Right gutter minimum width.	Integer	Default: 100
ProgEnable (`mdIsDomainConfigEnabled`)	Determines whether to load the programmatic settings.	Boolean	Default: false
Programmatic Settings Folder Path (`mdProgrammaticSettingsFolderPath`)	Location from which to load the programmatic settings files.	String	Default: `//services.serving-sys.com/programmatic/DomainList/`
Parent Levels To Resize (`mdParentLevelsToResize`)	This variable is ONLY for the `mdBackupImage` experience. If you set this variable to true, the min-width and min-height of the parent elements of the `ebDiv` tag will be set to the dimensions of the backup image, so that the backup image will not be cropped/clipped.	Number	Default: 0
Auto Scroll Top On Orientation (`mdAutoScrollTopOnOrientation`)	In mobile and tablet devices when the orientation is changed automatically, the scroll bar will be moved to the position of the header. If there is no header, it will be moved to the top of the page.	Boolean	Default: true

Custom interactions

The following custom interactions are reported by the ad and can be reviewed in AAS reporting (besides standard ad interactions).

Interaction Name	Description
`left_gutter_viewed`	(Auto) When left gutter expands for first time.
`right_gutter_viewed`	(Auto) When right gutter expands for first time.
`expand_immersiveTakeover_auto`	(Auto) When the header panel is expanded automatically.
`expand_immersiveTakeover_user`	(User) When user click on the expand button.
`collapse_immersiveTakeover_auto`	(Auto) When user click on the close button.
`collapse_immersiveTakeover_user`	(User) When user click on the close button.
`click_left_gutter`	Click-through fired once the user clicks the click-through button that appears in the left gutter.
`click_right_gutter`	Clickthrough fired once the user clicks the click-through button that appears in the right gutter.
`click_background`	Click-through fired once the user clicks the background panel.
`clickable_gutters`	Click-through fired once the user clicks the background image when the clickable option is enabled in the custom variable `mdPageBackground`.

All of the immersive takeover functionality is programmed in the template files. At a minimum, the only changes you will need to make are to the loaded image and its style.

Note

Note: When updating or replacing images or videos, make sure to also update references to their file names and dimensions found in index.html, style.css, and script.js as necessary. To update the layout, design, and functionality of a template, open the HTML, CSS, and JS files in a text editor.

Load and initialize the immersive takeover

Before initializing the immersive takeover, you only need to identify the asset; depending on this option, the banner or panel will load different functions and the behavior could change.

For example:

var config = {
   panel: "header"
 };
var immersiveTakeover = new immersiveTakeover(config);

Property

Description

Options

panel

Defines the type of the element for the immersive takeover.

If the value for panel is empty or undefined, it acts as a standard panel.

header
left_gutter
right_gutter
background
videoskin
controls
standard (if you want to add a standard panels)

Video example:

var config = {
    panel: "videoskin",
    videoWidth:1100,
    videoHeight:416,
    videoURL: "videos/video1.mp4",
    videoPoster: "videos/video1.jpg"
};
var immersiveTakeover = new immersiveTakeover(config);

Key	Description	Options
`panel`	Defines the type of the element for the immersive takeover. If the value for `panel` is empty or undefined, it acts as a standard panel.	header left_gutter right_gutter background videoskin controls standard (if you want to add a standard panels)
`videoWidth` `videoHeight`	If you want to use the `resizeVideo` function in a panel with video to get a good `aspectRatio`, you need to set up the `videoWidth` and `videoHeight` of your video asset.	Integer value.
`videoURL`	String that contains the source URL of the video or an array of strings if multiple codecs for the same video are required.	Single source URL as a string, `videos/video1.mp4` or multiple sources/codecs as an array of strings, `["videos/video1.mp4", "videos/video1.webm", "videos/video1.ogv"]` Note Note: During video tag dynamic generation, the file extension included in the source URL string will be used to generate the related videos' source tag's `type` parameter value. For example, `<source src="videos/video1.mp4" type="video/mp4">`
`videoPoster`	String that contains the source URL of the video poster image.	Source URL as a string, `videos/video1.jpg`.

Example:

var config = {
   panel: "controls",
   initialPosition:"top-center",
   expandedPosition:"top-center",
   collapsedPosition:"top-right",
   showDelay: 1000
};
var immersiveTakeover = new immersiveTakeover(config);

You can change the position of the controls panel of the three different states, using these options: top-left, top-center, top-right, bottom-left, bottom-center, or bottom-right.

When the VideoSkin is loaded initialPosition, it appears in the top-center of the page by default.
When the VideoSkin is expanded expandedPosition, it appears in the top-center of the page by default.
When the VideoSkin is collapsed collapsedPosition, it appears in the top-right of the page by default.
Each panel can be shown with a different delay. You can change it using N milliseconds and modify the property showDelay in the config variable.

var config = {
   panel: "videoskin",
    videoWidth:1100,
   videoHeight:416,
   videoURL: "videos/video1.mp4",
   videoPoster: "videos/video1.jpg",
   showDelay: 1000
};
var immersiveTakeover = new immersiveTakeover(config);

Update header panel

The header section of the index.html loads the essential style sheets, the AdKit API script, and the creative JavaScript file. The header is responsive and adapts to any screen size using our templates. All the elements are placed in relative position, and all of the properties are set in percentage so that elements appear correctly in all device sizes.

If frequency capping is set, the header will auto-expand and auto-collapse after few seconds if the value mentioned within the mdAutoCollapseTimeout custom variable is greater than zero.

The header panel of the VideoSkin and ImageSkin are transparent and do not contain any creative elements.

If you are not using our templates, you need to include the essential files, and you only need to add the following lines in your code to initialize the immersive takeover format:

var config = {
   panel: "header"
};
var immersiveTakeover = new immersiveTakeover(config);

The custom script will wait for other panels to load and, once all of the panels have been loaded, the custom script will dispatch the afterShowPanelContent event to all panels. This event notifies those panels to show their creative elements. Within the header script, once this event is received, certain creative elements will fade in. If you identify the asset like header, you will receive some options callbacks from the custom script.

Functions from the header:

When you want to expand the header, you must invoke this function:
```
immersiveTakeover.expand();
```
When you want to collapse the header, you must invoke this other function:
```
immersiveTakeover.collapse();
```

Callbacks for the header (optional to use). Header has the behavior to expand and collapse, you can control each state:

When the Expand animation is starting:

function afterExpandAnimStart(args) {
   /* Implement code logic to fire on Expand animation start */
}

When the Expand animation is completed:

function afterExpandAnimComplete(args) {
   /* Implement code logic to fire on Expand animation Complete */
}

When the Collapse animation is starting:

function afterCollapseAnimStart(args) {
   /* Implement code logic to fire on Collapse animation start */
}

When the Collapse animation is completed:

function afterCollapseAnimComplete(args) {
   /* Implement code logic to fire on Collapse animation Complete */
}

Update gutters

To customize the gutters, use an HTML-authoring environment to open index.html from panels/left_gutter, style.css from panels/left_gutter or panels/right_gutter, and script.js from panels/left_gutter or panels/right_gutter. Gutters within the VideoSkin and ImageSkin templates do not contain any creative elements.

If you are not using our templates, you need to include the essential files and you only need to add the following lines at your code to initialize the immersive takeover format:

var config = {
   panel: "left_gutter"
};
var immersiveTakeover = new immersiveTakeover(config);

var config = {
   panel: "right_gutter"
};
var immersiveTakeover = new immersiveTakeover(config);

Update background

To customize the background panel, use an HTML-authoring environment to open panels/background/index.html, panels/background/style.css, and panels/background/script.js.

The background panel of the VideoSkin template contains a static image and video.

If you are not using our templates, you need to include the essential files and you only need to add the following lines at your code to initialize the immersive takeover format:

var config = {
   panel: "background"
};
var immersiveTakeover = new immersiveTakeover(config);

or if you are using the video background option (VideoSkin)

var config = {
   panel: "videoskin"
};
var immersiveTakeover = new immersiveTakeover(config);

Panel callbacks

All the panels have the same callbacks for different events that you can use if required.

Callbacks for all panels (optional to use):

afterShowPanelContent: When the panel is shown.

function afterShowPanelContent(args) {
   /* Implement code logic to fire when the panel is shown */
}

onPanelLoaded: When the panel is loaded.

function onPanelLoaded(args) {
   /* Implement code logic to fire when the some panel is loaded */
   if (args.panelName.toLowerCase() == 'leftgutter') {
      /* do something */
   }
   else if (args.panelName.toLowerCase() == 'rightgutter') {
      /* do something */
   }
}

onPanelUnload: When the panel is unloaded.

function onPanelUnload(args) {
   /* Implement code logic to fire when the some panel is unloaded */
   if (args.panelName.toLowerCase() == 'leftgutter') {
      /* do something */
   }
   else if (args.panelName.toLowerCase() == 'rightgutter') {
      /* do something */
   }
}

adWasClicked: When the click-through is fired, all the panels will call this function and you can decide if you want to do something. For example, after click-through the video can be paused.
```
function adWasClicked(args){
   videoRef.pause();
   console.log("Ad was clicked");
}
```
onPageScroll: If you want to use "onPageScroll" feature you only need to add this function to your code. The function will recieve when the user scrolling up/down the percent of the scrollX and scrollY
```
function onPageScroll(args) {
   args.scrollXPercent;
   args.scrollYPercent;
}
```

Add a video

To add a video to your project, you must provide a container div into which the actual video tag and source tags will be injected. The video container div should not contain any child divs. No hardcoded video and/or source tags should be placed in the HTML document. The actual video tag and source tags are dynamically generated from within the template script immersiveTakeover_script.js. This allows the final tags to be loaded into the DOM in a proper state according to the desired functionality and environment.

You can use these functions to initialize the video and video tracking. Callbacks, if utilized, are dispatched on the following video events; ready, play, pause, end, and volume change. See the Video Callback Functions section for further details.

To initialize the video:
```
immersiveTakeover.initVideo(videoContainerRef);
```
The single parameter accepted by the immersiveTakeover.initVideo function is a reference to the element in which the dynamically generated video tag is to be injected. If no parameter is passed, the script will automatically search for an element with an ID of video-container, within the specific HTML DOM, in which to inject the video.
```
<div id="video-container"></div>
```
You can use the standard events to control the video functions such as play, pause, load, and mute.
```
videoRef.play();
videoRef.load();
videoRef.muted = true;
```
To resize the video holding the aspect ratio (you will need a div container for your video element):
```
immersiveTakeover.resizeVideo(videoContainerRef);
```
The video-container should have the following or similar style:
```
#video-container{
   background-color: black;
   position: absolute;
   width: 100%;
   height: 92%;
}
```
When creating the following config object, you may modify the default setup as required (and according to this document) to optimize the settings for your use case. For instance, you may change the videoWidth and videoHeight values according to the aspect ratio of your video and to achieve the best resolution possible.
```
var config = {
   panel: "header",
   videoWidth:1100,
   videoHeight:416,
   videoURL: "videos/video1.mp4",
   videoPoster: "videos/video1.jpg"
};
```

The Video Callback functions include the following:

When the video is injected into the page and ready for function calls and interaction:
```
function afterVideoReady(args) {
    /* Implement code logic to fire when the video is ready for function calls and interactions */ 
}
```
Note

Note: It is recommended to capture a reference to the dynamically created video within the afterVideoReady callback function as this is the first point at which it will be available. The args parameter will contain a reference to the video, which can be read using args.video. Please note the video reference is passed within the args parameter of all video-related callbacks. If you do not require a reference to the video element outside of the video related callback functions, or at all, you do not need to capture this reference.

When the video is played:

function afterVideoPlay(args) {
    /* Implement code logic to fire when the video Play */ 
}

When the video is ended:

function afterVideoEnd(args) {
    /* Implement code logic to fire when the video End */ 
}

When the video is paused:

function afterVideoPause(args) {
    /* Implement code logic to fire when the video Pause */
}

When the volume of the video is changed:

function afterVolumeChange(args) {
    /* Implement code logic to fire when the volume Change */
}

Synchronize panels

You can synchronize all the panels if you want to use animation that starts at the same time, or you want to start some animation after some determinate action in some panel. You only need to invoke the function syncAllPanels and send a string parameter.

For example: From the header panel using the callback function afterShowPanelContent, you can send start to initialize the animation at the same time for all panels.

function afterShowPanelContent(args) {
   immersiveTakeover.syncAllPanels("start");
}

After calling this function, all the panels you have in the workspace will run the function syncAll, which you can use to start some animation.

function syncAll(args) {
    switch (args.state) {
      case "start":
      /* Starting the animation */
      break;
      case "end":
       /* more options */
      break;
    }
}

args.state: Contains the string message, if you need to send several messages, or you can use a switch.

if you want to synchronize only with a specific gutter, you can use this other method.

immersiveTakeover.syncGutterLeft();

immersiveTakeover.syncGutterRight();

After invoking it from any panel, the left/right panel will run this function:

function syncGutterLeft() {
    /* Implement code logic to fire when the synchronize is invoked */
}

function syncGutterRight() {
    /* Implement code logic to fire when the synchronize is invoked */
}

Additional utilities

closePanel: You can close the panel from which this function was called, and you can select if the interaction is done by the user (default) or automatically.
- By user
```
immersiveTakeover.closePanel();
/* Or */
immersiveTakeover.closePanel(false);
```
- Automatically
```
immersiveTakeover.closePanel(true);
```
closeAllPanels: Use this function from any panel to close all panels at the same time.
```
immersiveTakeover.closeAllPanels();
```
fontResize: Use this function to resize font in the project. The function will receive the reference of the element and the minimum size of the font. The function will modify the fontSize depending of the resolution of the device.
```
var clickthroughExpandBtn = document.getElementById("clickthrough-expand");
immersiveTakeover.fontResize(clickthroughExpandBtn, 4);
```
getInfo: Use this function to get all the information about the environment of the device, for example if the ad is in local, or if the device is a mobile, IOS, or if the browser does not supported the autoplay feature. You can change the behavior according to the device.
```
var infoDevice = immersiveTakeover.getInfo();
var isLocal = infoDevice.isLocal; /* if the asset is loaded in local (true/false) */
var isMobile = infoDevice.isMobile; /* if the device is mobile (true/false) */
var isIOS = infoDevice.isIOS; /* if the device is IOS(true/false) */
var isUnsupportedBrowserAutoPlay = infoDevice.isUnsupportedBrowserAutoPlay;
/* if the device is not compatible with autoplay feature of the video (true/false) */
```
Note

Note: Autoplay of the video will not be available in some unsupported devices/environments, such ad iOS9 and below. In this case, the video will automatically default to click-to-play behavior regardless of the autoplay setting. Currently, the only environments listed within the support matrix for this template, that do not support autoplay video, are iOS9 and Samsung browser version 6.
loadAdditionalAsset: Use this function to inject an image from additional asset using the ID in some element in the ad. You will need the element where it will be loaded and the relative path for local testing.
```
var background = document.getElementById("background");
immersiveTakeover.loadAdditionalAsset(background,2,"../../images/gutterLeft_background.png");
```
setPanelZIndex: Use this function if you need to change the Z-index in some panel manually. It will affect only the panel which is used; you must indicate the number of the Z-index that you want to use.
```
immersiveTakeover.setPanelZIndex(20);
```
seteyeDivZIndex: Use this function to change the Z-index of the EyeDiv manually. It will affect all the panels that are inside of the eyeDiv; you must indicate the number of the Z-index that you want to use.
```
immersiveTakeover.seteyeDivZIndex(5);
 
```

Configuring layout per domain

Note

Note: Using programmatic custom variables is the preferred method, although you can still use the domainConfig.js file. By default, domainConfig.js file is disabled.

If you want to use this file, delete the comments line in the index.html of the banner, and create the domainConfig.js with your setup.

The domainConfig.js file contains domain-related customization details that allow you change both ad layout, and with publisher approval even the site layout per domain. While this method has been deprecated in favor of using the programmatic settings, support still exists in the ad format for the domainConfig.js file.

<script type="text/javascript" src="scripts/domainConfig.js"></script>

You can use the following customizations in the domainConfig.js script. This script is located in the scripts>domainConfig.js file. All customizations are also supported in Programmatic Settings Custom Variables.

Customization	Description
`domainName`	Domain name for which this setting will be applied. A subdomain and domain name is enough; full domain URL is not required.
`eyeDivZindex`	Sets z-index of eyeDiv that holds left gutter, right gutter and header panel.
`contentSelector`	Page content div reference to align left and right gutter.
`headerSelector`	Page header div reference to align gutter from top.
`contentOffset`	Offset from total page content (default is 0).
`headerOffset`	Offset from header (default is 0).
`alignTopScroll`	Align gutter to top if header goes out of view.
`backgroundPlacementSelector`	Page content div referrer to push background panel.
`siteStylesheet`	URL for the site style sheet to push in page content header.
`siteJavascript`	URL for the JavaScript file that will be injected in page header.
`backgroundZindex`	Background panel z-index.

The following shows an example of customizations for the domainConfig.js file:

var domainConfig = [{
   domainName: 'demo.sizmek.com',
   eyeDivZindex: 10,
   contentSelector: '#siteContainer',
   headerSelector: '#siteHeader',
   contentOffset: 0,
   headerOffset: 0,
   alignTopScroll: false,
   backgroundPlacementSelector: 'body',
   backgroundInjectType: 'Last',
   siteStylesheet: 'siteStylesheet/sizmek_demo.css',
   siteJavascript: 'siteJavascript/sizmek_demo.js',
   backgroundZindex: -1
 }];

Important

Important: If you need a single ad tag to work across a network of sites, either edit the deprecated file domainConfig.js and set different properties across different publishers, or work with the publisher certification team to ensure the custom variables are set as needed by publisher specifications across all intended sites.

Inject a background image on a publisher's page

To inject a background image, you can change the body or a specific element in the DOM of the page. You can do one of the following:

Use a simple background
Perform an advanced setup that uses breakpoints to determine when to load a specific background. For example, you can have a background for mobile devices in portrait mode or for low/high resolution.

The following sections describe the methods for injecting a background on a publisher's page.

Method A: custom variable `mdPageBackground`

This method allows you to inject a background image only once when the ad is loaded. There is no extra code required in the Workspace, and you can set up different options to show the image on the publisher's page.

Note

Note: Make sure that you use this method in conjunction with the mediaQueries method. You want to make sure that when the ad is loaded on the page, the custom variable result is not overwritten.

The following table describes the variables that are available.

Variables	Description	Values
`enabled`	Enables or disables this feature. If set to TRUE, the background is injected on the publisher's site.	Default: false Accepted: true/false
`img`	Allows you to add the path of an image from your Workspace, or use a number, if you want to select an additional asset.	Default: images/background_default.jpg Accepted: Numbers/complete path from your Workspace
`color`	Allows you to select a Hex color, or enter a name of a color, for example, red or green. This will be the background color of the page. For more information, click here.	Default: #000000 Accepted: Hex numbers, for example, red, blue, transparent
`size`	Determines the background size on the page. For more information, click here.	Default: cover Accepted: For example, cover ,contain, auto, percentage
`position`	Determines the position of the background, horizontal or vertical. For more information, click here.	Default: top center Accepted: top, center, left, right, bottom, x% y%, xpos, ypos
`repeat`	Determines if the background is repeated. If you want use the repeat option, for best results, use a small image. For more information, click here.	Default: no repeat Accepted: repeat, repeat-x, repeat-y, no-repeat
`attach`	Determines the behavior for the background when scrolling up/down on the publisher's page. For more information, click here.	Default: fixed Accepted: fixed, scroll, local, inherit, initial
`fade`	Determines the tween animation style for the background. When the value is set to none, the background is shown without any animation.	Default: fade-in Accepted: fade-in, fade-out, fade-in-out, none
`fade_time`	Duration of the tween animation when the background is injected on the publisher's site.	Default: 3000 Accepted: Number in milliseconds
`inject`	Element in the DOM that is applied to the setup. You can select a class (`.myClass`), id `(#myDiv`), or tag name (`header`).	Default: body Accepted: Any element in the DOM of the page
`injectType`	Methods to inject the background on the publisher's page include the following: div: Background is injected inside of a Div (`mdBackground`). The Div is inserted in the element that you select in the `inject` variable. style: Background is injected in the style (CSS) of the element that you select in the `inject` variable. Note Note: When the image is shown, this option will not have a fade-in/out (tween).	Default: Div Accpted: style or div
`clickable`	If set to TRUE, the background is clickable on the page with two dynamics, created using two divs (without panels for gutters).	Default: false Accepted: true/false

Method B: Invoke the `changePageBackground` function

From the workspace, invoke the changePageBackground function that is included in the workspace ImageSkin.

changePageBackground (image, color, size, position, attach, repeat, fade, fade_time, inject, injectType, clickable);

Note

Note: To avoid conflicts, the existing method is deleted when you use a new method. For example, if you use the variable injectType with a value of Div , and after you use the injectType with a value of style ,the Div with the first background will be removed from the page.

Method C: `mediaQueries`

The functions are included in the workspace ImageSkin. You can use the mediaQueries method to define the breakpoints to inject into the css of the publisher's page and improve the user experience when the ad is loaded in different devices with different resolutions. You can add all the that you need, via the following structure:

The following structure shows how to add the mediaQueries that you might need:

var breakpointsBackgroundsList = [{
   mediaQuery: "screen and (min-width: 960px)",
   setupBackground: {
   img: "images/background_default.jpg",
   color: "",
   size: "cover",
   position: "top center",
   attach: "fixed",
   repeat: "no-repeat",
   fade: "fade-in",
   fade_time: 0,
   inject: "body"
}]

Customization

Description

mediaQuery

Enables you to add the desired media query. The basic media queries control the width/height, but you can include orientation or advanced behavior to control the minimum device pixel ratio.

You do not need to include @media in the string. For more information, click here.

Examples of media queries include the following:

For mobile in portrait and landscape: only screen and (min-device-width:375 px) and (max-device-width:667 px)
For mobile in landscape mode only: only screen and (min-device-width:690 px) and (orientation : landscape))
For tablets in portrait mode only: screen and (min-width:690 px) and (max-width:995 px) and (orientation:portrait)
For all devices with a resolution between 0 px and 959 px:screen and (min-width:0 px) and (max-width:959 px)

setupBackground

Enables you to set up the behavior of your background for each mediaquery. For best results, it is recommended that you modify the following values:

image
color
size
position
attach
repeat
fade
fade_time
inject

setupBackground: {
   img: "images/background_default.jpg",
   color: "#000000",
   size: "cover",
   position: "top center",
   attach: "fixed",
   repeat: "no-repeat",
   fade: "fade-in",
   fade_time: 3000,
   inject: "body",
   clickable: false
}

Automatic detection of the widest element

This feature searches for the widest element found on the content of any page, and then automatically sets up the custom variables mdContentPlacementSelector and mdContentWidth. This feature uses the simple skin format in networks with the same tag in rotation.

To enable the automatic detection, change the value of the custom variable mdContentPlacementSelector. The basic method uses {"automaticDetection": true}.

The following table describes the parameters that you can configure to customize the search for an element.

Variables	Description	Values
`search`	Type of element you want to search on the page	Default: div Accepted examples include: div header span button
`horizontalTreshold`	Controls the maximum and minimum width of the pixels for the element you are searching	Default: 300,1800 Accepted: Numbers - minimum/maximum
`avoid`	Names of elements that you want to skip during the search process	Default: header footer dfp google input search hide nav module column Accepted: String
`priority`	The ID or class names to prioritize in the search process. In instances where a `priority` element is found, the element is checked, if it is not tagged as an `avoid` element. For example, `#container hide` will be avoided because it contains the word hide.	Default: #container, #wrapper container wrapper main #main Accepted: String

The following is a code example of a customized search for an element:

{"automaticDetection":true,"search":"div","horizontalTreshold":"300,1800","avoid":"header,footer,dfp,google,input,search,hide,nav,fb,module,column","priority":"#container,#wrapper,.container,.wrapper,.main,#main"}

Common customizations

Configure gutters

To align gutters correctly around the page content, set mdContentPlacementSelector to a valid CSS selector that will give the page width.
To align gutters correctly from the top, set headerSelector to a valid CSS selector to read header height, if any.
You can set gutters to display in a fixed location or scroll with the page. Set mdPosition to either fixed or scroll.
Gutters are responsive and adapt to any screen size and they can also be set to a static width. Setting mdLeftGutterMinWidth/mdLeftGutterMaxWidth or mdRightGutterMinWidth/mdRightGutterMaxWidth to the same value creates gutters with a fixed width.
You can set a minimum and maximum width for responsive gutters by updating mdLeftGutterMinWidth/mdRightGutterMinWidth and mdLeftGutterMaxWidth/mdRightGutterMaxWidth.
You can set gutters to fill the entire available space by updating mdLeftGutterMaxWidth/mdRightGutterMaxWidth to 0. If there is not enough room to d the gutters in the browser, the gutters will disappear.

Configure the header panel

The Header panel aligns correctly in the page content by accessing the parent div in which the placement tag is placed. If, for some reason this fails, the fallback value from the mdMinHeaderWidth custom variable is used. mdHeaderHeightBreakPoints defines the header collapse height for different viewport areas.

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. Upon any scroll, resize, or orientation change, the new scroll position is updated.

You can access the current scroll position, scrollXPercent and scrollYPercent 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 the code in the onPageScroll function in the script.js file.

Note

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

Manifest configuration (config.js file)

The Manifest file, config.js, is a metadata file that defines certain default behaviors for an ad that is created in AAS. The config.js file is located in the root folder of the Workspace. The file includes the predefined default settings needed for your simple skin. Depending on your requirements, you can modify these settings. For more information about the manifest configuration settings, see Manifest Ad Data.

Additional methods

The AAS HTML API provides a set of methods, such as user interactions, automatic interactions, and timers that you can use in your code. For more information about these methods, see Methods.

You should load only the modules you will use in each HTML. You can delete or add the video variable in your banner or panel assets, EBModulesToLoad= [ 'Video','EBCMD','EBAPI'], depending if you have a video or not.

It is recommended to load the files from each panel using the parent relative path. The following is an example for loading the files from a panel:

<link rel="stylesheet" href="../../styles/immersiveTakeover_style.css"/>
<script>EBModulesToLoad = ['Video','EBCMD','EBAPI'];</script>
<script type="text/javascript" src="http://ds.serving-sys.com/BurstingScript/adKit/adkit.js"></script>
<script type="text/javascript" src="../../scripts/immersiveTakeover_script.js"></script>

Demo

Click here to preview a demo of immersive takeover format.

Note

Create an ad using an Amazon Ad Server template

Included files

ImageSkin template

Video template

VideoSkin template

Setting up your ad in Amazon Ad Server

Additional tesources

Bulk upload

Shared libraries

Dynamic Creative Optimization

Advanced configuration

Custom Variables

Note

Note

Note

Custom interactions

Note

Load and initialize the immersive takeover

Note

Update header panel

Update gutters

Update background

Panel callbacks

Add a video

Note

Synchronize panels

Additional utilities

Note

Configuring layout per domain

Note

Important

Inject a background image on a publisher's page

Method A: custom variable mdPageBackground

Note

Note

Method B: Invoke the changePageBackground function

Note

Method C: mediaQueries

Automatic detection of the widest element

Common customizations

Configure gutters

Configure the header panel

Detect scroll position

Note

Manifest configuration (config.js file)

Additional methods

Demo

Comments

Method A: custom variable `mdPageBackground`

Method B: Invoke the `changePageBackground` function

Method C: `mediaQueries`