Advertising Module 1.0.0

Usage

To use the Advertising module, you can import it into your project from the Firebolt SDK:

import { Advertising } from '@firebolt-js/sdk'

Overview

A module for platform provided advertising settings and functionality.

Methods

advertisingId

Get the advertising ID

function advertisingId(options?: AdvertisingIdOptions): Promise<object>

Parameters:

Promise resolution:

Capabilities:

Examples

Getting the advertising ID

JavaScript:

import { Advertising } from '@firebolt-js/sdk'

Advertising.advertisingId(null)
    .then(advertisingId => {
        console.log(advertisingId)
    })

Value of advertisingId:

{
	"ifa": "01234567-89AB-CDEF-GH01-23456789ABCD",
	"ifa_type": "idfa",
	"lmt": "0"
}

{
	"jsonrpc": "2.0",
	"id": 1,
	"method": "Advertising.advertisingId",
	"params": {}
}

{
	"jsonrpc": "2.0",
	"id": 1,
	"result": {
		"ifa": "01234567-89AB-CDEF-GH01-23456789ABCD",
		"ifa_type": "idfa",
		"lmt": "0"
	}
}

Getting the advertising ID with scope browse

JavaScript:

import { Advertising } from '@firebolt-js/sdk'

Advertising.advertisingId({"scope":{"type":"browse","id":"paidPlacement"}})
    .then(advertisingId => {
        console.log(advertisingId)
    })

Value of advertisingId:

{
	"ifa": "01234567-89AB-CDEF-GH01-23456789ABCD",
	"ifa_type": "idfa",
	"lmt": "0"
}

{
	"jsonrpc": "2.0",
	"id": 1,
	"method": "Advertising.advertisingId",
	"params": {
		"options": {
			"scope": {
				"type": "browse",
				"id": "paidPlacement"
			}
		}
	}
}

{
	"jsonrpc": "2.0",
	"id": 1,
	"result": {
		"ifa": "01234567-89AB-CDEF-GH01-23456789ABCD",
		"ifa_type": "idfa",
		"lmt": "0"
	}
}

Getting the advertising ID with scope content

JavaScript:

import { Advertising } from '@firebolt-js/sdk'

Advertising.advertisingId({"scope":{"type":"content","id":"metadata:linear:station:123"}})
    .then(advertisingId => {
        console.log(advertisingId)
    })

Value of advertisingId:

{
	"ifa": "01234567-89AB-CDEF-GH01-23456789ABCD",
	"ifa_type": "idfa",
	"lmt": "0"
}

{
	"jsonrpc": "2.0",
	"id": 1,
	"method": "Advertising.advertisingId",
	"params": {
		"options": {
			"scope": {
				"type": "content",
				"id": "metadata:linear:station:123"
			}
		}
	}
}

{
	"jsonrpc": "2.0",
	"id": 1,
	"result": {
		"ifa": "01234567-89AB-CDEF-GH01-23456789ABCD",
		"ifa_type": "idfa",
		"lmt": "0"
	}
}

appBundleId

Get the App's Bundle ID

function appBundleId(): Promise<string>

Promise resolution:

string

Capabilities:

Examples

Default Example

JavaScript:

import { Advertising } from '@firebolt-js/sdk'

Advertising.appBundleId()
    .then(appBundleId => {
        console.log(appBundleId)
    })

Value of appBundleId:

"operator.app"

{
	"jsonrpc": "2.0",
	"id": 1,
	"method": "Advertising.appBundleId",
	"params": {}
}

{
	"jsonrpc": "2.0",
	"id": 1,
	"result": "operator.app"
}

config

Build configuration object for Ad Framework initialization

function config(options: AdConfigurationOptions): Promise<object>

Parameters:

Promise resolution:

object

Capabilities:

Examples

Initializing the Ad Framework

JavaScript:

import { Advertising } from '@firebolt-js/sdk'

Advertising.config({"environment":"prod","authenticationEntity":"MVPD"})
    .then(adFrameworkConfig => {
        console.log(adFrameworkConfig)
    })

