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 SDK	Android SDK	iOS SDK	tvOS SDK	Android TV SDK	Chromecast SDK
Yes	Yes	Yes	Unverified	TBD	TBD

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:

Method	Type	Optional	Description
integration	string	yes	Use 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
id	number or string	no	Your SpotX id
cacheBuster	boolean	yes	Add the cb parameter with a random number to the SpotX tag.
maximumAdDuration	number or string	yes
custom	SpotXData	yes	SpotX custom data
app	SpotXData	yes	SpotX app data
device	SpotXData	yes	SpotX device data
user	SpotXData	yes	SpotX user data
sources	string	yes	SpotX 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:

Method	Type	Optional	Description
id	number or string	no	Your SpotX id
cacheBuster	boolean	yes	Add the cb parameter with a random number to the SpotX tag.
maximumAdDuration	number or string	yes	Add the VMaxd parameter with a duration to the SpotX tag
ipAddress	string	yes	Add an IP Address to the SpotX configuration
custom	SpotXData	yes	SpotX custom data
app	SpotXData	yes	SpotX app data
device	SpotXData	yes	SpotX device data
user	SpotXData	yes	SpotX user data
sources	string	yes	SpotX ad tag (to directly set the SpotX source link)
queryParameters	[String: SpotXQueryParameter]	yes	Add 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:

Method	Type	Optional	Description
spotxAdDescription	number or string	no	Your SpotX id
cacheBuster	boolean	yes	Add the cb parameter with a random number to the SpotX tag.
maximumAdDuration	number or string	yes	Add the VMaxd parameter with a duration to the SpotX tag
ipAddress	string	yes	Add an IP Address to the SpotX configuration
queryParameters	[String: SpotXQueryParameter]	yes	Add 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);