studio.Enabler
The core library for building Studio HTML ads.

Jump to API Reference

Including The Enabler

This is the snippet to insert the Studio enabler into your document.

<script src="https://s0.2mdn.net/ads/studio/Enabler.js">
</script>

Waiting For Initialization

The enabler has an asyncronous setup process so please wait for the INIT event before starting your ad.

<script>
if (!Enabler.isInitialized()) {
  Enabler.addEventListener(
    studio.events.StudioEvent.INIT,
    enablerInitialized);
} else {
   enablerInitialized();
}
function enablerInitialized() {
  // Enabler initialized.
  // In App ads are rendered offscreen so animation should wait for
  // the visible event. These are simulated with delays in the local
  // environment.
  if (!Enabler.isVisible()) {
    Enabler.addEventListener(
      studio.events.StudioEvent.VISIBLE,
      adVisible);
  } else {
     adVisible();
  }
}
function adVisible() {
  // Ad visible, start ad/animation.
}
</script>

Basic Metric Reporting

Basic metric reporting for Exits, Counters, and Timers.

<script>
// Exits.
Enabler.exit("Click on BG");
// Exits; overriding exit.
Enabler.exitOverride("Click on BG", "http://www.google.com");
// Counters.
Enabler.counter("Clicked on tab 1");
// Timers
Enabler.startTimer("Spinning car");
Enabler.stopTimer("Spinning car");
</script>

Expanding and Collapsing

Configuration

For Expanding Ads, we can set various parameters and flags for the expansion using setExpandingPixelOffsets, setStartExpanded, and setIsMultiDirectional.

The following example is a multi directional expanding ad that is 300x250 when collapsed and expands to 500x350 when expanded. The entire size is 700x450 to accommodate for the direction it expands in. 

<head>
<script type="text/javascript">
// Can be called before INIT event.
Enabler.setExpandingPixelOffsets(
  200, // left offset of expanded ad
  100, // top offset of expanded ad
  700, // expanded width of ad
  450); // expanded height of ad
Enabler.setStartExpanded(false);
  // whether to start in expanded state (defaults to false)
Enabler.setIsMultiDirectional(true);
  // multidirectional ads expand in the "best available" direction
  // (default false)
// Listen for INIT/VISIBLE of Enabler here.
</script>
...
</head>

Lifecycle

Expanding ads need to adhere to a specific asyncronous lifecycle. Below is a list of methods, events, with explanations of the expanding and collapsing flows, as well as a complete example.

Events

  • studio.events.StudioEvent.EXPAND_START
  • studio.events.StudioEvent.EXPAND_FINISH
  • studio.events.StudioEvent.COLLAPSE_START
  • studio.events.StudioEvent.COLLAPSE_FINISH

Methods

  • Enabler.requestExpand()
  • Enabler.finishExpand()
  • Enabler.requestCollapse()
  • Enabler.finishCollapse()

Expanding flow

  1. Register event listeners.
  2. When you want to expand call Enabler.requestExpand().
  3. When the environment is ready to expand the studio.events.StudioEvent.EXPAND_START is dispatched.
  4. The Ad optionally performs an animated expansion.
  5. Ad then calls Enabler.finishExpand() to complete expansion. This makes sure pushdowns are syncronized.

Collapsing flow

  1. Register event listeners.
  2. When you want to collapse call Enabler.requestCollapse().
  3. When the environment is ready to collapse the studio.events.StudioEvent.COLLAPSE_START is dispatched. This can get dispatched independently of Enabler.requestCollapse() as sometimes the environment provides a close button outside of the creative.
  4. The Ad optionally performs an animated collapse.
  5. Ad then calls Enabler.finishCollapse() to complete collapse and close div.

Complete example 

<head>
<script type="text/javascript">
var isExpanded = false;

function expandStartHandler() {
  // Perform expand animation.
  // Optionally, should you want the direction to expand in call:
  // Enabler.getExpandDirection(); //
  // When animation finished must call
  Enabler.finishExpand();
}

function expandFinishHandler() {
  // Convenience callback for setting
  // final state when expanded.
  isExpanded = true;
}

function collapseStartHandler() {
  // Perform collapse animation.
  // When animation finished must call
  Enabler.finishCollapse();
}

