@tivio/ads-js v2.0.1

Tivio Ads JS

Tivio Ads supports management of advertisement from various sources.

Changelog

Installation

npm install --save @tivio/ads-js

or

yarn add @tivio/ads-js

API

Direct exports

The following functions can be directly imported from @tivio/ads-js.

createTivio

Promise which has to be called with the main Tivio configuration to enable Tivio ads functionalities. It resolves the promise with object containing API which means that this API you can use after the Tivio initialization is complete.

createTivio: (incomingConf: Conf) => Promise<RemoteBundleState>

createPlayerWrapper

Returns Tivio Player Wrapper instance.

Can be called even before Tivio initialization (see createTivio) is completed but in that case it doesn’t wait to Tivio initialisation so you may miss some markers.

You have to pass only two functions (setSource and seekTo) which lead to your low level player implementation of these functions.

createPlayerWrapper: (playerImplementation: PlayerInterfaceForPlayerWrapper) => TivioPlayerWrapper

getProgramTimestamps

Returns real start and end timestamps for the given program. This method is handy when your stream source URIs contain start and end timestamps so you can create URIs which contain exact time interval instead of creating bigger interval and seek inside it (to the real start).

Can be called even before Tivio initialization (see createTivio) is complete but in that case you will not receive these markers.

getProgramTimestamps: (channelName: string, epgFrom: Date, epgTo: Date) => Result

Tivio instance API

The following methods are accessible in the API object obtained from createTivio.

setUser

It authorizes operator’s user against the Tivio platform and activates user payments, recommendation and other user specific features.

It accepts your identifier of the user and data necessary for authorization (e.g. operator’s access token).

setUser: (userId: string, payload: Record<string, unknown>) => Promise<void>

Player Wrapper API

The following methods are accessible on Tivio Player Wrapper instance which was created by createPlayerWrapper.

addEventListener

Provides the way how to listen to changes. You can listen to markers or ads metadata. Markers event is fired when stream source has changed and it provides all markers for the current stream. Ads metadata event is fired when ad starts to play and then repeatedly during ad playback.

addEventListener: (eventType: PlayerWrapperEventTypeType, listener: Listener) => void

reportError

This method should be called every time the playback fails.

reportError: (error: Error) => void

reportPlaybackEnded

This method should be called every time the playback is stopped or reaches the end.

reportPlaybackEnded: () => void

reportTimeProgress

This method should be called every time the position of playback changes. It is a good practice to call it once per second. Position is expected to be in milliseconds and relative to the beginning of the stream.

reportTimeProgress: (ms: number) => void

seekTo

This method should be called every time you need to seek in the player. Tivio Ads can skip this action when seek is not currently allowed (e.g. while playing ad) or correct required position to the better one (e.g. when trying to seek to ads in the original stream) or simple do not touch this position. At the end it will call seekTo you have provided in createPlayerWrapper.

It can also leads to call setSource you have provided in createPlayerWrapper (e.g. when trying to seek to ads in the original stream and ads replacement is active).

seekTo: (ms: number) => void

setSource

This method should be called every time you need to start playback. Tivio Ads can change required source to the different one (ad source) or correct required position to the better one (e.g. when Tivio Ads knows real start of required stream) or simple do not touch anything. At the end it will call setSource you have provided in createPlayerWrapper.

Of course it remembers source you have originally required so after all ads were played it will call setSource you have provided in createPlayerWrapper with this source.

setSource: (source: Source | null, calibrationId?: string) => void

Types

The list of types which are used in the documentation above.

type Conf = {
    /**
     * Tells Tivio which technologies/protocols etc. is the device capable to play.
     * If not provided, Tivio will try to guess it (based on the browser).
     */
    deviceCapabilities?: PlayerCapability[]
    /**
     * Secret which is paired with organization.
     */
    secret: string
    /**
     * Can turn off Tivio's Sentry logging, defaults to true.
     */
    enableSentry?: boolean
    /**
     * Can turn on Tivio's console logging, defaults to false.
     */
    verbose?: boolean
}

