MediaVoice Plugin v1.244.0 Namespace: Callbacks

Managed Mode callbacks are JavaScript functions that run when your creatives load and render.

Each of your Managed Mode layouts has its own JavaScript code for each callback. This lets you write any layout-specific JavaScript code that you need.

The callback functions are:

Custom Injection Location: ManagedMode.Callbacks.customInjection
Fill: ManagedMode.Callbacks.onFill
Render: ManagedMode.Callbacks.onRender
Error: ManagedMode.Callbacks.onError

Type Definitions

Advertiser

An Advertiser object.

Type:

Object

Properties:

Name	Type	Description
`name`	string	The advertiser's name.
`vertical`	ManagedMode.Callbacks.Vertical	The advertiser's vertical.

Author

An Author object.

Type:

Object

Properties:

Name	Type	Description
`name`	string	The name of the author.

Campaign

A Campaign object.

Type:

Object

Properties:

Name	Type	Description
`advertiser`	ManagedMode.Callbacks.Advertiser	The campaign's advertiser.
`name`	string	The campaign's name.
`team`	ManagedMode.Callbacks.Team	The team that owns this campaign.

Channel

The channel tells us whether we are running inside a normal web page, an AMP page, a mobile app, etc.

Type:

Object

Properties:

Name	Type	Description
`name`	"amp" \| "applenews" \| "instant-article" \| "mobileapp" \| "web"	The name of the channel.

Conditions

A Conditions object is a set of predicates that are matched against how the creative was served.

Type:

Object

Properties:

Name	Type	Argument	Description
`adUnit`	string	<optional>	Ad unit condition. The format depends on the ad server. For example: `/hello/world/12345`
`iframesize`	string	<optional>	Iframe size condition. For example: `1x2`
`page`	string	<optional>	A page condition is a regular expression that matches against the page URL.
`placementKey`	string	<optional>	The "placement key" value that was used in the ad request.

Creative

A MediaVoice creative.

Type:

Object

Properties:

Name	Type	Argument	Description
`author`	ManagedMode.Callbacks.Author	<optional>	The creative's author.
`campaigns`	Array.<ManagedMode.Callbacks.Campaign>		Array of campaigns to which this creative belongs.
`content`	string	<optional>	The HTML content of the creative. This is relevant to a Hosted Content creative. (The `type` value for Hosted Content is `"article"`.)
`cta`	Array.<ManagedMode.Callbacks.CTA>	<optional>	An array of the creative's CTA (call-to-action) objects.
`custom`	Object	<optional>	The creative's custom fields.
`embeds`	Array.<ManagedMode.Callbacks.Embed>	<optional>	The creative's embedded content, for example, social media posts. This property is set only on the `creative` argument to `ManagedMode.Callbacks.onFill`, not the creatives in the `context` argument.
`experienceHash`	string		The unique identifier for the creative's "experience". This will differ between different variants of the same creative, when optimization is being used.
`id`	string		The unique identifier for the creative's "instance".
`image`	ManagedMode.Callbacks.Thumbnail	<optional>	The creative's main thumbnail image.
`layoutType`	"single_creative" \| "collection"	<optional>	The layout type. This property is set only on the `creative` argument to `ManagedMode.Callbacks.onFill`, not the creatives in the `context` argument.
`link`	string	<optional>	The creative's destination URL.
`pubDate`	string	<optional>	The creative's publication date. The format is: `YYYY-MM-DD` `"T"` `HH:mm:ss` `"Z"` For example: `"2017-05-27T18:00:48Z"`
`render`	ManagedMode.Callbacks.LayoutRenderOptions	<optional>	Options that affect how the layout is rendered. This property is set only on the `creative` argument to `ManagedMode.Callbacks.onFill`, not the creatives in the `context` argument.
`rule`	ManagedMode.Callbacks.Rule	<optional>	The rule whose conditions were matched. This property is set only on the `creative` argument to `ManagedMode.Callbacks.onFill`, not the creatives in the `context` argument.
`sponsor`	ManagedMode.Callbacks.Sponsor	<optional>	The sponsor. This property is set only on the `creative` argument to `ManagedMode.Callbacks.onFill`, not the creatives in the `context` argument.
`summary`	string	<optional>	The creative's summary.
`team`	ManagedMode.Callbacks.Team		The team that owns this creative.
`title`	string	<optional>	The creative's title.
`type`	"article" \| "deck" \| "facebook-post" \| "inbound" \| "instagram-media" \| "outbound" \| "tweet"		The creative's experience type. `"article"` Hosted Content `"deck"` Lightbox `"facebook-post"` Facebook Content `"inbound"` Web Content `"instagram-media"` Instagram Content `"outbound"` External Content `"tweet"` Twitter Content

