Namespace: API

Namespaces

event

logging

Members

<readonly> $

The jQuery object that the plugin uses internally.

Methods

<static> disableIAS()

Disables IAS tracking. Differs from the above in that this applies the confDisabled property to the IAS config, allowing logs from iastracker.js to appear. See NA-8831 for more context.

<static> disableMOAT()

Disables MOAT tracking. Differs from the above in that this applies the confDisabled property to the MOAT config, allowing logs from moattracker.js to appear. See NA-8831 for more context.

configurePrivacy(conf) → {boolean}

Configure user privacy measures.

Parameters:

Name	Type	Description
conf	object	Properties Name Type Argument Description privacyMode string <optional> The privacy mode preset to use. Options are: `gdpr` : GDPR compliant. `gdpr-eu` : When in EU & similar, `gdpr`; `managed` otherwise. `managed` : User consent is externally managed (by site/app operator). `no-track` : No user tracking will be performed. The gdpr-eu setting is default. When either gdpr or gdpr-eu is used, consent signals must be exchanged via IAB CMP JS or manually (via toggleUserConsent). When in gdpr mode (or gdpr-eu while in a EU country), consent must be granted before user tracking can be performed. When in managed mode (or gdpr-eu while in a non-EU country), user tracking will be performed unless consent is explicitly denied. When in no-track mode, user tracking will never be performed.

Returns:

Indicates if configuration was applied successfully.

Type

boolean

configureSecondaryPage(conf)

Tell the plugin to track and/or render the page.

Parameters:

