The current release of WebSDK 2.0 is focused on supporting the viewing of channel content, especially for streamlining support of viewing HA content.

Migration from WebSDK 1.0

Remove Redundant Details

The new WebSDK 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.

Remove Client-Side High Availability (HA) Logic

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

WebSDK 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.

HTML Updates

It may be necessary to update to your HTML to reference the new JavaScript at https://dl.phenixrts.com/JsSDK/.

TypeScript

WebSDK 2.0 takes advantage of TypeScript to support efficient app development and maintenance. Install the Phenix Web SDK from https://www.npmjs.com/package/@phenixrts/sdk 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.

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.

Tokens

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

In WebSDK 1.0, tokens were optional. In WebSDK 2.0, they are at the heart of the service.

You will notice that the WebSDK 2.0 sample JSFiddle, among others, uses a static token in the JavaScript to subscribe to the desired channel. The JavaScript code does not include details such as channel alias, as all of that information is in the token.

You can base64-decode the token (minus the prefix; that is, everything after DIGEST) to check the UNIX timestamp, channelAlias, 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, e.g., https://demo.phenixrts.com/pcast

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

  • requiredTag: Information such as the channelAlias of the channel to which this token provides access, e.g., channelAlias:phenixWebsiteDemo

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

to:{"applicationId":"demo","digest":"x5YDd9lD9/ZrcPHDkLmQduIsqh5flpNvmTEhvAKLdK9gNy9Tv1yDin3ZOk9AZmqZqj7BSEPevxS8s5JCdFzEbw==","token":"{"expires":1930076626660,"requiredTag":"channelAlias:phenixWebsiteDemo"}"}

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

For more details on tokens, see https://phenixrts.atlassian.net/wiki/spaces/CKB/pages/499744810.

APIs

• Client-Side JS/TypeScript

  • WebSDK v2 with <video>

  • Embedded player

• Server side REST/HTTPS APIs

• Handshake to negotiate RTC session

• Bitrate control

• Termination of stream

Client-Side API

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

Initialization

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"/>

Channel States

Detecting the state using WebSDKv2 is similar to WebSDKv1. 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.

Error Management and Logging

Details about error management, and logging can be found at this page.

Measuring performance

See the https://phenixrts.atlassian.net/wiki/spaces/CKB/pages/549814283 article for details on measuring performance.

Example

An example in JSFiddle can be found here.