Value of adFrameworkConfig:

{
	"adServerUrl": "https://demo.v.fwmrm.net/ad/p/1",
	"adServerUrlTemplate": "https://demo.v.fwmrm.net/ad/p/1?flag=+sltp+exvt+slcb+emcr+amcb+aeti&prof=12345:caf_allinone_profile &nw=12345&mode=live&vdur=123&caid=a110523018&asnw=372464&csid=gmott_ios_tablet_watch_live_ESPNU&ssnw=372464&vip=198.205.92.1&resp=vmap1&metr=1031&pvrn=12345&vprn=12345&vcid=1X0Ce7L3xRWlTeNhc7br8Q%3D%3D",
	"adNetworkId": "519178",
	"adProfileId": "12345:caf_allinone_profile",
	"adSiteSectionId": "caf_allinone_profile_section",
	"adOptOut": true,
	"privacyData": "ew0KICAicGR0IjogImdkcDp2MSIsDQogICJ1c19wcml2YWN5IjogIjEtTi0iLA0KICAibG10IjogIjEiIA0KfQ0K",
	"ifaValue": "01234567-89AB-CDEF-GH01-23456789ABCD",
	"ifa": "ewogICJ2YWx1ZSI6ICIwMTIzNDU2Ny04OUFCLUNERUYtR0gwMS0yMzQ1Njc4OUFCQ0QiLAogICJpZmFfdHlwZSI6ICJzc3BpZCIsCiAgImxtdCI6ICIwIgp9Cg==",
	"appName": "FutureToday",
	"appBundleId": "FutureToday.comcast",
	"distributorAppId": "1001",
	"deviceAdAttributes": "ewogICJib0F0dHJpYnV0ZXNGb3JSZXZTaGFyZUlkIjogIjEyMzQiCn0=",
	"coppa": 0,
	"authenticationEntity": "60f72475281cfba3852413bd53e957f6"
}

{
	"jsonrpc": "2.0",
	"id": 1,
	"method": "Advertising.config",
	"params": {
		"options": {
			"environment": "prod",
			"authenticationEntity": "MVPD"
		}
	}
}

{
	"jsonrpc": "2.0",
	"id": 1,
	"result": {
		"adServerUrl": "https://demo.v.fwmrm.net/ad/p/1",
		"adServerUrlTemplate": "https://demo.v.fwmrm.net/ad/p/1?flag=+sltp+exvt+slcb+emcr+amcb+aeti&prof=12345:caf_allinone_profile &nw=12345&mode=live&vdur=123&caid=a110523018&asnw=372464&csid=gmott_ios_tablet_watch_live_ESPNU&ssnw=372464&vip=198.205.92.1&resp=vmap1&metr=1031&pvrn=12345&vprn=12345&vcid=1X0Ce7L3xRWlTeNhc7br8Q%3D%3D",
		"adNetworkId": "519178",
		"adProfileId": "12345:caf_allinone_profile",
		"adSiteSectionId": "caf_allinone_profile_section",
		"adOptOut": true,
		"privacyData": "ew0KICAicGR0IjogImdkcDp2MSIsDQogICJ1c19wcml2YWN5IjogIjEtTi0iLA0KICAibG10IjogIjEiIA0KfQ0K",
		"ifaValue": "01234567-89AB-CDEF-GH01-23456789ABCD",
		"ifa": "ewogICJ2YWx1ZSI6ICIwMTIzNDU2Ny04OUFCLUNERUYtR0gwMS0yMzQ1Njc4OUFCQ0QiLAogICJpZmFfdHlwZSI6ICJzc3BpZCIsCiAgImxtdCI6ICIwIgp9Cg==",
		"appName": "FutureToday",
		"appBundleId": "FutureToday.comcast",
		"distributorAppId": "1001",
		"deviceAdAttributes": "ewogICJib0F0dHJpYnV0ZXNGb3JSZXZTaGFyZUlkIjogIjEyMzQiCn0=",
		"coppa": 0,
		"authenticationEntity": "60f72475281cfba3852413bd53e957f6"
	}
}

