Overview
Introduction and Screenshots
The HTML5 Background Dimmer Block feature allows you to incorporate Background Dimmer functionality into your ad. This allows you to cover site content around your ad so the user will focus on your content. Whether you are on a desktop browser or mobile device, the surrounding mask will be full screen. You are able to specify the color, opacity and fade time of the background dimmer. Please check your publisher specs before implementing the Background Dimmer in your ad.
Demos/Downloads
The following table provides links to the template and demo for the HTML5 Background Dimmer ad feature.
Template |
|
Demo |
Supported Platforms
Platform |
Supported Version |
Windows |
Internet Explorer 10+, Edge, Firefox, Chrome |
Mac |
Firefox, Chrome, Safari |
iPhone |
iOS 8.0 and later |
iPad |
iOS 8.0 and later |
Android |
Android 4.1 and later( including tablets) |
Assets
Workspaces Available
The Background Dimmer Ad Feature includes one HTML5 Workspace built using the HTML5 Polite Banner.
Included Workspace Files
Filename |
Description |
|
Background Dimmer Demo Backup image |
|
Sizmek logo image |
|
Background Dimmer Demo HTML file. |
|
Background Dimmer Javascript file |
|
Background Dimmer Stylesheet |
Implementing the Ad Feature
How to Add the Ad Feature to Your Workspace Code
Prerequisite
Before you begin, make sure you have the following resources available:
- HTML5 Background Dimmer Ad Feature Files
Procedure
The following steps illustrate how to add the Background Dimmer Ad Feature to your creative Workspace.
- After the EB object has been initialized, you can use the following method call to set your dimmer settings.
EB._sendMessage("setDimmer", {color: "#000", opacity: 0.8, fadeTime: 500});
- When you are ready to dim the page, you can use the following method call to show the dimmer:
EB._sendMessage("showDimmer");
- When you want to hide the dimmer, use the following method call:
EB._sendMessage("hideDimmer");
- Alternately, you can use the following message to toggle the dimmer on and off:
EB._sendMessage("toggleDimmer");
- There are also a number of other calls you can use which are covered below. All calls are made in the following format:
EB._sendMessage(message[, parameters]);
Background Dimmer Optional Commands
Message |
Parameters |
Description |
|
Object [optional] |
Show the background dimmer. You can optionally pass in parameters to specify color, opacity, and fade time. |
|
Object [optional] |
Hide the background dimmer. You can optionally pass in parameters to specify color, opacity, and fade time. |
|
Object [optional] |
Toggle the background dimmer on and off. You can optionally pass in parameters to specify color, opacity, and fade time. |
|
Object [required] |
Change the background dimmer settings without changing its current state. Pass in parameters to specify color, opacity, and fade time. The settings will take effect the next time the dimmer state is changed. |
|
None |
Stop the background dimmer from fading out automatically. |
|
None |
Request the current status of the dimmer. |
|
None |
Request whether the escape key is set to fade the dimmer. |
Here is an example of how to add custom parameters to the custom script. In this case, the dimmer fades to black (color=000), at an opacity of 0.8 (opacity=0.8). The fade takes 500 milliseconds (fadetime=500). The dimmer fades in automatically (auto=true), and disappears after 10000 milliseconds (duration=10000). The z-index is set to 20000 (zindex=20000), and the escape key can be used to hide the dimmer (escapetohide=true).
http://ds.serving-sys.com/BurstingRes/CustomScripts/html5_block_background_dimmer_v1.js?color=000&opacity=0.8&fadetime=500&auto=true&duration=10000&zindex=20000&escapetohide=true
If you set a duration for the dimmer, you can cancel it using the “cancelDimmerTimer” message. For example, if a user engages with your ad, you may want to stop the dimmer from automatically fading out.
EB._sendMessage("cancelDimmerTimer");
It is fine to use the script parameters without the JavaScript API, to use the JavaScript API without setting script parameters, or to use both in conjunction. Just make sure you are satisfying your publisher’s specifications. The “escapetohide” parameter has a catch. After the user has focused on the ad, by clicking on it, for example, the background dimmer script can no longer listen for the escape key. Therefore, the escape key will not hide the dimmer after the user has focused on the ad. In order to get around this problem, you can add an escape key listener in your ad and send the “hideDimmer” message when it is pressed. If you would like to know if the escape key is enabled in the custom script, send the “getDimmerEscapeToHideStatus” message from your ad, and listen for “dimmerEscapeToHideStatus” message to come back. Check the “isEnabled” property of the data that is sent back to see if the escape key is enabled in the custom script. There is code in the block that shows how to achieve this effect. Here is a portion:
window.addEventListener("message", handleMessage, false);
function handleMessage(e) {
var event = JSON.parse(e.data);
switch(event.type) {
case "dimmerEscapeToHideStatus":
if (event.data.isEnabled) {
// add escape key listener
}
break;
}
}
You can also listen for when the escape key is pressed outside of the iframe by listening for the “dimmerEscapeToHide” message. For example, you may want to track pressing escape to hide as a user action.
window.addEventListener("message", handleMessage, false);
function handleMessage(e) {
var event = JSON.parse(e.data);
switch(event.type) {
case " dimmerEscapeToHide":
// handle escape key pressed
break;
}
}
Setting Up the Background Dimmer Ad Feature in the Sizmek Platform
Sizmek MDX2.0 Setup
Archive the Background Dimmer workspace into ZIP files, preserving the directory structure. You can do this with WinZip, 7Zip, or another archiving program.
- Zip and upload the HTML5 Workspace Folder found in the template folder.
- Log into the MDX2.0 Platform.
- Click on Manage > Creative Assets, and upload your Workspace to the appropriate asset folder
- (Optional) Rename the folder.
- From the main menu, select Shortcuts > Create New Ad > Create a New Ad.
- In the Ad Name field, enter the unique name of your ad.
- Choose a format from the format type drop-down.
- Choose the HTML5 Workspace Folder you uploaded to platform.
- Navigate to Advanced Features > Custom JS and enter the following Custom Script: https://secure-ds.serving-sys.com/burstingres/CustomScripts/html5_block_background_dimmer_v1.js.
- Save.
Sizmek Advertising Suite Setup
- Zip the HTML5 Workspace Folder found in the template folder.
- Log in to the Sizmek Advertising Suite.
- Click the Creative menu item > Asset Library, and upload your Workspace to the appropriate asset folder.
- (Optional) Rename the folder.
- Click Creative > Ads and click New Ad and select Blank Ad.
- In the Ad Name field, enter the unique name of your ad.
- Choose a format from the Ad Format drop-down.
- Under Main Assets select the Workspace folder and default image.
- Under Clickthrough & Events > Events, add a new On Ad Download Event and add the following Custom Script: https://secure-ds.serving-sys.com/burstingres/CustomScripts/html5_block_background_dimmer_v1.js.
- Save.
Custom Interactions
Interaction Name |
Description |
|
Track when the dimmer is shown by the user |
|
Track when the dimmer is hidden by the user |
Change Log
October 04, 2016
- Updated for AdKit
- Updated for secure protocol
- Migrated to Sizmek Advertising Suite
- Fixed dimmer resize issue - dimmer width was being set to window width and not page width. If browser was minimized and scrollbar was present, dimmer would not expand to full width, but to the width of the window.
March 4, 2016
- Added Ad Feature Tracking
June 09, 2013
Initial Release
Can we please include whether this feature is supported in a Safeframe?