Advertising Module

Version Advertising 1.3.0

Table of Contents
Usage
Overview
Methods
- advertisingId
- appBundleId
- config
- deviceAttributes
- listen
- once
- policy
Events
- policyChanged
Types

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:

Param	Type	Required	Description
`options`	`AdvertisingIdOptions`	false	AdvertisingId options

Promise resolution:

Capabilities:

Role	Capability
uses	xrn:firebolt:capability:advertising:identifier

Examples

Getting the advertising ID

JavaScript:

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

let advertisingId = await Advertising.advertisingId(null)
console.log(advertisingId)

Value of advertisingId:

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

JSON-RPC:

Request:

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

Response:

{
  "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'

let advertisingId = await Advertising.advertisingId({
  scope: { type: 'browse', id: 'paidPlacement' },
})
console.log(advertisingId)

Value of advertisingId:

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

JSON-RPC:

Request:

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

Response:

{
  "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'

let advertisingId = await Advertising.advertisingId({
  scope: { type: 'content', id: 'metadata:linear:station:123' },
})
console.log(advertisingId)

Value of advertisingId:

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

JSON-RPC:

Request:

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

Response:

{
  "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:

Capabilities:

Role	Capability
uses	xrn:firebolt:capability:advertising:configuration

Examples

Default Example

JavaScript:

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

let appBundleId = await Advertising.appBundleId()
console.log(appBundleId)

Value of appBundleId:

'operator.app'

JSON-RPC:

Request:

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

Response:

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

config

Build configuration object for Ad Framework initialization

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

Parameters:

Param	Type	Required	Description
`options`	`AdConfigurationOptions`	true	Configuration options

Promise resolution:

Capabilities:

Role	Capability
uses	xrn:firebolt:capability:advertising:configuration

Examples

Initializing the Ad Framework

JavaScript:

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

let adFrameworkConfig = await Advertising.config({
  environment: 'prod',
  authenticationEntity: 'MVPD',
})
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"
}

JSON-RPC:

Request:

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

Response:

{
  "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:

Capabilities:

Role	Capability
uses	xrn:firebolt:capability:advertising:configuration

Examples

Getting the device attributes

JavaScript:

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

let deviceAttributes = await Advertising.deviceAttributes()
console.log(deviceAttributes)

Value of deviceAttributes:

{
}

JSON-RPC:

Request:

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

Response:

{
  "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:

Param	Type	Required	Summary
`event`	`string`	Yes	The event to listen for, see Events.
callback	`function`	Yes	A function that will be invoked when the event occurs.

Promise resolution:

Type	Description
`number`	Listener ID to clear the callback method and stop receiving the event, e.g. `Advertising.clear(id)`

Callback parameters:

Param	Type	Required	Summary
`data`	`any`	Yes	The event data, which depends on which event is firing, see Events.

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:

Param	Type	Required	Summary
callback	`function`	Yes	A function that will be invoked when the event occurs. The event data depends on which event is firing, see Events.

Callback parameters:

Param	Type	Required	Summary
`event`	`string`	Yes	The event that has occured listen for, see Events.
`data`	`any`	Yes	The event data, which depends on which event is firing, see Events.

Promise resolution:

Type	Description
`number`	Listener ID to clear the callback method and stop receiving the event, e.g. `Advertising.clear(id)`

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:

Param	Type	Required	Summary
`event`	`string`	Yes	The event to listen for, see Events.
callback	`function`	Yes	A function that will be invoked when the event occurs.

Promise resolution:

Type	Description
`number`	Listener ID to clear the callback method and stop receiving the event, e.g. `Advertising.clear(id)`

Callback parameters:

Param	Type	Required	Summary
`data`	`any`	Yes	The event data, which depends on which event is firing, see Events.

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:

Param	Type	Required	Summary
callback	`function`	Yes	A function that will be invoked when the event occurs. The event data depends on which event is firing, see Events.

Callback parameters:

Param	Type	Required	Summary
`event`	`string`	Yes	The event that has occured listen for, see Events.
`data`	`any`	Yes	The event data, which depends on which event is firing, see Events.

Promise resolution:

Type	Description
`number`	Listener ID to clear the callback method and stop receiving the event, e.g. `Advertising.clear(id)`

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:

Role	Capability
uses	xrn:firebolt:capability:privacy:advertising xrn:firebolt:capability:advertising:configuration

Examples

Getting the advertising policy settings

JavaScript:

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

let adPolicy = await Advertising.policy()
console.log(adPolicy)

Value of adPolicy:

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

JSON-RPC:

Request:

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

Response:

{
  "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'

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

Value of adPolicy:

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

JSON-RPC:

Request:

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

Response:

{
  "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
}

AdvertisingIdOptions

type AdvertisingIdOptions = {
  scope?: object // Provides the options to send scope type and id to select desired advertising id
}

Advertising Module

Table of Contents

Usage

Overview

Methods

advertisingId

Examples

appBundleId

Examples

config

Examples

deviceAttributes

Examples

listen

once

policy

Examples

Examples

Events

policyChanged

Types

AdConfigurationOptions

AdPolicy

AdvertisingIdOptions