CTA

A CTA (call-to-action) object.

Type:

Object

Properties:

Name	Type	Argument	Description
`destUrl`	string		The destination URL.
`id`	string		Unique identifier for the CTA.
`image`	ManagedMode.Callbacks.Logo	<optional>	The CTA image. Usually this is the sponsor's logo.
`sponsorName`	string	<optional>	The CTA sponsor's name.
`type`	"sponsorlogolink" \| "sponsornamelink"		The CTA type. It may be a sponsor's logo (image) or a sponsor's name (text).

customInjection(templateContext) → {InjectionStrategy}

This callback is executed immediately before the rendered template is injected onto the page.

This callback should return an object with two optional properties: "injectionTarget" and "injectionBehavior".

These properties can be modified to control the template's injection location.

Parameters:

Name	Type	Description
`templateContext`	ManagedMode.Callbacks.TemplateContext	The jQuery-wrapped, fully-rendered, template element.

Returns:

An InjectionStrategy object which specifies the template's injection target and the injection behavior.

Type: InjectionStrategy

Example

(function(templateContext) {
    // Inject the template after the specified
    // element's (id="river") children.
    return {
      "injectionTarget": window.top.document.getElementById("river"),
      "injectionBehavior": "append",
    };
})

Embed

An Embed object represents embedded content such as social media posts.

Type:

Object

Properties:

Name Type Description

type

Object

Information about the embedded content type.

Properties

Name	Type	Argument	Description
`tweet`	boolean	<optional>	True if the embed is a post from Twitter.
`instagram-media`	boolean	<optional>	True if the embed is a post from Instagram. Ensure that you access this property with quotes; for example: `if (embed.type["instagram-media"]) {}`
`facebook-post`	boolean	<optional>	True is the embed is a post from Facebook. Ensure that you access this property with quotes; for example: `if (embed.type["facebook-post"]) {}`

FillContext

The FillContext object is passed to your ManagedMode.Callbacks.onFill callback function.

Type:

Object

Properties:

Name	Type	Argument	Description
`channel`	ManagedMode.Callbacks.Channel		The channel tells us whether we are running inside a normal web page, an AMP page, a mobile app, etc.
`creatives`	Array.<ManagedMode.Callbacks.Creative>		Array of creatives. Only a Multi-Creative layout will be able to render more than one.
`exitOnDefaultRule`	boolean	<optional>	True if the default placement will not be rendered when no conditions match.
`placement`	ManagedMode.Callbacks.Placement		The placement whose layout will be rendered.

InjectionStrategy

This is the object returned from the ManagedMode.Callbacks.customInjection callback.

Its properties are used to modify the template's injection location.

Type:

Object

Properties:

Name	Type	Argument	Description
`injectionTarget`	Object	<optional>	This should be a DOM element. If not specified, this will default to "Window.frameElement".
`injectionBehavior`	"append" \| "prepend" \| "before" \| "after"	<optional>	This controls how the template is injected, relative to the "injectionTarget". If not specified, this will default to "before", but can be any of the values listed below: `"append"` The template will be placed inside of the DOM element identified by "injectionTarget", but after any existing content within "injectionTarget". `"prepend"` The template will be placed inside of the DOM element identified by "injectionTarget", but before any existing content within "injectionTarget". `"before"` The template will be placed outside of and in front of the DOM element identified by "injectionTarget". `"after"` The template will be placed outside of and after the DOM element identified by "injectionTarget".

