Skip to main content
Version: 4.12.7

SpotX

SpotX is a global video ad serving platform providing digital media owners with a solution that allows them to monetize their content with video advertising across desktop, mobile and connected devices.

SDKs

Web SDKAndroid SDKiOS SDKtvOS SDKAndroid TV SDKChromecast SDK
YesYesYesUnverifiedTBDTBD

Prerequisites

Your THEOplayer SDK must have the SpotX module enabled. You can enable this module when building your THEOplayer SDK through the THEOplayer Development Portal.

Integrating SpotX

Web SDK

Add the SpotX ad integration when configuring the player

player.source = {
sources: ...,
ads: [{
integration: 'spotx',
...
}]
}

the {{SpotXAdDescription}} object provides the following properties:

MethodTypeOptionalDescription
integrationstringyesUse the value 'spotx' to use the SpotX ad integration. The SpotX integration uses Google IMA. To use Google IMA, it is required to load the SDK first. You can find the getting started of Google IMA sdk at: https://developers.google.com/interactive-media-ads/docs/sdks/html5/quickstart
idnumber or stringnoYour SpotX id
cacheBusterbooleanyesAdd the cb parameter with a random number to the SpotX tag.
maximumAdDurationnumber or stringyes
customSpotXDatayesSpotX custom data
appSpotXDatayesSpotX app data
deviceSpotXDatayesSpotX device data
userSpotXDatayesSpotX user data
sourcesstringyesSpotX ad tag (to directly set the SpotX source link)

Example:

player.source = {
sources: ...,
ads: [{
integration: 'spotx',
id: 123456,
cacheBuster: true,
app: {
bundle: 'com.exampleapps.example',
name: 'My CTV App'
},
device: {
ifa: '38400000-8cf0-11bd-b23e-10b96e40000d',
ua: 'Mozilla/5.0 (iPhone; CPU iPhone OS 10_3 like Mac OS X) AppleWebKit/602.1.50 (KHTML, like Gecko) CriOS/56.0.2924.75 Mobile/14E5239e Safari/602.1',
geo: {
lat: -24.378528,
lon: -128.325119
},
dnt: 1,
lmt: 1,
},
custom: {
category: ['category1', 'category2'],
somekey: 'somevalue'
},
user: {
yob: 1984,
gender: 'm'
}
}
]};

iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

Add a SpotXAdDescription to the player before initializing:

let spotxAdDescription = SpotXAdDescription(id)
var source = SourceDescription(..., ads: [spotxAdDescription])

A SpotXAdDescription has the following properties:

MethodTypeOptionalDescription
idnumber or stringnoYour SpotX id
cacheBusterbooleanyesAdd the cb parameter with a random number to the SpotX tag.
maximumAdDurationnumber or stringyesAdd the VMaxd parameter with a duration to the SpotX tag
ipAddressstringyesAdd an IP Address to the SpotX configuration
customSpotXDatayesSpotX custom data
appSpotXDatayesSpotX app data
deviceSpotXDatayesSpotX device data
userSpotXDatayesSpotX user data
sourcesstringyesSpotX ad tag (to directly set the SpotX source link)
queryParameters[String: SpotXQueryParameter]yesAdd custom query parameters to the SpotX tag

Code Sample:

var player = THEOplayer()
var spotx: SpotXAdDescription {
let app = SpotXData(stringParameters: ["bundle": "com.exampleapps.example", "name": "My CTV App"])
let device = SpotXData(stringParameters: ["ifa": "38400000-8cf0-11bd-b23e-10b96e40000d"], intParameters: ["dnt": 1, "lmt": 1], geoParameter: Geo(lat: -24.378528, lon: -128.325119))
let user = SpotXData(stringParameters: ["gender": "m"], intParameters: ["yob": 1984])
let custom = SpotXData(stringParameters: ["my-custom-label": "my-custom-value"])
return SpotXAdDescription(id: "85394", cacheBuster: true, app: app, device: device, user: user, custom: custom)
}

var source = SourceDescription {
let typedSource = TypedSource(src: sourceUrl, type: streamType)
return SourceDescription(source: typedSource, ads: [spotx])
}

player.source = source

Legacy Android SDK (4.12.x)

Add a SpotXAdDescription to the player before initializing:

THEOplayerConfig = new THEOplayerConfig.Builder()
.ui(uiConfig)
.build();
THEOplayerView tpv = new THEOplayerView(this, playerConfig);

OR

tpv = findViewById(R.id.theoplayer_view);

A SpotXAdDescription.Builder has the following properties:

MethodTypeOptionalDescription
spotxAdDescriptionnumber or stringnoYour SpotX id
cacheBusterbooleanyesAdd the cb parameter with a random number to the SpotX tag.
maximumAdDurationnumber or stringyesAdd the VMaxd parameter with a duration to the SpotX tag
ipAddressstringyesAdd an IP Address to the SpotX configuration
queryParameters[String: SpotXQueryParameter]yesAdd custom query parameters to the SpotX tag. Used to list data like: custom data, device, user, app

Code Sample:

SourceDescription source = sourceDescription("http://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8")
.ads(spotxAdDescription("85394")
.cacheBuster(false)
.maximumAdDuration(5)
.queryParameters(
spotxDataQueryParameters()
//.param("key1", "value1")
.param("device", spotxData().param("ua", "TEST").param("ifa", "IFA").build())
.param("myCustomObject", spotxData().param("myCustomString", "abcd").build())
.param("app", spotxData().param("appName", "TestApp").param("appVersion", "1.0").build())
.param("nested",
spotxDataQueryParameters()
.param("nestedObjectKey", "nestedObjectValue")
.param("nestedInNested", spotxDataQueryParameters().param("nestedInNestedObjectKey", "nestedInNestedObjectValue").build())
.build())
.build())
.build())
.build();
tpv.getPlayer().setSource(source);