playback-web-middleware v0.7.1

Playback Web Middleware

A "middleware" which serves as the glue between playback-web-player (the player library) and the catalogue "chapter" of any target application which is built upon the web stack (HTML/CSS/JavaScript).

Design Goals

• Remove complexity from catalogue chapters, and own all playback-related features, API calls and business logic not directly related to playing and interacting with a video.
• Allow the player library itself to remain highly generic and environment agnostic.
• Create an entry point into the player for other teams (e.g. sport data) while ring-fencing and isolating the most critical playback functionality

Contents

• Getting Started
  • Installation
  • Instantiation
  • Usage
• Developer
• Sandbox

Getting Started

The following guide is aimed at consumers of the player middleware looking to integrate it with an application. If you are a developer looking to make changes to the middleware source code, please see the Developer guide.

Installation

To install, add the repository's git+ssh path to your project's dependencies, specifying the desired release tag as a hash segment:

...
"dependencies": {
    "playback-web-middleware": "git+ssh://git@github.com/getndazn/playback-web-middleware.git#vX.Y.Z",
    ...
}

You may then run npm install to download and install the package locally. You will need to be SSH authenticated (e.g. a member of the getndazn organisation) in order to do this.

Once installed, you may then import the Middleware's React component into your project's modules as desired:

import PlayerMiddleware from 'playback-web-middleware';

Instantiation

The PlayerMiddleware React component may be used to create discrete instances of the player within an existing React application. Currently, a React component is used to abstract and wrap instantiation, and provide a convenient entry point into the player for compatible catalogue "chapters".

The component can be provided with two props:

• An optional config object, providing an initial set of configuration options.
• An onPlayerReady callback function, to be invoked by the middleware once the component has mounted and the player is ready to be interacted with. The callback provides the consumer with a single object as an argument, which is a reference to the middleware instance.

import PlayerMiddleware from 'playback-web-middleware';

class MyComponent extends React.Component {
    this.handlePlayerReady = this.handlePlayerReady.bind(this);

    this.initialConfig = {
        ...
    };

    handlePlayerReady(playerMiddleware) {
        this.playerMiddleware = playerMiddleware;
    }

    componentWillUnmount() {
        this.playerMiddleware.destroy();
    }

    render() {
        return (
            <PlayerMiddleware
                onPlayerReady={this.handlePlayerReady}
                config={this.initialConfig}
            />
        );
    }
}

The object passed to the config prop, can includes zero or more configuration options with which to configure the middleware and underlying player.

For example:

<PlayerMiddleware
    onPlayerReady={this.handlePlayerReady}
    config={{
        serviceUrls: {
            playback: 'https://foo.bar.baz/api/playback/v2'
        }
    }}
/>

When used in a DAZN catalogue environment where data has been made available by bootstrap via window.dazn, the middleware will attempt to ingest as much configuration as possible from the environment by default, although options may still be manually overridden.

Further reading: Configuration Options

Usage

API Methods

The middleware instance returned from the factory function exposes various API methods with which to interact with the player, the most important being the .loadAsset() method, used to load assets into the player.

NB: The asset object passed to the .loadAsset() is equivalent to a Tile object from the common-web-dazn catalogue. Although the middleware is only concerned with subset of this object, the entire tile may be passed.

For example:

import PlayerMiddleware from 'playback-web-middleware';

class MyComponent extends React.Component {
    ...

    loadAsset(asset) {
        this.playerMiddleware.loadAsset(asset);
    }

    ...
}

Further reading: API Methods

Handling Output

In order for the consumer application to react to emissions and state changes from the middleware and underlying player, two observable streams are also exposed: .legacyShim$ and .playerInteractions$.

The legacyShim$ stream was designed to follow the API of the previous "common-player" integration and expedite the initial integration with the common-web-dazn catalogue chapter. This should be deemed a temporary API however (hence "shim"), and as other teams integrate with the player middleware, we will work with them to design a more fit-for-purpose and optimized API. Similarly, as more playback-related functionality and UI is migrated from the catalogue into the playback domain, far less data will need to be exposed.

The playerInteractions$ stream emits information about user interactions with the player, which could then be passed onto Google Analytics by the catalogue application.

Consumers can subscribe to these streams as soon the reference to the player middleware is received via a handler supplied to the onPlayerReady callback prop:

class MyComponent extends React.Component {
    ...

    handlePlayerReady(playerMiddleware) {
        this.playerMiddleware = playerMiddleware;

        this.playerMiddleware.legagcyShim$.subscribe(this.subscribeToPlayerState);
        this.playerMiddleware.playerInteractions$.subscribe(this.subscribeToPlayerInteractions);
    }

    ...
}

Developer

To install project dependencies, run:

$ npm install

Once dependencies are installed, you may run any of the following NPM scripts as needed using:

$ npm run {script}

Linting

lint

Lints JavaScript according to the rules defined in /config/eslint/.eslintrc.

Testing

test

Runs all unit tests using Mocha/Chai, according to the configuration defined in /config/mocha/mocha.opts.

test:watch

Runs tests on changes to any .js file.

test:cover

Runs tests with a final coverage report, and failing if the coverage is below that specified in /config/.nycrc.json.

Building and Development

dev

Creates an in-memory bundle for development according to the default configuration defined in /config/webpack/dev.config.js and serves it via webpack-dev-server on localhost:8080.

build

Creates a minified production UMD bundle for the middleware including the player and all (non-peer) dependencies.

build:dev

Creates a bundled sandbox application in the dist directory with which to drive and test the middleware.

build:analyze

Creates a production bundle and then opens the webpack bundle analyzer tool in order to inspect the size of dependencies.

publish

Creates a production bundle and commits it to a tagged release branch of the provided semver tag. Deletes all non-deliverables from the branch before releasing. The desired tag must be passed as an argument, e.g. npm run publish -- 1.2.3.

This should be considered a temporary solution to publishing that should eventually be replaced with a more standard npm publish approach.

Sandbox

A sandbox implementation of the middleware is provided in the /sandbox/ directory for the purposes of expediting testing and development by removing the overhead of a full catalog integration, and also removing the potential for catalog regressions to impact development of the player.

In order to use the sandbox, run npm run dev, and navigate to localhost:8080. When using the sandbox, the middleware instance is exposed via the window.middleware property to assist with debugging.

In order to easily test against real DAZN content, a basic authentication form and asset selection UI has been included to quickly load protected media from DAZN's API.