HTML5 SDK¶

Connecting¶

The following parameters are needed for a successful integration with PolyNet SDK:

channelId: Optional identifier for the channel. Must be a String.
apiKey: Api Key provided by System73. Contact us in order to obtain it.

Life cycle¶

Once the System73 SDK Service has been initialized following the instructions for your specific player (check instructions here) our SDK will override internal player methods used for video content requests.

Info

Once you attach our SDK to the player, it cannot be reverted. In order to do a full cleanup, you will need to create a new player instance.

HTTP Authorization & CORS [Optional]¶

Sometimes, players access content that requires credentials such as: cookies, authorization headers, TLS client certificates, etc..., and also need to support browsers that restrict cross-domain HTTP requests (CORS).

Players usually let you set a flag (for example, withCredentials), to enable cross-domain access with credentials.

The SDK gets the setting from the player. However, it might not be possible in all cases.

Tip

To avoid video not playing due to CORS-related errors, you can explicitly set withCredentials in the SDK (matching whichever you set in the player).

polyNetConfig: {
    apiKey: '<YOUR_API_KEY>', // mandatory
    channelId: '<CHANNEL_ID>', // optional
    withCredentials: true // optional
}

Handling events [Optional]¶

onMetrics¶

In order to receive metrics from System73 SDK, you should create onMetrics function:

/**
 * @param {Object} polyNetMetricsObject
 */
function onMetrics(polyNetMetricsObject) {
    // Handle polyNetMetricsObject
    console.log(polyNetMetricsObject)
}

polyNetConfig: {
    apiKey: '<YOUR_API_KEY>', // mandatory
    channelId: '<CHANNEL_ID>', // optional
    onMetrics: onMetrics
}

System73 SDK metrics¶

An object generated from an SDK with the following information:

Name	Type	Description
accumulatedCdnDownThroughput	Number	The amount of data as payload received from the CDN since the session started. (Kilobits).
accumulatedP2pDownThroughput	Number	The amount of data as payload received from P2P since the session started. (Kilobits).
bitrate	String	The bitrate of the currently played representation. (Bits per second).
bufferFillingRate	Number	The rate at which the content is received versus playing time.
cdnDownThroughput	Number	The amount of data as payload received from the CDN during the last reporting period. (Kilobits).
connectionStatus	String	Describes the current connection status of the client.
date	Date	The timestamp on which the metrics object was created.
deviceId	String	Unique identifier for the device running the PolyNet SDK.
downSpeed	Number	The last computed download speed (Kilobits).
inboundNodeId	String	Unique identifier for the inbound connection if connected to other peer or the value “POI” if downloading from CDN.
isConnected	Boolean	A Boolean that identifies if the client is connected to PolyNet.
nodeId	String	Unique identifier for the PolyNet node.
outboundMetrics	Array	Metrics for outbound peers. See outbound metrics below.
p2pDownThroughput	Number	The amount of data as payload received from P2P during the last reporting period. (Kilobits).
playerBufferHealth	Number	The amount of time (playback time) that are left for playing in the player's video read-ahead buffer. (milliseconds).
playerTimeToFirstFrame	Number	The amount of time from the start of the PolyNet SDK until the player starts playback. (milliseconds).
representationId	String	Unique identifier for the current representation or rendition being displayed.
roundTripTime	Number	The amount of time between sending a data packet from a child node to its inbound P2P peer and back. (Milliseconds).
sessionId	String	Unique identifier for the device session running the PolyNet SDK.
source	String	The source specifies where the content is downloaded from.
streamId	String	Unique identifier for the current stream being displayed.
streamUri	String	Identifies the URI of the stream.

Outbound metrics¶

Name	Type	Description
bufferFillingRate	Number	The rate at which the content is received in the PolyNet outbound peer versus playing time.
nodeId	String	Unique identifier for the PolyNet outbound peer.
status	String	The status of the connection for the PolyNet outbound peer.

The error method will be called when System73 SDK raises an error. Nevertheless, our service will keep working as reliably as possible. This method is useful when debugging the integration process.

The metrics method will be called periodically to deliver metrics from System73 SDK.

Multi-feature capabilities [Optional]¶

You can control System73 SDK's logic on a feature-by-feature basis using its instance.

Object	Function	Description
wrapper	enable/disable	Enable or disable PolyNet. When you disable PolyNet, you will also disable all other functionalities.
wrapper.p2p	enable/disable	Enable or disable the P2P.
wrapper.metrics	enable/disable	Enable or disable the metrics. When you disable metrics, P2P will also be disabled.
wrapper.mss	enable/disable	Enable or disable Midstream Switching. It will only be enabled if it is configured in the `polyNetConfig`. You can see more details in the specifications of each player.

Other considerations [Optional]¶

When using the sharingContent property, you can control how your application will participate in System73 SDK's overlay. It has three possible values and they are:

NEVER: The video content will never be shared with other peers.
ONLY_ON_LAN: The video content will be shared only if connected via WIFI or ETHERNET. (Default)
ALWAYS: The video content will be shared with other peers.

polyNetConfig: {
    apiKey: '<YOUR_API_KEY>', // mandatory
    channelId: '<CHANNEL_ID>', // optional
    sharingContent: 'ONLY_ON_LAN' // default
}

Use Case

If you want to allow your users to opt in/out of P2P networking, you can set this property based on a control in your application.

Last update: 2022-07-13