Web SDK 2.0

We are currently working on the next generation of web SDK that is smaller and even faster than its prior generation. It is currently available for real-time viewing of channels. Please refer to npmjs.org for the latest available version.

If you have a web application that can be migrated to Web SDK 2.0, follow the guidance in this section. Developers of new applications may also find the information in this section useful.

Manually setting the Stream Selection Strategy on the client is no longer needed in V2. Phenix Web SDK 2.0 has a significantly streamlined and autonomous High Availability implementation.

Web SDK 2.0 improves on V1 by removing hard coded client side logic and replacing it with an automatic server-side approach to deal with a larger variety of HA failover situations. V2's server side logic is more dynamic and allows for Phenix to adjust the HA logic to address novel failover situations without requiring client code updates.

Any client-side code for managing HA should be deprecated.

It may be necessary to update to your code with the new JavaScript here.

Note that your application must not dynamically reference the download area.

Web SDK 2.0 takes advantage of TypeScript to support efficient app development and maintenance. Install the Phenix Web SDK from our npmjs repository using the instructions on that page. Prerequisites for using this include Git, NPM, Preact, and TypeScript.

If you are already using the Phenix Web SDK and are directly modifying JavaScript instead of working in TypeScript, you may continue to do so, but we strongly encourage you to migrate to TypeScript.

Developers should use, in order of preference:

• TypeScript and NPM

• JavaScript and NPM

• JavaScript in web browser

Once you have familiarized yourself with the code, see the information below on how to build and include a token for the channel you wish to view.

In Web SDK 1.0, tokens were optional, and were only needed to restrict access to channels, rooms, or streams. Web SDK 2.0 relies completely on edge tokens to support actions such as joining channels or rooms and subscribing to streams.

You can base64-decode the token (minus the prefix; that is, everything after DIGEST) to check the UNIX timestamp, channelId, and other information contained within the token, which includes:

• applicationId: The applicationId that generated the token

• digest: The cryptographic signature portion of the token

• token: The section of the token that specifies the items for which it provides access

  • uri: The base URI of the token

  • expires: The expiration of the token, based on the current Unix epoch, in milliseconds

  • requiredTag: Information such as the channelId of the channel to which this token provides access, e.g., channelId:us-central#phenixrts.com#phenixWebsiteDemo.sEhRandomFW7

For example, this channel name can be seen in the token by using a base64 decode of the token eyJhcHBsaWNhdGlvbklkIjoiZGVtbyIsImRpZ2VzdCI6Ing1WURkOWxEOS9acmNQSERrTG1RZHVJc3FoNWZscE52bVRFaHZBS0xkSzlnTnk5VHYxeURpbjNaT2s5QVptcVpxajdCU0VQZXZ4UzhzNUpDZEZ6RWJ3PT0iLCJ0b2tlbiI6IntcImV4cGlyZXNcIjoxOTMwMDc2NjI2NjYwLFwicmVxdWlyZWRUYWdcIjpcImNoYW5uZWxJZDp1cy1jZW50cmFsI3BoZW5peHJ0cy5jb20jcGhlbml4V2Vic2l0ZURlbW8uc0VoUmFuZG9tRlc3XCJ9In0=

to:{"applicationId":"demo","digest":"x5YDd9lD9/ZrcPHDkLmQduIsqh5flpNvmTEhvAKLdK9gNy9Tv1yDin3ZOk9AZmqZqj7BSEPevxS8s5JCdFzEbw==","token":"{"expires":1930076626660,"requiredTag":"channelId:us-central#phenixrts.com#phenixWebsiteDemo.sEhRandomFW7"}"}

If you have access to the Phenix Customer Portal, you can use the Decode Token page to see the contents of a token.

For more details on tokens, see Edge Token Usage.

The new Web SDK 2.0 centers around using EdgeAuth Tokens which contain usage details. This removes the need for a variety of details currently supplied via JavaScript, such as:

• features

• channelAlias, channelId

• backendUri

• adminApiProxyClient

• channelExpressOptions

• joinChannelOptions

Any code setting these values must be deprecated, as setting these values may cause failures in your application.

A typical workflow is as follows:

• Client-Side JS/TypeScript

  • Web SDK v2 with the <video> tag

  • Embedded player

• Server side REST/HTTPS APIs

• Handshake to negotiate RTC session

• Bitrate control

• Termination of stream

In the pseudocode below, "edgeToken" represents how the token is stored and transmitted to Phenix.

 
let token = edgeToken;
let videoElement = document.getElementById(‘video’);
let channel = phenix.Channels.createChannel({
    videoElement,
    token,
    telemetry: Off|Essential|All,
    consoleLogs: Off|Debug|Info|Warn|Error
});

To improve the page load to first frame (and as part of it time to first frame), the example client code initiates discovery of the closest healthy data center while the SDK loads before the client accesses the programmatic API.

The logs will include details about the discovery process. If you prefer to avoid that then you can set the meta tag.

<meta name="phenix-console-logging-level" value="Off"/>

Detecting the state using Web SDK v2 is similar to Web SDK v1. There is an RX observable that you can list for updates to the state and act accordingly:

channel.state.subscribe(state => const stateName = phenix.ChannelState[state])

phenix.ChannelState[state] will map to a string such as "Error", "Playing", or "Unauthorized".

Current channel states are listed below. Be sure to reference the string, not the enum value as that is subject to change if the list is re-ordered in a future update.

• Offline

• Starting

• Paused

• Playing

• Recovering

• StandBy

• Stopped

• Unauthorized

• GeoRestricted

• GeoBlocked

• Error

Use channel.state.subscribe for detecting Phenix playback failure.

ChannelState values that should cause a client to fall back to HLS:

• Fallback immediately on

  • Offline

  • Stopped

  • Unauthorized

  • GeoRestricted

  • GeoBlocked

• Fallback on Error when failureCount > 3 This can be achieved by evaluating the failure count whenever the state changes to Error (we expose the failure count). On each retry the state changes to Starting.

All errors are retried and some may resolve after one retry (we have a fallback strategy). It may take two to three retries if the channel is HA, and it can fall over to another stream as well.

This page provides details about error management and logging.

See the How to set up measurement of timing information article for details on measuring performance.