deviceAttributes

Get the device advertising device attributes

function deviceAttributes(): Promise<object>

Promise resolution:

object

Capabilities:

Examples

Getting the device attributes

JavaScript:

import { Advertising } from '@firebolt-js/sdk'

Advertising.deviceAttributes()
    .then(deviceAttributes => {
        console.log(deviceAttributes)
    })

Value of deviceAttributes:

{}

{
	"jsonrpc": "2.0",
	"id": 1,
	"method": "Advertising.deviceAttributes",
	"params": {}
}

{
	"jsonrpc": "2.0",
	"id": 1,
	"result": {}
}

listen

To listen to a specific event pass the event name as the first parameter:

listen(event: string, callback: (data: any) => void): Promise<number>

Parameters:

Promise resolution:

Callback parameters:

To listen to all events from this module pass only a callback, without specifying an event name:

listen(callback: (event: string, data: any) => void): Promise<number>

Parameters:

Callback parameters:

Promise resolution:

See Listening for events for more information and examples.

once

To listen to a single instance of a specific event pass the event name as the first parameter:

once(event: string, callback: (data: any) => void): Promise<number>

The once method will only pass the next instance of this event, and then dicard the listener you provided.

Parameters:

Promise resolution:

Callback parameters:

To listen to the next instance only of any events from this module pass only a callback, without specifying an event name:

once(callback: (event: string, data: any) => void): Promise<number>

Parameters:

Callback parameters:

Promise resolution:

See Listening for events for more information and examples.

policy

Get the advertising privacy and playback policy

To get the value of policy call the method like this:

function policy(): Promise<AdPolicy>

Promise resolution:

AdPolicy

Capabilities:

Examples

Getting the advertising policy settings

JavaScript:

import { Advertising } from '@firebolt-js/sdk'

Advertising.policy()
    .then(adPolicy => {
        console.log(adPolicy)
    })

Value of adPolicy:

{
	"skipRestriction": "adsUnwatched",
	"limitAdTracking": false
}

{
	"jsonrpc": "2.0",
	"id": 1,
	"method": "Advertising.policy",
	"params": {}
}

{
	"jsonrpc": "2.0",
	"id": 1,
	"result": {
		"skipRestriction": "adsUnwatched",
		"limitAdTracking": false
	}
}

To subscribe to notifications when the value changes, call the method like this:

function policy(callback: (value) => AdPolicy): Promise<number>

Promise resolution:

number

Examples

Getting the advertising policy settings

JavaScript:

import { Advertising } from '@firebolt-js/sdk'

policy(value => {
  console.log(value)
}).then(listenerId => {
  console.log(listenerId)
})

Value of adPolicy:

{
	"skipRestriction": "adsUnwatched",
	"limitAdTracking": false
}

{
	"jsonrpc": "2.0",
	"id": 1,
	"method": "Advertising.onPolicyChanged",
	"params": {
		"listen": true
	}
}

{
	"jsonrpc": "2.0",
	"id": 1,
	"result": {
		"skipRestriction": "adsUnwatched",
		"limitAdTracking": false
	}
}

Events

policyChanged

See: policy

Types

AdConfigurationOptions

type AdConfigurationOptions = {
  coppa?: boolean                // Whether or not the app requires US COPPA compliance.
  environment?: 'prod' | 'test'  // Whether the app is running in a production or test mode.
  authenticationEntity?: string  // The authentication provider, when it is separate entity than the app provider, e.g. an MVPD.
}

AdPolicy

Describes various ad playback enforcement rules that the app should follow.

type AdPolicy = {
  skipRestriction?: SkipRestriction  // The advertisement skip restriction.
  limitAdTracking?: boolean
}

See also:

'none' | 'adsUnwatched' | 'adsAll' | 'all'

AdvertisingIdOptions

type AdvertisingIdOptions = {
  scope?: {
    type: 'browse' | 'content'  // The scope type, which will determine where to show advertisement
    id: string                  // A value that identifies a specific scope within the scope type
  }
}