LayoutRenderOptions

Options that affect how a layout is rendered.

Type:

Object

Properties:

Name	Type	Argument	Description
`adjustHeight`	string	<optional>	`"automatic"` if the layout uses the "Automatically adjust iframe height" option.
`adjustWidth`	string	<optional>	`"automatic"` if the layout uses the "Automatically adjust iframe width" option.
`bustIframe`	boolean	<optional>	True if the layout uses the "Render outside of the iframe" option.

Logo

A Logo object.

This represents a sponsor's logo image.

Type:

Object

Properties:

Name	Type	Argument	Description
`caption`	string	<optional>	The logo's caption.
`credits`	string	<optional>	The logo's credits.
`sourceHeight`	number		The height, in pixels, of the original source image file.
`sourceWidth`	number		The width, in pixels, of the original source image file.

onError(errorContext)

The Error function is called when a creative fails to render.

Failures can occur due to a promo feed being empty, or JavaScript errors during rendering.

This will NOT be called in other more common situations such as the creative failing to load.

Parameters:

Name Type Description

errorContext

Object

Properties

Name	Type	Argument	Description
`$`	JQueryStatic		A jQuery API object. This is the global jQuery object, not an instance. Note: your callback function may be running in an iframe document, which may not be the same document where your layout is rendered. Therefore, you may need to specify the document when making a query, for example: `errorContext.$(".myElement", window.top.document);`
`err`	string	<optional>	An error code, if available. `"NO_CREATIVES_IN_PROMOFEED"` A promo feed had no creatives, so rendering cannot continue.

Example

(function(errorContext) {
  errorContext.$(".placeholder").remove();
})

onFill(fillContext, creative, jQuery)

The Fill function is called after the creative data has loaded, but before the layout is rendered.

Parameters:

Name	Type	Description
`fillContext`	ManagedMode.Callbacks.FillContext	An object that tells you which creatives were loaded, which layout will be used to render them, and other useful information.
`creative`	ManagedMode.Callbacks.Creative	This creative object will be used for rendering. If you make changes to this object, then those changes will persist.
`jQuery`	JQueryStatic	A jQuery API object. This is the global jQuery object, not an instance. Note: your callback function may be running in an iframe document, which may not be the same document where your layout is rendered. Therefore, you may need to specify the document when making a query, for example: `jQuery(".myElement", window.top.document);`

Example

(function(fillContext, creative, jQuery) {
    // Change the title that will be rendered
    // on an AMP page.
    try {
        if (fillContext.channel.name === "amp") {
            creative.title = "New Title";
        }
    } catch (error) {}
})

onRender(renderContext)

The Render function is called after the creative has been rendered.

At this point, your layout's template has been filled, parsed as HTML, and inserted into the document.

Parameters:

Name	Type	Description
`renderContext`	ManagedMode.Callbacks.RenderContext	The rendered layout and related information.

Example

(function(renderContext) {
    renderContext.$template.find(".myClass").hide();
})

Organization

An Organization object.

An Organization owns one or more teams; each team owns one or more campaigns.

Type:

Object

Properties:

Name	Type	Description
`id`	string	Unique identifier for the organization.
`name`	string	Organization name.

Placement

A Placement object represents a layout and how it was chosen.

Type:

Object

Properties:

Name	Type	Description
`id`	string	Unique identifier of the placement.
`layoutType`	"single_creative" \| "collection"	The layout type.
`name`	string	The layout name.
`render`	ManagedMode.Callbacks.LayoutRenderOptions	Options that affect how the layout is rendered.
`rule`	ManagedMode.Callbacks.Rule	The rule whose conditions were matched. This rule's layout will be used for rendering.

RenderContext

A RenderContext object contains a rendered layout and related information.

This is the argument to the ManagedMode.Callbacks.onRender callback.

Type:

Object

Properties:

Name Type Description

$

JQueryStatic

A jQuery API object. This is the global jQuery object, not an instance.

Note: your callback function may be running in an iframe document, which may not be the same document where your layout is rendered. Therefore, you may need to specify the document when making a query, for example:

