Getting Started with WebSDK 2.0
The current release of WebSDK 2.0 is focused on supporting the viewing of channel content, especially for streamlining support of viewing HA content.
If your use case includes publishing, Rooms, or messaging/chat, please use WebSDK 1.0 until further notice.
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 here.
TypeScript
WebSDK 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.
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.
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 ID, 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, 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 Debug Token page to see the contents of a token.
For more details on tokens, see Edge Token Usage.
APIs
Client-Side JS/TypeScript
WebSDK v2 with the
<video>
tagEmbedded 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.
1let token = edgeToken;2let videoElement = document.getElementById(‘video’);3let channel = phenix.Channels.createChannel({4 videoElement,5 token,6 telemetry: Off|Essential|All,7 consoleLogs: Off|Debug|Info|Warn|Error8});
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 WebSDK-2.0-Logging-and-Error-Handling.
Measuring performance
See the How to set up measurement of timing information article for details on measuring performance.
Example
An example in JSFiddle can be found here.