Interface ImaSdkSettings

Note: This reference page follows TypeScript documentation structure. If you have suggestions for or see issues with the reference documentation, open a thread with your feedback on the IMA technical forum.

---

This class contains SDK-wide settings.

Methods
getCompanionBackfill	Returns the current companion backfill mode.
getDisableCustomPlaybackForIOS10Plus	Returns whether to disable custom playback on iOS 10+ browsers.
getFeatureFlags	Returns an object with keys as feature flags and values as their current state.
getLocale	Returns the publisher provided locale.
getNumRedirects	Returns the maximum number of redirects for subsequent redirects will be denied.
getPlayerType	Returns the partner provided player type.
getPlayerVersion	Returns the partner provided player version.
getPpid	Returns the publisher provided id.
isCookiesEnabled	Returns whether the publisher allows cookies to be used.
setAutoPlayAdBreaks	Sets whether VMAP and ad rules ad breaks are automatically played.
setCompanionBackfill	Sets the companion backfill mode.
setCookiesEnabled	Deprecated. Sets whether the SDK should store a Google Ad Manager cookie (GFP Cookie) on the publisher's domain, as a first-party cookie.
setDisableCustomPlaybackForIOS10Plus	Sets whether to disable custom playback on iOS 10+ browsers.
setFeatureFlags	Set the value for any feature flags.
setLocale	Sets the publisher provided locale.
setNumRedirects	Specifies the maximum number of redirects before the subsequent redirects will be denied, and the ad load aborted.
setPlayerType	Sets the partner provided player type.
setPlayerVersion	Sets the partner provided player version.
setPpid	Sets the publisher provided id.
setSessionId	Session ID is a temporary random ID.
setVpaidAllowed	Deprecated. Sets whether VPAID creatives are allowed.
setVpaidMode	Sets VPAID playback mode.

Methods

---

getCompanionBackfill

getCompanionBackfill(): CompanionBackfillMode

Returns the current companion backfill mode.

Returns
CompanionBackfillMode	The current value.

---

getDisableCustomPlaybackForIOS10Plus

getDisableCustomPlaybackForIOS10Plus(): boolean

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

Returns
boolean	Whether to disable custom playback.

---

getFeatureFlags

getFeatureFlags(): Record<string, unknown>

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

Returns
Record<string, unknown>	The feature flags.

---

getLocale

getLocale(): string

Returns the publisher provided locale.

Returns
string	Publisher provided locale.

---

getNumRedirects

getNumRedirects(): number

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

Returns
number	the maximum number of redirects.

---

getPlayerType

getPlayerType(): string

Returns the partner provided player type.

Returns
string	Partner player type.

---

getPlayerVersion

getPlayerVersion(): string

Returns the partner provided player version.

Returns
string	Partner player version.

---

getPpid

getPpid(): string

Returns the publisher provided id.

Returns
string	The publisher provided id.

---

isCookiesEnabled

isCookiesEnabled(): boolean

Returns whether the publisher allows cookies to be used.

Returns
boolean	Whether the publisher allows cookies to be used.

---

setAutoPlayAdBreaks

setAutoPlayAdBreaks(autoPlayAdBreaks: boolean): void

Sets whether VMAP and ad rules ad breaks are automatically played

Parameters
autoPlayAdBreaks: boolean	Whether to autoPlay the ad breaks.

---

setCompanionBackfill

setCompanionBackfill(mode: CompanionBackfillMode): void

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

The default mode is ImaSdkSettings.CompanionBackfillMode.ALWAYS.

Parameters
mode: CompanionBackfillMode	The chosen companion backfill mode.

---

setCookiesEnabled

setCookiesEnabled(cookiesEnabled: boolean): void

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

Deprecated: For options to control storage and identifier usage, see the Limited Ads guide.

Parameters
cookiesEnabled: boolean	Whether to enable the first party cookie.

---

setDisableCustomPlaybackForIOS10Plus

setDisableCustomPlaybackForIOS10Plus(disable: boolean): 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.

Parameters
disable: boolean	Whether or not to disable custom playback.

---

setFeatureFlags

setFeatureFlags(featureFlags: Record<string, unknown>): 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.

Parameters
featureFlags: Record<string, unknown>	The feature flags object.

---

setLocale

setLocale(locale: string): 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.

Parameters
locale: string	Publisher-provided locale.

---

setNumRedirects

setNumRedirects(numRedirects: number): 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.

Parameters
numRedirects: number	The maximum number of redirects.

---

setPlayerType

setPlayerType(playerType: string): 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'); 

Parameters
playerType: string	The type of the partner player.

---

setPlayerVersion

setPlayerVersion(playerVersion: string): 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'); 

Parameters
playerVersion: string	The version of the partner player.

---

setPpid

setPpid(ppid: string): void

Sets the publisher provided id.

Parameters
ppid: string	publisher provided id.

---

setSessionId

setSessionId(sessionId: string): void

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

Parameters
sessionId: string	A temporary UUID used for frequency capping.

---

setVpaidAllowed

setVpaidAllowed(allowVpaid: boolean): void

Sets whether VPAID creatives are allowed.

Deprecated: Use setVpaidMode.

Parameters
allowVpaid: boolean	Whether to allow VPAID creatives.

---

setVpaidMode

setVpaidMode(vpaidMode: VpaidMode): void

Sets VPAID playback mode.

Parameters
vpaidMode: VpaidMode	Sets how VPAID ads will be played. Default is secure mode.