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	Sizmek_Background_Dimmer_HTML5_10_0_1.zip
Demo	Preview 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
images/backup.jpg	Background Dimmer Demo Backup image
images/logo.png	Sizmek logo image
index.html	Background Dimmer Demo HTML file.
script.js	Background Dimmer Javascript file
style.css	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.

1. 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});

2. When you are ready to dim the page, you can use the following method call to show the dimmer:

    EB._sendMessage("showDimmer");

3. When you want to hide the dimmer, use the following method call:

    EB._sendMessage("hideDimmer");

4. Alternately, you can use the following message to toggle the dimmer on and off:

    EB._sendMessage("toggleDimmer");

5. 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
showDimmer	Object [optional]	Show the background dimmer. You can optionally pass in parameters to specify color, opacity, and fade time.
hideDimmer	Object [optional]	Hide the background dimmer. You can optionally pass in parameters to specify color, opacity, and fade time.
toggleDimmer	Object [optional]	Toggle the background dimmer on and off. You can optionally pass in parameters to specify color, opacity, and fade time.
setDimmer	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.
cancelDimmerTimer	None	Stop the background dimmer from fading out automatically.
getDimmerStatus	None	Request the current status of the dimmer.
getDimmerEscapeToHideStatus	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.

1. Zip and upload the HTML5 Workspace Folder found in the template folder.
2. Log into the MDX2.0 Platform.
3. Click on Manage > Creative Assets, and upload your Workspace to the appropriate asset folder
4. (Optional) Rename the folder.
5. From the main menu, select Shortcuts > Create New Ad > Create a New Ad.
6. In the Ad Name field, enter the unique name of your ad.
7. Choose a format from the format type drop-down.
8. Choose the HTML5 Workspace Folder you uploaded to platform.
9. 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.
10. Save. 

Sizmek Advertising Suite Setup

1. Zip the HTML5 Workspace Folder found in the template folder.
2. Log in to the Sizmek Advertising Suite.
3. Click the Creative menu item > Asset Library, and upload your Workspace to the appropriate asset folder.
4. (Optional) Rename the folder.
5. Click Creative > Ads and click New Ad and select Blank Ad.
6. In the Ad Name field, enter the unique name of your ad.
7. Choose a format from the Ad Format drop-down.
8. Under Main Assets select the Workspace folder and default image.
9. 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.
10. Save. 

Custom Interactions

Interaction Name	Description
ShowDimmer	Track when the dimmer is shown by the user
HideDimmer	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