function collapseFinishHandler() {
  // Convenience callback for setting
  // final state when collapsed.
  isExpanded = false;
}

function actionClickHandler() {
  isExpanded ? Enabler.requestCollapse() : Enabler.requestExpand();
}

Enabler.addEventListener(
  studio.events.StudioEvent.EXPAND_START,
  expandStartHandler);
Enabler.addEventListener(
  studio.events.StudioEvent.EXPAND_FINISH,
  expandFinishHandler);
Enabler.addEventListener(
  studio.events.StudioEvent.COLLAPSE_START,
  collapseStartHandler);
Enabler.addEventListener(
  studio.events.StudioEvent.COLLAPSE_FINISH,
  collapseFinishHandler);
actionBtn.addEventListener(
  'click',
  actionClickHandler,
  false);
</script>
...
</head>

Fullscreen Expand

Lifecycle

Fullscreen ads have a lifecycle that is similar to expanding ads. Differences are noted below.

Events

  • studio.events.StudioEvent.FULLSCREEN_SUPPORT
  • studio.events.StudioEvent.FULLSCREEN_DIMENSIONS
  • studio.events.StudioEvent.FULLSCREEN_EXPAND_START
  • studio.events.StudioEvent.FULLSCREEN_EXPAND_FINISH
  • studio.events.StudioEvent.FULLSCREEN_COLLAPSE_START
  • studio.events.StudioEvent.FULLSCREEN_COLLAPSE_FINISH

Methods

  • Enabler.queryFullscreenSupport()
  • Enabler.queryFullscreenDimensions()
  • Enabler.requestFullscreenExpand(opt_width, opt_height)
  • Enabler.finishFullscreenExpand()
  • Enabler.requestFullscreenCollapse()
  • Enabler.finishFullscreenCollapse()

Expanding flow

  1. Register event listeners.
  2. To determine if fullscreen is available, call Enabler.queryFullscreenSupport().
  3. To determine the maximum available size for expanding, call Enabler.queryFullscreenDimensions().
  4. When you want to expand call Enabler.requestFullscreenExpand(). You can pass a set of dimensions to expand to, or omit the dimensions to expand to the maximum possible size.
  5. Subsequent steps are the same as normal expand, just use the analogous method calls and events.

Collapsing flow

Collapse flow is exactly analogous to the collapse flow for normal expanding ads.

Inheritance

Constructor

studio.Enabler(useSingletonGetter)

Parameters

useSingletonGetter : number
Use studio.Enabler.getInstance() or alias Enabler to get enabler instance.

Instance Methods

