Advertising Module

Version Advertising 1.4.1

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 IAB compliant identifier for advertising (IFA). It is recommended to use the IFA to manage advertising related activities while respecting the user’s privacy settings.

function advertisingId(
  options: AdvertisingIdOptions,
): Promise<AdvertisingIdResult>

Parameters:

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

Promise resolution:

AdvertisingIdResult

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": "sspid",
	"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": "sspid",
    "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": "sspid",
	"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": "sspid",
    "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": "sspid",
	"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:

'app.operator'

JSON-RPC:

Request:

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

Response:

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

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:advertising:policy

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
}

AdvertisingIdResult

type AdvertisingIdResult = {
  ifa: string // UUID conforming to IAB standard
  ifa_type: string // source of the IFA as defined by IAB
  lmt: '0' | '1' // boolean that if set to 1, user has requested ad tracking and measurement is disabled
}

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

AdvertisingIdResult