renderContext.$(".myElement", window.top.document);

$template

jQuery

A jQuery object that represents the rendered template.

If your layout renders outside of the iframe, then the DOM elements may belong to a different document than window.document.

analytics

Object

An object with methods for manual analytics event tracking.

Properties

Name	Type	Description
`trackPrimaryClick`	function	Call this function to emit a click event. This should only be used in special cases. For example, your layout might have a "tap to expand" button that you wish to count as a click, when it would not happen automatically.
`attachInteractionWatcher`	function	Creates a function that watches an element for user interaction. This is for tracking clicks or taps of embedded content. When you call attachInteractionWatcher, it will attach a "watcher" function to the given object. After your embedded content has loaded, you can call the watcher function to start tracking user interactions. You should only call the watcher function one time.

fill

ManagedMode.Callbacks.FillContext

Information about how the creative was loaded.

This is the same object passed to the ManagedMode.Callbacks.onFill callback.

placementData

ManagedMode.Callbacks.Placement

Information about the placement whose layout was used to render the template.

rendering

Object

An object with helper functions for rendering

Properties

Name	Type	Description
`resizeFrameToFitContent`	function	Call this function to resize the frame containing the creative to the proper size for the creative.

Rule

A Rule object determines which layout to render based on a set of conditions.

Type:

Object

Properties:

Name	Type	Argument	Description
`conditions`	ManagedMode.Callbacks.Conditions		The conditions that will be matched for this rule to take effect.
`id`	string		The unique identifier of this rule.
`isDefault`	boolean	<optional>	True if this rule is used by default when no other rules have matching conditions.
`name`	string		The rule name.
`placement`	string		The unique identifier of the placement whose layout will be rendered when this rule has matching conditions.

Sponsor

A Sponsor object.

Type:

Object

Properties:

Name	Type	Argument	Description
`link`	string	<optional>	A URL for the sponsor.
`logo`	ManagedMode.Callbacks.Logo	<optional>	The sponsor's logo.
`name`	string		The sponsor's name.

Team

A Team object. Each Team belongs to an Organization.

Type:

Object

Properties:

Name	Type	Description
`id`	string	Unique identifier for the team.
`name`	string	Team name.
`organization`	ManagedMode.Callbacks.Organization	The organization that owns this team.

TemplateContext

A TemplateContext object contains the jQuery-wrapped template as well as a jQuery API object.

This is the argument to the ManagedMode.Callbacks.customInjection callback.

Type:

Object

Properties:

Name	Type	Description
`$`	JQueryStatic	A jQuery API object. This is the global jQuery object, not an instance. Note: your callback function may be running in an iframe document, which may not be the same document where your layout is rendered. Therefore, you may need to specify the document when making a query, for example: `templateContext.$(".myElement", window.top.document);`
`$template`	jQuery	A jQuery object that represents the jQuery-wrapped template. If your layout renders outside of the iframe, then the DOM elements may belong to a different document than `window.document`.

Thumbnail

A Thumbnail object represents the main thumbnail image for a creative.

Type:

Object

Properties:

Name	Type	Argument	Description
`caption`	string	<optional>	The image caption.
`credits`	string	<optional>	The image credits.
`instances`	Array.<ManagedMode.Callbacks.ThumbnailInstance>	<optional>	Array of instances. Each instance is intended to represent the same image, but cropped to different aspect ratios. Your layout's Handlebars template will choose which instance to use.

ThumbnailInstance

A ThumbnailInstance object represents one aspect ratio of a thumbnail image.

Thumbnail images can have multiple "instances" that represent the same image cropped to different aspect ratios.

Type:

Object

Properties:

Name	Type	Description
`sourceHeight`	number	The height, in pixels, of the original image file.
`sourceWidth`	number	The width, in pixels, of the original image file.

Vertical

A Vertical object.

Type:

Object

Properties:

Name	Type	Description
`vertical.code`	string	The vertical code (MSCI/S&P GICS Industry Group).
`vertical.name`	string	The vertical name.

Example

{
  "code": "1010",
  "name": "Energy",
}