Class: ImaSdkSettings

google.ima.ImaSdkSettings

class   public   static

This class contains SDK-wide settings.

Enumerations

CompanionBackfillMode

constant   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 main ad returned.

If the value is ON_MASTER_AD, companion backfill will be attempted if there is a main 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:

...
let 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

constant   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 through JavaScript.

Properties

CompanionBackfillMode

constant   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 main ad returned.

If the value is ON_MASTER_AD, companion backfill will be attempted if there is a main 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:

...
let 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

constant   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 through JavaScript.

Methods

getCompanionBackfill

getCompanionBackfill() returns CompanionBackfillMode

Returns the current companion backfill mode.

Returns

non-null 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 

getFeatureFlags

getFeatureFlags() returns Object with any type properties

Returns an object with keys as feature flags and values as their current state.

Returns

non-null Object with any type properties 

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 (null or string)

Returns the publisher provided id.

Returns

(null or string) publisher provided id.

isCookiesEnabled

isCookiesEnabled() returns boolean

Returns

boolean Whether the publisher allows cookies to be used.

setAutoPlayAdBreaks

setAutoPlayAdBreaks(autoPlayAdBreaks) returns void

Sets whether VMAP and ad rules ad breaks are automatically played

Parameter
autoPlayAdBreaks	boolean Whether to autoPlay the ad breaks.

Returns

void 

setCompanionBackfill

setCompanionBackfill(mode) returns void

Sets the companion backfill mode. See the various modes available in ImaSdkSettings.CompanionBackfillMode.

The default mode is ImaSdkSettings.CompanionBackfillMode.ALWAYS.

Parameter
mode	CompanionBackfillMode The chosen companion backfill mode. Value must not be null.

Returns

void 

setCookiesEnabled

setCookiesEnabled(cookiesEnabled) returns void

Whether the SDK should store a Google Ad Manager cookie (GFP Cookie) on the publisher's domain, as a first-party cookie. This enables persistence across multiple visits to the same domain without using third-party cookies. Defaults to true.

This setting will not affect other cookies which may be set by other parties or for other purposes. User consent and opt-outs may also disable usage of first-party cookies. These will be picked up by publisher's usage of an IAB compliant Consent Management Provider, if in the same frame.

Parameter
cookiesEnabled	boolean

Returns

void 

setDisableCustomPlaybackForIOS10Plus

setDisableCustomPlaybackForIOS10Plus(disable) returns void

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.

Returns

void 

setFeatureFlags

setFeatureFlags(featureFlags) returns void

Set the value for any feature flags. This should be set as early as possible, before requesting ads. Settings will remain constant until the next ad request. Calling this method again will reset any feature flags for the next ad request.

Parameter
featureFlags	Object with any type properties Value must not be null.

Returns

void 

setLocale

setLocale(locale) returns void

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.

Returns

void 

setNumRedirects

setNumRedirects(numRedirects) returns void

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.

Returns

void 

setPlayerType

setPlayerType(playerType) returns void

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:

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

Parameter
playerType	string The type of the partner player.

Returns

void 

setPlayerVersion

setPlayerVersion(playerVersion) returns void

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:

settings.setPlayerVersion('1.0.0');

Parameter
playerVersion	string The version of the partner player.

Returns

void 

setPpid

setPpid(ppid) returns void

Sets the publisher provided id.

Parameter
ppid	string publisher provided id.

Returns

void 

setSessionId

setSessionId(sessionId) returns void

Session ID is a temporary random ID. It is used exclusively for frequency capping. A session ID must be a UUID.

Parameter
sessionId	string A temporary UUID used for frequency capping.

Returns

void 

setVpaidAllowed

setVpaidAllowed(allowVpaid) returns void

Deprecated. Use setVpaidMode. Sets whether VPAID creatives are allowed.

Parameter
allowVpaid	boolean Whether to allow VPAID creatives.

Returns

void 

setVpaidMode

setVpaidMode(vpaidMode) returns void

Sets VPAID playback mode.

Parameter
vpaidMode	VpaidMode Sets how VPAID ads will be played. Default is secure mode. Value must not be null.

Returns

void