[@liveryvideo/interactive-bridge](../index.md) / InteractiveBridge # Class: InteractiveBridge Can be used by a Livery interactive layer element or page to communicate with the surrounding Livery Player. ## Example ```js import { InteractiveBridge } from '@liveryvideo/interactive-bridge'; // The `playerBridge` will be provided to you as interactive element // Or, as interactive page, to prevent cross site security issues: // https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage#security_concerns // replace `'*'` by the origin of the page that the player is expected to be on const bridge = new InteractiveBridge(playerBridge || '*'); bridge.getAppName().then(appName => window.alert(`appName: ${appName}`)); ``` ## Extends - [`LiveryBridge`](LiveryBridge.md) ## Constructors ### Constructor > **new InteractiveBridge**(`target`, `options?`): `InteractiveBridge` Constructs `InteractiveBridge` with specified `target` player bridge or with `window.parent` as target window and with specified string as origin. #### Parameters ##### target Player bridge or window origin to target `string` | [`AbstractPlayerBridge`](AbstractPlayerBridge.md) ##### options? Options for this bridge and [InteractivePlayerOptions](../interfaces/InteractivePlayerOptions.md) ###### controlsDisabled? `boolean` True if default player controls should be disabled to use custom controls instead, false otherwise. ###### handleAuth? (`tokenOrClaims?`) => `void` Handles authentication data coming from the player. #### Returns `InteractiveBridge` #### Overrides [`LiveryBridge`](LiveryBridge.md).[`constructor`](LiveryBridge.md#constructor) ## Methods ### getAppName() > **getAppName**(): `Promise`\<`string`\> Returns promise of player application name. #### Returns `Promise`\<`string`\> *** ### ~~getCustomerId()~~ > **getCustomerId**(): `Promise`\<`string`\> Returns promise of player customer id. #### Returns `Promise`\<`string`\> #### Deprecated Instead use [subscribeConfig](#subscribeconfig).customerId *** ### getEndpointId() > **getEndpointId**(): `Promise`\<`string`\> Returns promise of player Pinpoint analytics endpoint id. #### Returns `Promise`\<`string`\> *** ### getFeatures() > **getFeatures**(): `Promise`\<[`Features`](../interfaces/Features.md)\> Returns promise of a registry of features supported by the player in general and under given circumstances. #### Returns `Promise`\<[`Features`](../interfaces/Features.md)\> *** ### ~~getLatency()~~ > **getLatency**(): `Promise`\<`number`\> Returns promise of current player latency in seconds. #### Returns `Promise`\<`number`\> #### Deprecated Instead use [getPlayback](#getplayback).latency *** ### getLiveryParams() > **getLiveryParams**(): `Promise`\<`Record`\<`string`, `string`\>\> Returns promise of an object of key-value string parameters from player. Android and iOS players will call a callback and pass on the returned values. The web player will return all 'livery_' prefixed query parameters with: - The prefix stripped from the names (snake_case will not be converted to camelCase) - Parameter names and values URL decoded - Empty string (not `null`) values for parameters without a value - Only the first value of a repeated parameter (no multiple value array support) So given location.search: `'?foo&livery_foo%3Abar=hey+you&livery_no_val&livery_multi=1&livery_multi=2'` this will return: `{ 'foo:bar': 'hey you', no_val: '', multi: '1' }`. #### Returns `Promise`\<`Record`\<`string`, `string`\>\> *** ### getPlayback() > **getPlayback**(): `Promise`\<[`PlaybackDetails`](../interfaces/PlaybackDetails.md)\> Returns promise of current playback details, i.e: values that are continuously changing. #### Returns `Promise`\<[`PlaybackDetails`](../interfaces/PlaybackDetails.md)\> *** ### getPlayerVersion() > **getPlayerVersion**(): `Promise`\<`string`\> Returns promise of player version. #### Returns `Promise`\<`string`\> *** ### getStreamId() > **getStreamId**(): `Promise`\<`string`\> Returns promise of player stream id. #### Returns `Promise`\<`string`\> *** ### pause() > **pause**(): `Promise`\<`unknown`\> Pause playback. #### Returns `Promise`\<`unknown`\> *** ### play() > **play**(): `Promise`\<`unknown`\> Attempt to start or resume playback. Can fail if not allowed by the browser, e.g: when not called directly from a click event listener. In that case it can fall back to muted playback, changing [subscribeVolume](#subscribevolume).muted to true. Or if that also fails then [subscribePaused](#subscribepaused) will remain true. #### Returns `Promise`\<`unknown`\> *** ### ~~registerCustomCommand()~~ > **registerCustomCommand**(`name`, `handler`): `void` Register `handler` function to be called with `arg` and `listener` when `sendCustomCommand()` is called on other side with matching `name`. #### Parameters ##### name `string` ##### handler (`arg`, `listener`) => `unknown` #### Returns `void` #### Deprecated Instead use [registerInteractiveCommand](#registerinteractivecommand) #### Overrides `LiveryBridge.registerCustomCommand` *** ### registerInteractiveCommand() > **registerInteractiveCommand**(`name`, `handler`): `void` Register `handler` function to be called with `arg` and `listener` when `sendInteractiveCommand()` is called from the player side with matching `name`. #### Parameters ##### name `string` Custom command name to listen to ##### handler (`arg`, `listener`) => `unknown` Function to handle those commands and whose value to return to it #### Returns `void` *** ### reload() > **reload**(): `Promise`\<`unknown`\> Reload player, e.g: to try to recover from an error. #### Returns `Promise`\<`unknown`\> *** ### seek() > **seek**(`position`): `Promise`\<`unknown`\> Seek to specified `position` in seconds since start of stream/VOD. Where `position` needs to be within a `'LIVE'` interval of [subscribeConfig](#subscribeconfig).streamPhases and the [getPlayback](#getplayback).duration. Requires: [getFeatures](#getfeatures).scrubber. #### Parameters ##### position `number` Position in seconds since start of stream/VOD to seek to #### Returns `Promise`\<`unknown`\> *** ### selectQuality() > **selectQuality**(`index`): `Promise`\<`unknown`\> Select quality at specified index of [subscribeQualities](#subscribequalities).list or -1 to use ABR. #### Parameters ##### index `number` Index of quality to select #### Returns `Promise`\<`unknown`\> #### Throws Error "Player unconfigured" when config has not been loaded yet #### Throws Error "Qualities undefined" when stream qualities have not been loaded yet #### Throws Error "Cannot select quality when a quality is forced" #### Throws RangeError when index is not -1 or a valid quality index *** ### ~~sendCustomCommand()~~ > **sendCustomCommand**(`name`, `arg?`, `listener?`): `Promise`\<`unknown`\> Returns promise of value returned by other side's custom command handler with matching `name` that is passed `arg`. Any `handler` `listener` calls will subsequently also be bridged to this `listener` callback. #### Parameters ##### name `string` ##### arg? `unknown` ##### listener? (`value`) => `void` #### Returns `Promise`\<`unknown`\> #### Deprecated Instead use [sendPlayerCommand](#sendplayercommand) #### Overrides `LiveryBridge.sendCustomCommand` *** ### sendPlayerCommand() > **sendPlayerCommand**(`name`, `arg?`, `listener?`): `Promise`\<`unknown`\> Returns promise of value returned by the player's custom command handler with matching `name` that is passed `arg`. Any `handler` `listener` calls will subsequently also be bridged to this `listener` callback. #### Parameters ##### name `string` Name of custom command to send ##### arg? `unknown` Optional argument to custom command to send ##### listener? (`value`) => `void` Optional listener function to be called with custom command handler listener call values #### Returns `Promise`\<`unknown`\> *** ### setDisplay() > **setDisplay**(`display`): `Promise`\<`unknown`\> Attempt to change display mode to specified value. Can reject if not allowed by the browser, e.g: when not called directly from a click event listener. Requires related feature, i.e: [getFeatures](#getfeatures).airplay, chromecast or fullscreen. #### Parameters ##### display [`DisplayMode`](../type-aliases/DisplayMode.md) Display mode to attempt to change to #### Returns `Promise`\<`unknown`\> *** ### setMuted() > **setMuted**(`muted`): `Promise`\<`unknown`\> Attempt to change `muted` state to specified value. Unmuting can fail if not allowed by the browser, e.g: when not called directly from a click event listener. The specified state is kept track of by the player though and respected on reload when possible. Look at [subscribeVolume](#subscribevolume).muted state to track actual unmuting. #### Parameters ##### muted `boolean` Muted state to attempt to change to #### Returns `Promise`\<`unknown`\> *** ### setVolume() > **setVolume**(`volume`): `Promise`\<`unknown`\> Change `volume` to specified value. When a player starts unmuted at volume `0` and this is changed to a higher volume later, that can be disallowed by the browser, e.g: when not called directly from a click event listener. In that case the player will fall back to changing [subscribeVolume](#subscribevolume).muted to `true` to allow the volume change to persist. Requires: [getFeatures](#getfeatures).volume. #### Parameters ##### volume `number` Volume, between 0 and 1, to change to #### Returns `Promise`\<`unknown`\> *** ### submitUserFeedback() > **submitUserFeedback**(`feedback`): `Promise`\<`unknown`\> Submit user feedback. Requires: [getFeatures](#getfeatures).contact. #### Parameters ##### feedback [`UserFeedback`](../interfaces/UserFeedback.md) User feedback to submit #### Returns `Promise`\<`unknown`\> *** ### subscribeConfig() > **subscribeConfig**(`listener`): `Promise`\<[`Config`](../interfaces/Config.md)\> Returns promise of Livery stream config and calls back `listener` with server side updates or when streamId is changed. #### Parameters ##### listener (`value`) => `void` Listener to call when value is changed #### Returns `Promise`\<[`Config`](../interfaces/Config.md)\> *** ### subscribeDisplay() > **subscribeDisplay**(`listener`): `Promise`\<[`DisplayMode`](../type-aliases/DisplayMode.md)\> Returns promise of current display mode and calls back `listener` with any subsequent display mode changes. #### Parameters ##### listener (`value`) => `void` Listener to call when value is changed #### Returns `Promise`\<[`DisplayMode`](../type-aliases/DisplayMode.md)\> *** ### subscribeError() > **subscribeError**(`listener`): `Promise`\<`string`\> Returns promise of current player error message or undefined and calls back `listener` with any subsequent errors. #### Parameters ##### listener (`value`) => `void` Listener to call when value is changed #### Returns `Promise`\<`string`\> *** ### ~~subscribeFullscreen()~~ > **subscribeFullscreen**(`listener`): `Promise`\<`boolean`\> Returns promise of current player fullscreen state and calls back `listener` with any subsequent state changes. #### Parameters ##### listener (`value`) => `void` #### Returns `Promise`\<`boolean`\> #### Deprecated Instead use [subscribeDisplay](#subscribedisplay).display value "FULLSCREEN" *** ### subscribeMode() > **subscribeMode**(`listener`): `Promise`\<[`PlaybackMode`](../type-aliases/PlaybackMode.md)\> Returns promise of current mode of playback, e.g. how to buffer, sync, adapt quality, manage stalls, etc. and calls back `listener` with any subsequent mode changes. #### Parameters ##### listener (`mode`) => `void` Listener to call when value is changed #### Returns `Promise`\<[`PlaybackMode`](../type-aliases/PlaybackMode.md)\> *** ### ~~subscribeOrientation()~~ > **subscribeOrientation**(`listener`): `Promise`\<[`Orientation`](../type-aliases/Orientation.md)\> Returns promise of current player window orientation (`'landscape' \| 'portrait'`) and calls back `listener` with any subsequent orientations. #### Parameters ##### listener (`value`) => `void` #### Returns `Promise`\<[`Orientation`](../type-aliases/Orientation.md)\> #### Deprecated Will be removed in the next major version. *** ### subscribePaused() > **subscribePaused**(`listener`): `Promise`\<`boolean`\> Returns promise of current `paused` state and calls back `listener` with any subsequent `paused` state updates. Where `paused` is true if `playbackState` is `'PAUSED'` or `'ENDED'`. I.e: Not playing as intended. #### Parameters ##### listener (`value`) => `void` Listener to call when value is changed #### Returns `Promise`\<`boolean`\> *** ### subscribePlaybackState() > **subscribePlaybackState**(`listener`): `Promise`\<[`PlaybackState`](../type-aliases/PlaybackState.md)\> Returns promise of current player playback state and calls back `listener` with any subsequent state updates. #### Parameters ##### listener (`value`) => `void` Listener to call when value is changed #### Returns `Promise`\<[`PlaybackState`](../type-aliases/PlaybackState.md)\> *** ### subscribePlaying() > **subscribePlaying**(`listener`): `Promise`\<`boolean`\> Returns promise of current `playing` state and calls back `listener` with any subsequent `playing` state updates. Where `playing` is true if `playbackState` is `'PLAYING'`, `'FAST_FORWARD'`, `'SLOW_MO'` or `'REWIND'`. I.e: Playing as intended. #### Parameters ##### listener (`value`) => `void` Listener to call when value is changed #### Returns `Promise`\<`boolean`\> *** ### subscribeQualities() > **subscribeQualities**(`listener`): `Promise`\<[`Qualities`](../interfaces/Qualities.md)\> Returns promise of current player stream qualities and calls back `listener` with any subsequent qualities changes. #### Parameters ##### listener (`value`) => `void` Listener to call when value is changed #### Returns `Promise`\<[`Qualities`](../interfaces/Qualities.md)\> *** ### ~~subscribeQuality()~~ > **subscribeQuality**(`listener`): `Promise`\<`string`\> Returns promise of current player stream quality and calls back `listener` with any subsequent quality changes. #### Parameters ##### listener (`value`) => `void` Listener to call when value is changed #### Returns `Promise`\<`string`\> #### Deprecated Instead use [subscribeQualities](#subscribequalities).active *** ### subscribeStalled() > **subscribeStalled**(`listener`): `Promise`\<`boolean`\> Returns promise of current `stalled` state and calls back `listener` with any subsequent `stalled` state updates. Where `stalled` is true if `playbackState` is `'BUFFERING'` or `'SEEKING'`. I.e: Not playing, but trying to. #### Parameters ##### listener (`value`) => `void` Listener to call when value is changed #### Returns `Promise`\<`boolean`\> *** ### ~~subscribeStreamPhase()~~ > **subscribeStreamPhase**(`listener`): `Promise`\<[`StreamPhase`](../type-aliases/StreamPhase.md)\> Returns promise of current player stream phase (`'PRE' \| 'LIVE' \| 'POST'`) and calls back `listener` with any subsequent phases. #### Parameters ##### listener (`phase`) => `void` #### Returns `Promise`\<[`StreamPhase`](../type-aliases/StreamPhase.md)\> #### Deprecated Instead use [subscribeConfig](#subscribeconfig).streamPhase *** ### subscribeVolume() > **subscribeVolume**(`listener`): `Promise`\<[`Volume`](../interfaces/Volume.md)\> Returns promise of current player volume state and calls back `listener` with any subsequent volume changes. #### Parameters ##### listener (`volume`) => `void` Listener to call when value is changed #### Returns `Promise`\<[`Volume`](../interfaces/Volume.md)\> *** ### ~~unregisterCustomCommand()~~ > **unregisterCustomCommand**(`name`): `void` Unregister custom command by name. #### Parameters ##### name `string` #### Returns `void` #### Deprecated Instead use [unregisterInteractiveCommand](#unregisterinteractivecommand) #### Overrides `LiveryBridge.unregisterCustomCommand` *** ### unregisterInteractiveCommand() > **unregisterInteractiveCommand**(`name`): `void` Unregister custom interactive command by name. #### Parameters ##### name `string` Name of custom command handler to unregister #### Returns `void`