Name	Type	Description
conf	object	Properties Name Type Argument Description dateFormat API.dateFormatterCallback <optional> A callback that accepts a [Date][1] object and returns a formatted string. This lets you control how dates are rendered. [1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date binding object <optional> A map of CSS selectors that determine where on the page to render each piece of content. Known keys: title, summary, content, author, pubDate, sponsor.name, sponsor.link, sponsor.logo, image.href, image.caption, image.credits onFill API.secondaryPageOnFill <optional> A callback that runs before the page is rendered to the DOM. onRender API.secondaryPageOnRender <optional> A callback that runs after the page is rendered to the DOM. onError API.secondaryPageOnError <optional> A callback that runs if the page cannot be rendered. track function <optional> A callback that runs when the plugin cannot determine whether the page should be tracked or not. This happens on inbound page views that were not directly triggered by an ad clickthrough. To track these inbound pages, return the string "inbound" from this callback. Ideally, your page’s HTML will contain a Canonical Link Element that will be used for tracking.

disablePolarTracker()

This function is a no-op.

Deprecated:

• Yes

enableIAS(primaryEnabled, callback)

Eanble or disable IAS tracking.

Parameters:

Name	Type	Argument	Default	Description
primaryEnabled	boolean	<optional>	true	true to enable IAS tracking on primary views, false to disable it.
callback	function	<optional>		A callback function that returns an object. The object's key-values must comprise all the parameters required in order to inject the IAS tracking tag.

enableMOAT(enabled, primaryEnabled, contentDiv)

Enable or disable MOAT tracking.

Parameters:

Name	Type	Argument	Default	Description
enabled	boolean	<optional>	true	true to enable MOAT, false to disable it.
primaryEnabled	boolean	<optional>	false	true to enable MOAT tracking on primary views, false to disable it. Added in v0.5.46. Previous plugin versions always behave as if this argument is true.
contentDiv	string	<optional>	"document.body"	Specifies the ID selector of the content div to be used by MOAT for tracking. Added in v0.5.46. Previous plugin versions do not send any selector to MOAT, with the assumption that the entire page should be tracked.

enableSPAMode(pageOnHashChange)

Enable Single-page application (SPA) mode.

Parameters:

Name	Type	Description
pageOnHashChange	boolean	An onhashchange event indicates that a new page has been rendered.

injectCSS(styles, target)

Inject CSS styles into the document.

Parameters:

Name	Type	Argument	Default	Description
styles	string			CSS styles.
target	string	<optional>	head	Selector, whose matching elements will have a style element appended.

insertPreview(options)

Request an ad and automatically place it in the page when it succeeds.

Parameters:

Name	Type	Description
options	object	Properties Name Type Argument Description label string <optional> Label that will be reported in analytics events. unit object Ad unit to request. Note that if the plugin is operating in "preview mode" and the "mvpi" parameter is supplied in the query string, then this unit is ignored by the plugin; instead the plugin always renders the preview with the creative referenced in the "mvpi" parameter. location string CSS selector where the ad should be inserted. It must match exactly one element. infoText string Text that is shown when the info button is clicked. infoButtonText string Text for the info button label. template object | function When an object is provided then the most appropriate template will be picked based on the ad tag. Source ad tags will translate to creative templates, At least one of the following values must be assigned. Possible object values are: creative, collection, or fn Both creative and collection must be assigned a handlebars template. fn must be passed a function that takes the adtag and model and returns a template function. When a function is provided then the function is assumed to be a creative template. The picked template will be run upon success, and inserted into the DOM where the location selector has a match. onRender API.onRenderCallback Callback that runs after the template is executed and inserted into the DOM. onFill function Callback that runs after a native ad is fetched successfully. onError API.onErrorCallback Callback that runs upon failure. dateFormat API.dateFormatterCallback Date formatter that will transform the pubDate. If this parameter is not defined, then the template will render raw [ISO 8601][1] dates. [1]: http://en.wikipedia.org/wiki/ISO_8601 sponsorLinkFormat API.sponsorLinkFormatterCallback Sponsor Link formatter that will transform the sponsor link and name. If it is not defined, then the template will use the default formatting. previews array The list of ad previews in the collection to use if a collection ad tag is being used. collectionSize Integer The number of creatives that the collection template can render.

insertPreviewCollection(options)

Request a collection of ads and automatically place each in the page when request succeeds.

A collection is a group of ads served from one ad request. To use a collection, you must first create the collection in MediaVoice, then traffic the collection ad tag as a normal 3rd-party unit through your ad server. Then, create a custom collection template that includes templates or logic to render each individual ad spot, which is used in the options argument.

Parameters:

Name	Type	Description
options	object	The collection configuration. Properties Name Type Description label string A unique name for your collection. unit object The ad unit used to request the collection. location string The DOM node where the collection will be inserted. infoText string The text that is displayed when the info button is clicked. infoButtonText string The text displayed on the info button. template object | function When an object is provided then the most appropriate template will be picked based on the ad tag. Source ad tags will translate to creative templates, At least one of the following values must be assigned. Possible object values are: creative, collection, or fn Both creative and collection must be assigned a handlebars template. fn must be passed a function that takes the adtag and model and returns a template function. When a function is provided then the function is assumed to be a collection template. The picked template will be run upon success, and inserted into the DOM where the location selector has a match. onRender API.onRenderCallback Callback that runs after the template is executed and inserted into the DOM. onFill function A callback that is triggered after the ad request returns. onError function A callback that is triggered if a error occurs. dateFormat API.dateFormatterCallback Date formatter that will transform the pubDate. If this parameter is not defined, then the template will render raw [ISO 8601][1] dates. [1]: http://en.wikipedia.org/wiki/ISO_8601 sponsorLinkFormat API.sponsorLinkFormatterCallback Sponsor Link formatter that will transform the sponsor link and name. If it is not defined, then the template will use the default formatting. previews array The list of ad previews in the collection to use if a collection ad tag is being used. collectionSize Integer The number of creatives that the collection template can render.

log()

This function records strings, objects, etc. to the JavaScript console.

requestAd(options) → {object|null}

Request an ad on demand. The DOM’s body element may have a pixel tracker image appended after a successful ad request.

Parameters:

Name	Type	Description
options	object	Ad request options Properties Name Type Argument Description unit object Ad unit. Will be passed to the ad driver. Properties Name Type Description server string Ad server, e.g. "dfp" or "mocean". label string Label. Used for the impression analytics event that is automatically tracked when the ad is successfully loaded. previewCount integer <optional> Used for collections to tell the API how many creatives to fetch. onFill API.requestAdOnFill Success callback. onError API.requestAdOnError Error callback. htmlElement function <optional> A function that returns the HTML element or jQuery object that contains the ad preview. The function will be called after the onFill success callback. You must provide this function if MOAT is enabled. Otherwise, MOAT will be unable to track the viewability of the ad preview. The element must be rendered and in the DOM.

Returns:

If the request is started successfully, then an object with a cancel function that you can call to abort the ad request. Otherwise, null.

Type

object | null

requestCreative(options) → {null}

Request a creative on demand, given the creative’s instance ID. This is intended to be used when deep linking (i.e., when a page view is not driven directly by an ad-served impression). In this deep link use case, analytics must be manually reported via the track function, with options.kind holding a value of event.kind.DEEP_LINK, and values of null for both options.unit and options.adtag.

Parameters:

Name	Type	Description
options	object	Request options. Properties Name Type Argument Description id string Creative id. previewCount string <optional> The number of creatives to request from the API. Used for collections. onFill API.requestCreativeOnFill Success callback. onError API.requestCreativeOnError Error callback.

Returns:

Type

null

resetAdServer()

Calls reset on all registered ad servers. For single-page applications the ad server may need to be reset between ad requests to ensure a new ad unit is delivered. If using DFP + GPT, this function should be called immediately after googletag.pubads().refresh(), in order to synchronize the correlator value used by GPT with the value used to request native ad units.

setPropertyID(id)

Set the Property ID for your page or application.

This function must be called exactly once, before any other plugin functions are called.

Parameters:

Name	Type	Description
id	string	Property ID supplied by your MediaVoice account manager.

setSecondaryPageURL(url)

Set the URL path for the secondary page. This is required for the plugin to render the secondary page and generate links to it.

Parameters:

Name	Type	Description
url	string	URL path to the secondary page. For example, "sponsored.html".

setWillLinkRedirect(Callback)

Set a callback function that tells the plugin whether a given link will be redirected to a different URL when clicked.

When your callback returns false, and the link’s destination is on the same origin as the current page, then the plugin will avoid storing tracking data in the destination URL. It will use HTML5 Web Storage instead.

This is necessary on web sites that do not work correctly when URLs have our tracking data added to the hash.

Parameters:

Name	Type	Argument	Description
Callback	API.willLinkRedirectCallback	<nullable>	function that will be invoked when links are clicked.

toggleUserConsent(flag) → {boolean|null}

Toggle the user consent flag.

Parameters:

Name	Type	Description
flag	boolean | null	The consent value to set. If null is passed, no change will be made.

Returns:

The current consent flag value. If null, no consent decision has yet been made available.

Type

boolean | null

Type Definitions

dateFormatterCallback(date) → {string}

Date formatter function.

Parameters:

Name	Type	Description
date	Date	The [Date object][1] to format. [1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date

Returns:

Formatted date.

Type

string

onErrorCallback(error, extra)

Callback function, triggered when an internal error has occurred. Can be called from insertPreview or insertPreviewCollection.

Parameters:

Name	Type	Description
error	string | object	A string or object representation of the error that occurred
extra	object	Any extra error information around the error the occurred.

onRenderCallback($html, creative)

Callback function, triggered immediately after a placement is rendered by insertPreview or insertPreviewCollection.

Parameters:

Name	Type	Description
$html	object	The jQuery object that was rendered from the template.
creative	object	The creative that was rendered. This is the same object provided in the onFill callback.

requestAdOnError(error)

Error callback function for the requestAd function.

Parameters:

Name	Type	Description
error	object	The error that occurred while fetching the ad

requestAdOnFill(response)

Success callback function for the requestAd function.

Parameters:

Name	Type	Description
response	object	The ad response Properties Name Type Description model object Model representing e.g. an article adtag object Creative and tracking info.

requestCreativeOnError(error)

Error callback function for the requestCreative function.

Parameters:

Name	Type	Description
error	object	The error that occurred while fetching the creative.

requestCreativeOnFill(response)

Success callback function for the requestCreative function.

Parameters:

Name	Type	Description
response	object	The creative response. Properties Name Type Description model object Model representing e.g. an article.

secondaryPageOnError(error)

Callback function, triggered when the secondary page cannot be rendered.

Parameters:

Name	Type	Description
error	object	The error that occurred while fetching the secondary page content.

secondaryPageOnFill(model)

Callback function, triggered immediately before the secondary page is rendered into the DOM.

Parameters:

Name	Type	Description
model	object	Model representing e.g. an article

secondaryPageOnRender()

Callback function, triggered immediately after the secondary page is rendered into the DOM.

sponsorLinkFormatterCallback(sponsorName, sponsorLink) → {object}

Sponsor link formatter function.

Parameters:

Name	Type	Description
sponsorName	string	The name of the sponsor from the sponsornamelink cta.
sponsorLink	string	The link for the sponsor from the sponsornamelink cta.

Returns:

newSponsorName, newSponsorLink

Type

object

willLinkRedirectCallback(url) → {boolean}

Callback that tells the plugin whether a given link will be redirected when clicked.

Parameters:

Name	Type	Description
url	string	The URL of the link.

Returns:

true if the link will be redirected, otherwise false. Returning false will allow the plugin to store tracking data with HTML5 Web Storage instead of altering the destination URL.

Type

boolean