Defined in studio.Enabler
addEventListener(type, , opt_capture, opt_handlerScope)
Adds an event listener to the event target. The same handler can only be added once per the type. Even if you add the same handler multiple times using the same type then it will only be called once when the event is dispatched.
Arguments:
type : string
The type of the event to listen for.
: function(*):* | {handleEvent:function(*):*
No description.
opt_capture : boolean=
In DOM-compliant browsers, this determines whether the listener is fired during the capture or bubble phase of the event.
opt_handlerScope : Object=
Object in whose scope to call the listener.
addMessageHandler(messageName, handler)
Adds a new handler for an otherwise unknown message.
Arguments:
messageName : string
The name of the message, which cannot match an exported method on studio.Enabler.
handler : Function
The handler function.
callAfterInitialized(callback)
Calls the callback when the enabler is initialized or after.
Arguments:
callback : Function
The callback to invoke when the enabler is initialized or if it has already initialized, call immediately.
close()
Closes floating and popup creative types. If it is an expanding creative, close acts as a proxy to collapse.
closeCompanion()
Closes the companion asset for floating, reminder, and pop-up creative types.
collapse()
Use requestCollapse() instead. Clips the container of the html asset from the expanded dimensions to the collapsed dimensions. Please use event listeners to invoke the collapse action as it may be called by the environment independently of calling studio.Enabler#collapse(). 
Enabler.addEventListener(
    studio.events.StudioEvent.COLLAPSE,
    function() {
      // collapse action
    });
This function is only applicable for expandable ad formats.
counter(eventId, opt_isCumulative)
Tracks a counter event.
Arguments:
eventId : string
The string ID of the event to count.
opt_isCumulative : boolean=
Optional parameter that indicates whether or not the counter event should be counted cumulatively.
displayCompanion()
Triggers the display of the companion asset for floating, reminder, and pop-up advert types.
exit(id, opt_url)
Opens a new window with the URL as identified by the given exit ID.
Arguments:
id : string
The exit ID.
opt_url : string=
The url to navigate to. This URL can still be modified in Studio and DCM. If you want this URL to be uneditable Studio and DCM, use the exitOverride method instead.
exitOverride(id, url)
Opens a new window with the URL as identified by the given exit ID. This differs from normal exit() as the url value will always override the value modified in Studio or elsewhere.
Arguments:
id : string
The exit ID.
url : string
The url to navigate to regardless of what has been set in Studio.
exitQueryString(id, opt_queryString)
Opens a new window with the URL as identified by the given exit ID with an optional queryString appended.
Arguments:
id : string
String ID of exit.
opt_queryString : string=
Desired query string value(s) to append to the end of the exit URL.
expand(opt_disableTracking, opt_expandProperties)
Use studio.Enabler#requestExpand(). Unclips the container of the html asset from the collapsed dimensions to the expanded dimensions. This function is only applicable for expandable ad formats.
Arguments:
opt_disableTracking : boolean=
Whether or not this expand causes an event to be logged. This is useful for creatives that start out expanded and don't want to log the first expand.
opt_expandProperties : Object=
The properties to expand with. This is used in mobile environments supporting MRAID. The object will look like the following: 

    expandProperties object = {
      'width': integer,
      'height': integer,
      'useCustomClose': boolean,
      'isModal': boolean (read only)
    }
.
finishCollapse()
Clips the container of the html asset from the expanded dimensions to the collapsed dimensions. Please use event listeners to invoke the collapsed state of the ad as the collapse event may be dispatched by the environment independently of calling studio.Enabler#requestCollapse(). 
Enabler.addEventListener(
    studio.events.StudioEvent.COLLAPSE_START,
    function() {
      // collapse action
      Enabler.finishCollapse();
    });
Enabler.requestCollapse();
This function is only applicable for expandable ad formats.
finishExpand()
Finalizes the expand call via the rendering code.
finishFullscreenCollapse()
Finishes fullscreen collapse.
finishFullscreenExpand()
Finishes fullscreen expand.
getContainerState() ⇒ studio.sdk.ContainerState
Returns the current state of the container.
Returns: studio.sdk.ContainerState  The container state.
getDartAdId() ⇒ ?number
Returns the DART ad ID.
Returns: ?number  Integer value of the ID number (generated by DART) that identifies the ad.
getDartAssetId() ⇒ ?string
Returns the DART asset ID.
Returns: ?string  The ID (generated by DART) that identifies the creative.
getDartCreativeId() ⇒ ?number
Returns the DART creative ID.
Returns: ?number  The ID number (generated by DART) that identifies the creative.
getDartPageId() ⇒ ?number
Returns the DART page ID.
Returns: ?number  The ID number (generated by DART) that identifies the zone where the creative is served.
getDartRenderingId() ⇒ ?string
Returns the DART rendering ID.
Returns: ?string  The ID (generated by DART) that identifies the rendering version of the creative.
getDartSiteId() ⇒ ?number
Returns the DART site ID.
Returns: ?number  Integer value of the ID number that identifies the site where the creative is served, as defined in DART.
getDartSiteName() ⇒ ?string
Returns the DART site name.
Returns: ?string  The name of the site where the creative is served, as defined in DART.
getExpandDirection() ⇒ studio.common.mde.Direction
Returns the expand direction.
Returns: studio.common.mde.Direction  The direction to expand in.
getFilename(originalFilename) ⇒ string
Use getUrl(filename). Returns the runtime file name given the original compile-time file name. The original file name may have been mapped to a newer file name.
Arguments:
originalFilename : string
The original file name of the asset.
Returns: string  The file name to be used at runtime when served through DoubleClick Studio and DART.
getOrientation() ⇒ studio.common.Orientation
Returns an object representing the orientation of the device.
Returns: studio.common.Orientation  An object representing the orientation of the device.
getParameter(variableName) ⇒ *
Retrieves a creative parameter that the user can pass via queryString URL. This is also used internally to access ad configuration data.
Arguments:
variableName : string
Name of the variable to get.
Returns: *  Value of the parameter.
getParameterAsInteger(name) ⇒ ?number
Retrieves a creative parameter as an integer.
Arguments:
name : string
Name of the variable to get.
Returns: ?number  Value of the parameter or null if the parameter is undefined.
getParameterAsNullableString(name) ⇒ ?string
Retrieves a creative parameter as a nullable string.
Arguments:
name : string
Name of the variable to get.
Returns: ?string  Value of the parameter or null if the parameter is undefined.
getProfileId() ⇒ number
Get the dynamic creative profile id.
Returns: number  Returns the dynamic creative profile id.
getUrl(filepath) ⇒ string
Gets the runtime URL given the original compile-time filename.
Arguments:
filepath : string
The original full path of the asset
Returns: string  The URL to be used at runtime when served through Studio and DART.
getUserAreaCode() ⇒ ?string
Retrieving a user's area code will soon be unavailable. Returns the user's area code.
Returns: ?string  The user's area code.
getUserBandwidth() ⇒ number
Returns the user's bandwidth according to DART bandwidth codes. Only supported for personalized ads.
Returns: number  An integer representing the user's bandwidth. Bandwidth values are:
  1. Unknown = 0
  3. Dialup = 1
  4. DSL = 2
  5. Cable = 3
  6. Broadband = 4
  7. T1 = 5
.
getUserCountry() ⇒ ?string
Returns the two-letter string representation of the user's country. Only supported for personalized ads.
Returns: ?string  Two-letter string representation of the user's country. Null is returned if country data is unavailable.
getUserDMACode() ⇒ ?number

Deprecated

Returns the DART representation of the user's Nielsen Designated Market Area.
Returns: ?number  A DART representation of the user's Nielson Designated Market Area.
getUserState() ⇒ ?string
Returns the two-letter string representation of the user's state or province. Only supported for personalized ads.
Returns: ?string  Two-letter string representation of the user's state or province. Null is returned if state/province is unavailable.
getUserZipCode() ⇒ ?string
Returns the user's zip code (for users in the United States, U.S. territories, and Canada). Only supported for personalized ads.
Returns: ?string  The user's zip code as supplied by the ad server. Null value is returned if zip code is unavailable.
hasUserInteracted() ⇒ boolean
Checks if a user has interacted with the document. 
if (Enabler.hasUserInteracted()) {
  // Do expensive request.
}
Returns: boolean  Whether the user has interacted with the document.
invokeExternalJsFunction(functionName)
Invoke a function in the parent container. This could be the top frame if served via a adj (script) tag, the serving iframe if served via and adi (iframe) tag.
Arguments:
functionName : string
The function name to invoke.
invokeMraidMethod(methodName, opt_args, opt_callback)
Invoke a function on the mraid api. This is different from invokeExternalJsFunction as you are given the results of the function in a callback.
Arguments:
methodName : studio.sdk.MraidMethod
The method name to invoke on the mraid object. You can also use dot accessors to access subobjects if they are ever introduced. For instance, 'package.method', would call window.mraid.package.method().
opt_args : Array=
The arguments to invoke the method with.
opt_callback : function(?Object)=
A callback that gets invoked with the results of the function call.
isInitialized() ⇒ boolean
Returns whether the Enabler is intialized.
Returns: boolean  Whether the Enabler is intialized.
isPageLoaded() ⇒ boolean
Returns whether the parent page has loaded. The iframe is notified when the page has loaded and dispatches the StudioEvent.PAGE_LOADED event.
Returns: boolean  Whether the parent page has loaded or not.
isServingInLiveEnvironment() ⇒ boolean
Returns whether the ad is serving in the live environment or not.
Returns: boolean  Whether the ad is serving in the live environment or not.
isVisible() ⇒ boolean
Returns whether the ad is visible. The iframe is notified when the ad is visible and the enabler dispatches the StudioEvent.VISIBLE event.
Returns: boolean  Whether the ad is visible or not.
loadModule(moduleName, opt_loadedCallback)
Loads an additional module.
Arguments:
moduleName : studio.module.ModuleId
The name of the module to load.
opt_loadedCallback : Function=
The callback to invoke when the module is loaded.
loadScript(scriptUrl, opt_loadedCallback)
Loads an additional script file.
Arguments:
scriptUrl : string
The url of the script to load.
opt_loadedCallback : Function=
The callback to invoke when the script is loaded.
queryFullscreenDimensions()
Initiates a query for the maximum allowable fullscreen dimensions. A studio.event.StudioEvent.FULLSCREEN_DIMENSIONS event will be dispatched with the maximum allowed width and height as properties. Some publishers may pad the fullscreen window for a lightbox-like experience. Because of this the maximum allowable dimensions may not take up the entire browser window or screen.
queryFullscreenSupport()
Initiates a query to find out whether mock fullscreen expansion mode is supported. Please listen for the studio.event.StudioEvent.FULLSCREEN_SUPPORT event. This event will contain the support status.
registerChargeableEventName(eventName)
Provide a method that allows the creative to define a chargeable event. 
Enabler.registerChargeableEventName("SWIPE");
Arguments:
eventName : string
String name for which a counter or timer event will be will be will be triggered in the creative execution.
removeEventListener(type, , opt_capture, opt_handlerScope)
Removes an event listener from the event target. The handler must be the same object as the one added. If the handler has not been added then nothing is done.
Arguments:
type : string
The type of the event to listen for.
: function(*):* | {handleEvent:function(*):*
No description.
opt_capture : boolean=
In DOM-compliant browsers, this determines whether the listener is fired during the capture or bubble phase of the event.
opt_handlerScope : Object=
Object in whose scope to call the listener.
removeMessageHandler(messageName)
Removes a new handler for an otherwise unknown message.
Arguments:
messageName : string
The name of the message, which cannot match an exported method on studio.Enabler.
reportCustomClickVariable(postString)
Use studio.Enabler#reportCustomVariableCount1(custom).

Deprecated

This tracks a click against the string parameter. The string must meet the following criteria:
  • The string cannot exceed 100 characters
  • The string must only contain Latin characters (0-9, Aa-Zz)
  • The String must NOT contain any personally identifiable information such as name, email address, phone number, health info, financial info, etc.
Additionally, all question marks (?) and anything after the first question mark in a string will be truncated.
Arguments:
postString : string
Value to record against the click.
reportCustomImpressionVariable(postString)
Use studio.Enabler#reportCustomVariableCount1(custom).

Deprecated

Tracks an impression against the string parameter. The string must meet the following criteria:
  • The string cannot exceed 100 characters
  • The string must only contain Latin characters (0-9, Aa-Zz)
  • The String must NOT contain any personally identifiable information such as name, email address, phone number, health info, financial info, etc.
Additionally, all question marks (?) and anything after the first question mark in a string will be truncated.
Arguments:
postString : string
Value to record against the impression.
reportCustomVariableCount1(customString)
Counts instances of the string parameter, aggregated as Custom Variable Count 1 in reports. The string must meet the following criteria:
  • The string cannot exceed 100 characters
  • The string must only contain Latin characters (0-9, Aa-Zz)
  • The String must NOT contain any personally identifiable information such as name, email address, phone number, health info, financial info, etc.
Additionally, all question marks (?) and anything after the first question mark in a string will be truncated.
Arguments:
customString : string
Value to record against custom variable count 1.
reportCustomVariableCount2(customString)
Counts instances of the string parameter, aggregated as Custom Variable Count 2 in reports. The string must meet the following criteria:
  • The string cannot exceed 100 characters
  • The string must only contain Latin characters (0-9, Aa-Zz)
  • The String must NOT contain any personally identifiable information such as name, email address, phone number, health info, financial info, etc.
Additionally, all question marks (?) and anything after the first question mark in a string will be truncated.
Arguments:
customString : string
Value to record against custom variable count 2.
reportManualClose()
Records a manual closing of a floating, pop-up, expanding, in-page with pop-up, or in-page with floating ad.
requestCollapse()
Initiates the collapse lifecycle. This begins by calling requestCollapse(), waiting for the COLLAPSE_START event, animating your collapse, then calling finishCollapse() when the creative has fully collapsed. Please use event listeners to invoke the collapsed state of the ad as the collapse event may be dispatched by the environment independently of calling studio.Enabler#requestCollapse(). 
Enabler.addEventListener(
    studio.events.StudioEvent.COLLAPSE_START,
    function() {
      // Do collapse action then...
      Enabler.finishCollapse();
    });
Enabler.requestCollapse();
This function is only applicable for expandable ad formats.
requestExpand()
Initiates the expand lifecycle. This begins by calling requestExpand(), waiting for the EXPAND_START event, animating your expand, then calling finishExpand() when the creative has fully expanded. Please use event listeners to invoke the expanded state of the ad as the expand may be dispatched by the environment independently of calling studio.Enabler#requestExpand(). This is especially true on networks such as the Google Display Network that display a hover timer before allowing the ad to expand. Typical usage will look like: 
Enabler.addEventListener(
    studio.events.StudioEvent.EXPAND_START,
    function(event) {
      // For multi directional expands, direction to expand in can be
      // obtained by calling Enabler.getExpandingDirection() (or
      // from event.direction).

      // Do expand action then...
      Enabler.finishExpand();
    });
Enabler.requestExpand();
This function is only applicable for expandable ad formats.
requestFullscreenCollapse()
Requests fullscreen collapse. Please listen for the studio.event.StudioEvent.FULLSCREEN_COLLAPSE_START event to start collapse.
requestFullscreenExpand(opt_width, opt_height)
Requests fullscreen expand. If width and height are provided, expands to a rectangle of that width and height centered in the middle of the display (or browser window, if the browser is not fullscreen). Otherwise expands to the full size of the browser window/display. Note that on mobile devices the browser window typically takes up the entire display.
Arguments:
opt_width : number=
Width we would like to expand to in pixels.
opt_height : number=
Height we would like to expand to in pixels.
setDevDynamicContent(value)
Set the dynamic content development values.
Arguments:
value : Object
The Dynamic Content development values.
setExpandingPixelOffsets(left, top, opt_expandedWidth, opt_expandedHeight, opt_startExpanded, opt_isMultiDirectional)
Sets the pixel offsets for the collapsed portion of the ad. This does not affect the local testing environment but when the ad is live the collapsed portion will be shown at 0x0. This method works by setting the marginLeft and marginTop of the body element which is set to relative positioning.
Arguments:
left : number
The left offset to the collapsed portion of the ad.
top : number
The top offset to the collapsed portion of the ad.
opt_expandedWidth : number=
The expanded width of this asset.
opt_expandedHeight : number=
The expanded height of this asset.
opt_startExpanded : boolean=
Whether this asset starts expanded, this will disable tracking, expansion timer, not log an interactive impression when the initial requestExpand is called. Note: this parameter is deprecated.
opt_isMultiDirectional : boolean=
Whether this the ad supports multidirectional expands. Note: this parameter is deprecated.
setFloatingPixelDimensions(width, height)
Prepopulates the width and height of a floating or peeldown creative.
Arguments:
width : number
The width of this asset.
height : number
The height of this asset.
setHint(name, value) ⇒ studio.Enabler
Adds a Hint to this creative
Arguments:
name : studio.sdk.hint.Hint
The name of the hint we want to add.
value : string
The value of the hint we want to add.
Returns: studio.Enabler  this.
setIsMultiDirectional(isMultiDirectional)
Sets the isMultiDirectional flag.
Arguments:
isMultiDirectional : boolean
Whether the ad is configured as multidirectional.
setProfileId(value)
Set the dynamic creative profile id.
Arguments:
value : number
Profile id.
setStartExpanded(startExpanded)
Sets the startExpanded flag, which controls whether the asset starts in the expanded state or not. If true, then when the initial requestExpand call will not be tracked or logged and will not trigger an expansion timer.
Arguments:
startExpanded : boolean
Value of the flag.
setUseCustomClose(useCustomClose)
Sets useCustomClose. This is primarily of use in mobile environments using MRAID. When this flag is set, it means that the creative will provide its own close button, so MRAID doesn't have to provide one.
Arguments:
useCustomClose : boolean
Value of the flag.
startTimer(timerId)
Starts an event timer.
Arguments:
timerId : string
The string ID of the timer to start.
stopTimer(timerId)
Stops an event timer.
Arguments:
timerId : string
The string ID of the timer to stop.

Static Methods

studio.Enabler.getInstance() ⇒ !studio.Enabler
Returns the instance of the enabler singleton.
Returns: !studio.Enabler  No description.

Package studio

Package Reference