type ExposedApi = {
    /**
     * Set user authorizes operator’s user against the Tivio platform and activates user payments, recommendation
     * and other user specific features.
     *
     * @param userId - operator’s user identifier
     * @param payload - data necessary for authorization (e.g. operator’s access token)
     */
    setUser: (userId: string, payload: Record<string, unknown>) => Promise<void>
}

type RemoteBundleErrorState = {
    state: 'error'
    error: string | null
    conf: InternalConf
}

type RemoteBundleOkState = {
    state: 'ready'
    error: null
    conf: InternalConf
} & ExposedApi

type RemoteBundleState = RemoteBundleErrorState | RemoteBundleOkState

interface PlayerInterfaceForPlayerWrapper {
    /**
     * @param {number} ms - milliseconds relative to start of video (relative to 0 ms)
     *  or in case of TV programs relative to start of the program (relative to source.from ms)
     */
    seekTo: (ms: number) => void
    /**
     * @param {Source} source - source to be player
     */
    setSource: (source: Source | null) => void
}

type SourceBase = {
    /**
     * Tivio SDK users may use pretty complicated source objects in their existing code and if Tivio player
     * is an interception layer, it should allow them to pass through any type of object.
     */
    additionalPayload?: Record<string, any>
    /**
     * Source type.
     */
    type: 'ad' | 'live_tv_channel' | 'other' | 'tivio_vod' | 'tv_program'
    /**
     * URI to play.
     */
    uri: string
}

type StartAndContinuePosition= {
    /**
     * Relative from stream start, in ms.
     * Should be always provided except continueFromPosition is present.
     * Tivio can correct this value to the real program start position.
     */
    startFromPosition?: number
    /**
     * Relative from stream start, in ms.
     * If provided, tivio will not correct it and will send this value back in startFromPosition.
     * If provided, startFromPosition is ignored.
     */
    continueFromPosition?: number
}

type TvProgramSource = SourceBase & StartAndContinuePosition & {
    type: 'tv_program'
    /**
     * If epgTo is wrong, Tivio cannot correctly guess if the video it startover or timeshift . For such cases
     * Tivio needs explicit tv mode.
     * null if source begins in the future.
     */
    tvMode: 'startover' | 'timeshift' | null
    /**
     * Tivio needs channel name in order to load markers.
     */
    channelName: string
    /**
     * Tivio needs EPG from in order to load markers.
     */
    epgFrom: Date
    /**
     * Tivio needs EPG to in order to load markers.
     */
    epgTo: Date
    /**
     * When the stream (provided in uri) really starts - typically few minutes before epgFrom.
     */
    streamStart: Date
}

type AdSource = SourceBase & {
    type: 'ad'
}

/**
 * If Tivio PlayerWrapper is an interception layer, it should allow the pass-through
 * of not just Tivio source types but any other source types that the 3rd party app may be using.
 */
type OtherSource = SourceBase & StartAndContinuePosition & {
    type: 'other'
}

/**
 * Not supported yet, now it does pass-through only.
 */
type LiveTvChannelSource = SourceBase & {
    type: 'live_tv_channel'
    /**
     * Tivio needs channel name in order to load markers.
     */
    channelName: string
}

type Source = TvProgramSource | AdSource | OtherSource | LiveTvChannelSource

interface TivioPlayerWrapper {
    /**
     * @param eventType - event type to listen
     * @param listener - listener to be notified
     */
    addEventListener: (eventType: PlayerWrapperEventTypeType, listener: Listener) => void
    /**
     * @param error
     */
    reportError: (error: Error) => void
    reportPlaybackEnded: () => void
    /**
     * @param ms - reported position
     */
    reportTimeProgress: (ms: number) => void
    /**
     * @param ms - position to seek to
     */
    seekTo: (ms: number) => void
    /**
     * @param {Source} source - source to set
     * @param {string} calibrationId - id of calibration profile
     */
    setSource: (source: Source | null, calibrationId?: string) => void
}

enum PlayerWrapperEventType {
    adMetadata = 'adMetadata',
    markers = 'markers'
}

type PlayerWrapperEventTypeType = `${PlayerWrapperEventType}`

type ListenerAdMetadata = (metadata: AdMetadata) => void
type ListenerMarkers = (marker: Marker[] | null) => void
type Listener = ListenerAdMetadata | ListenerMarkers