Google
Go to class or file:
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.
-
studio.events.StudioEvent.EXPAND_START -
studio.events.StudioEvent.EXPAND_FINISH -
studio.events.StudioEvent.COLLAPSE_START -
studio.events.StudioEvent.COLLAPSE_FINISH
-
Enabler.requestExpand() -
Enabler.finishExpand() -
Enabler.requestCollapse() -
Enabler.finishCollapse()
- Register event listeners.
- When you want to expand call
Enabler.requestExpand(). - When the environment is ready to expand the
studio.events.StudioEvent.EXPAND_STARTis dispatched. - The Ad optionally performs an animated expansion.
- Ad then calls
Enabler.finishExpand()to complete expansion. This makes sure pushdowns are syncronized.
- Register event listeners.
- When you want to collapse call
Enabler.requestCollapse(). - When the environment is ready to collapse the
studio.events.StudioEvent.COLLAPSE_STARTis dispatched. This can get dispatched independently ofEnabler.requestCollapse()as sometimes the environment provides a close button outside of the creative. - The Ad optionally performs an animated collapse.
- Ad then calls
Enabler.finishCollapse()to complete collapse and close div.
<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.
-
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
-
Enabler.queryFullscreenSupport() -
Enabler.queryFullscreenDimensions() -
Enabler.requestFullscreenExpand(opt_width, opt_height) -
Enabler.finishFullscreenExpand() -
Enabler.requestFullscreenCollapse() -
Enabler.finishFullscreenCollapse()
- Register event listeners.
- To determine if fullscreen is available, call
Enabler.queryFullscreenSupport(). - To determine the maximum available size for expanding, call
Enabler.queryFullscreenDimensions(). - 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. - Subsequent steps are the same as normal expand, just use the analogous method calls and events.
Collapse flow is exactly analogous to the collapse flow for normal expanding ads.
Useful links
Inheritance
studio.Enabler
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.
|
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.
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.
|
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. |
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:
. |
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.Returns an object representing the orientation of the device.
Returns:
studio.common.Orientation
An object representing the orientation of
the device.
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.
|
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. 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.
Arguments:
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.
Arguments:
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.
Arguments:
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.
Arguments:
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. 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.
|
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.
|
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.
