Class: ImaSdkSettings

Constructor

ImaSdkSettings

new ImaSdkSettings()

This class contains SDK-wide settings.

Enumerations

CompanionBackfillMode

static

string

Defines a set of constants for the companion backfill setting. This setting indicates whether companions should be backfilled in various scenarios.

If the value is ALWAYS, companion backfill will be attempted in all situations, even when there is no master ad returned.

If the value is ON_MASTER_AD, companion backfill will be attempted if there is a master ad with fewer companions than there are companion slots. The missing companions will be backfilled.

The default value is ALWAYS.

Note that client-side companion backfill requires tagging your companions properly with a Google Publisher Tag (GPT). To enable backfill, the following changes to standard GPT setup are necessary:
...
var slot1 = googletag.defineSlot('/1234/adunit', [300, 250], 'slot-div');
slot1.addService(googletag.companionAds()).addService(googletag.pubads());
...
googletag.companionAds().setRefreshUnfilledSlots(true);
...
googletag.enableServices();
For autoplay videos, the following additional change is recommended to prevent companion slots from being preloaded and then immediately replaced with companions.
googletag.pubads().disableInitialLoad();
...
googletag.enableServices();

Value

ALWAYS

ON_MASTER_AD

VpaidMode

static

number

A set of constants for enabling VPAID functionality.

Value

DISABLED

VPAID ads will not play and an error will be returned.

ENABLED

VPAID ads are enabled using a cross domain iframe. The VPAID ad cannot access the site. VPAID ads that depend on friendly iframe access may error. This is the default.

INSECURE

VPAID ads are enabled using a friendly iframe. This allows the ad access to the site via JavaScript.

Properties

CompanionBackfillMode

static

string

Defines a set of constants for the companion backfill setting. This setting indicates whether companions should be backfilled in various scenarios.

If the value is ALWAYS, companion backfill will be attempted in all situations, even when there is no master ad returned.

If the value is ON_MASTER_AD, companion backfill will be attempted if there is a master ad with fewer companions than there are companion slots. The missing companions will be backfilled.

The default value is ALWAYS.

Note that client-side companion backfill requires tagging your companions properly with a Google Publisher Tag (GPT). To enable backfill, the following changes to standard GPT setup are necessary:
...
var slot1 = googletag.defineSlot('/1234/adunit', [300, 250], 'slot-div');
slot1.addService(googletag.companionAds()).addService(googletag.pubads());
...
googletag.companionAds().setRefreshUnfilledSlots(true);
...
googletag.enableServices();
For autoplay videos, the following additional change is recommended to prevent companion slots from being preloaded and then immediately replaced with companions.
googletag.pubads().disableInitialLoad();
...
googletag.enableServices();

Value

ALWAYS

ON_MASTER_AD

VpaidMode

static

number

A set of constants for enabling VPAID functionality.

Value

DISABLED

VPAID ads will not play and an error will be returned.

ENABLED

VPAID ads are enabled using a cross domain iframe. The VPAID ad cannot access the site. VPAID ads that depend on friendly iframe access may error. This is the default.

INSECURE

VPAID ads are enabled using a friendly iframe. This allows the ad access to the site via JavaScript.

Methods

getCompanionBackfill

getCompanionBackfill() returns ima.ImaSdkSettings.CompanionBackfillMode

Returns the current companion backfill mode.

Returns

non-null ima.ImaSdkSettings.CompanionBackfillMode The current value.

getDisableCustomPlaybackForIOS10Plus

getDisableCustomPlaybackForIOS10Plus() returns boolean

Gets whether to disable custom playback on iOS 10+ browsers. The default value is false.

Returns

boolean 

getLocale

getLocale() returns string

Returns the publisher provided locale.

Returns

string Publisher provided locale.

getNumRedirects

getNumRedirects() returns number

Returns the maximum number of redirects for subsequent redirects will be denied.

Returns

number the maximum number of redirects.

getPlayerType

getPlayerType() returns string

