PolyNet™ HTML5 SDK
Connecting
The following parameters are needed for a successful integration with PolyNet SDK:
- channelId: Optional identifier for the channel. Must be String.
- apiKey: Api Key provided by System73. Contact us in order to obtain it.
PolyNet life cycle
Once the PolyNet has been initialized following the instructions for your specific player (check instructions here) PolyNet will override internal player methods used for video content requests.
In order to dispose the PolyNet instance, you need to dispose the player instance instead. After this, you will not be able to use the previously created PolyNet instance.
HTTP Authorization & CORS [Optional]
Sometimes, players access content that requires some form of credentials (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.
Advice: 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]
onCreate
In order to receive know when the PolyNet is created you shall create onCreate function:
function onCreate() {
// Do something after PolyNet is Created
}
polyNetConfig: {
apiKey: '<YOUR_API_KEY>', // mandatory
channelId: '<CHANNEL_ID>', // optional
onCreate: onCreate
}
onMetrics
In order to receive metrics from the PolyNet you shall 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
}
PolyNet metrics
An object generated from PolyNet SDK with the following information:
Name | Type | Description |
---|---|---|
accumulatedCdnDownThroughput | String | The amount of data as payload received from the CDN since the session started. (Kilobits). |
accumulatedP2pDownThroughput | String | 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 | String | The rate at which the content is received versus playing time. |
cdnDownThroughput | String | 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 | String | 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 | String | The amount of data as payload received from P2P during the last reporting period. (Kilobits). |
playerBufferHealth | String | The amount of time (playback time) that are left for playing in the player's video read-ahead buffer. (milliseconds). |
playerTimeToFirstFrame | String | 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 | String | 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. |
upSpeed | String | The last computed upload speed. (Kilobits). |
Outbound metrics
Name | Type | Description |
---|---|---|
bufferFillingRate | String | 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 the PolyNet raises an error. Nevertheless, the PolyNet will keep working as reliably as possible. This method is useful in the debugging of the integration process.
The metrics method will be called periodically to deliver metrics of the PolyNet.
Other considerations [Optional]
Sharing content restriction
Using the sharingContent
property you can control how your application will participate in the PolyNet. Its possible values 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.