PRODUCT
Follow

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

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

    EB._sendMessage("showDimmer");

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

    EB._sendMessage("hideDimmer");

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

    EB._sendMessage("toggleDimmer");

  1. 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 ManageCreative 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

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

  • Avatar
    Joaquin Estrada

    Can we please include whether this feature is supported in a Safeframe?