Returns the partner provided player type.

Returns

string Partner player type.

getPlayerVersion

getPlayerVersion() returns string

Returns the partner provided player version.

Returns

string Partner player version.

getPpid

getPpid() returns string

Returns the publisher provided id.

Returns

string publisher provided id.

isCookiesEnabled

isCookiesEnabled() returns boolean

Returns

boolean Whether cookies are enabled.

setAutoPlayAdBreaks

setAutoPlayAdBreaks(autoPlayAdBreaks)

Sets whether VMAP and ad rules ad breaks are automatically played

Parameter

autoPlayAdBreaks

boolean

Whether to autoPlay the ad breaks.

setCompanionBackfill

setCompanionBackfill(mode)

Sets the companion backfill mode. Please see the various modes available in ima.ImaSdkSettings.CompanionBackfillMode.

The default mode is ima.ImaSdkSettings.CompanionBackfillMode.ALWAYS.

Parameter

mode

ima.ImaSdkSettings.CompanionBackfillMode

The desired companion backfill mode.

Value must not be null.

setCookiesEnabled

setCookiesEnabled(cookiesEnabled)

Parameter

cookiesEnabled

boolean

Sets whether Google Ad Manager cookies are enabled. If true, enables Ad Manager cookies on ad requests, otherwise ignores Ad Manager cookies on subsequent ad requests and prevents cookie creation. True by default. Note that disabling cookies will also disable features that rely on cookies. See https://support.google.com/admanager/answer/3202794 for further details.

setDisableCustomPlaybackForIOS10Plus

setDisableCustomPlaybackForIOS10Plus(disable)

Sets whether to disable custom playback on iOS 10+ browsers. If true, ads will play inline if the content video is inline. This enables TrueView skippable ads. However, the ad will stay inline and not support iOS's native fullscreen. When false, ads will play in the same player as your content. The value set here when an AdDisplayContainer is created is used for the lifetime of the container. The default value is false.

Parameter

disable

boolean

Whether or not to disable custom playback.

setLocale

setLocale(locale)

Sets the publisher provided locale. Must be called before creating AdsLoader or AdDisplayContainer. The locale specifies the language in which to display UI elements. The supported codes can be found in Localizing for Language and Locale.

Parameter

locale

string

Publisher-provided locale.

setNumRedirects

setNumRedirects(numRedirects)

Specifies the maximum number of redirects before the subsequent redirects will be denied, and the ad load aborted. The number of redirects directly affects latency and thus user experience. This applies to all VAST wrapper ads.

Parameter

numRedirects

number

the maximum number of redirects.

setPlayerType

setPlayerType(playerType)

Sets the partner provided player type. This setting should be used to specify the name of the player being integrated with the SDK. Player type greater than 20 characters will be truncated. The player type specified should be short and unique. This is an optional setting used to improve SDK usability by tracking player types.

Example:


ima.settings.setPlayerType('google/gmf-player');

Parameter

playerType

string

The type of the partner player.

setPlayerVersion

setPlayerVersion(playerVersion)

Sets the partner provided player version. This setting should be used to specify the version of the partner player being integrated with the SDK. Player versions greater than 20 characters will be truncated. This is an optional setting used to improve SDK usability by tracking player version.

Example:


ima.settings.setPlayerVersion('1.0.0');

Parameter

playerVersion

string

The version of the partner player.

setPpid

setPpid(ppid)

Sets the publisher provided id.

Parameter

ppid

string

publisher provided id.

setVpaidAllowed

setVpaidAllowed(allowVpaid)

Deprecated. Please use setVpaidMode. Sets whether VPAID creatives are allowed.

Parameter

allowVpaid

boolean

Whether to allow VPAID creatives.

setVpaidMode

setVpaidMode(vpaidMode)

Sets VPAID playback mode.

Parameter

vpaidMode

ima.ImaSdkSettings.VpaidMode

Sets how VPAID ads will be played. Default is secure mode.

Value must not be null.