HTML5 SDK¶
Connecting¶
The following parameters are needed for a successful integration with Edge Intelligence 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).
var s73Config = {
apiKey: '<YOUR_API_KEY>', // mandatory
channelId: '<CHANNEL_ID>', // optional
withCredentials: true // optional
};
List of run-time and initialisation errors¶
This is the list of the possible run-time and initialisation errors that may be shown in the browsers's console.
| Code | Description |
|---|---|
| -600 | Check your API Key. If problem persists, contact support at support@system73.com. |
| -601 | Check your API Key. If problem persists, contact support at support@system73.com. |
| -602 | Check your API Key. Detail: (...). If problem persists, contact support at support@system73.com. |
| -603 | The PolyNet SDK has failed to build. Detail: (...). If problem persists, contact support at support@system73.com. |
| Code | Description |
|---|---|
| -700 | The PolyNet SDK has failed and raised an exception. Detail: (...). If problem persists, contact support at support@system73.com. |
| -701 | The PolyNet SDK is not compatible with the tracker provided. Tracker code: (...). This may happen in transitions to newer versions. If problem persists, contact support at support@system73.com. |
| -702 | Error communicating with tracker. Detail: (...). If problem persists, contact support at support@system73.com. |
| -703 | Error communicating with tracker metrics endpoint. Detail: (...). If problem persists, contact support at support@system73.com. |
| -704 | The Api Key is revoked from PolyNet server. Please, contact support at support@system73.com. |
| -705 | PolyNet connection rejected. Detail: (...). If problem persists, contact support at support@system73.com. |
| -706 | The content steering API Key is revoked. Please, contact support at support@system73.com |
Handling events [Optional]¶
onMetrics¶
In order to receive metrics from System73 SDK, you should create onMetrics function:
/**
* @param {Object} s73MetricsObject
*/
function onMetrics(s73MetricsObject) {
// Handle metrics object
console.log(s73MetricsObject)
}
var s73Config = {
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 Edge Intelligence 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 Edge Intelligence. |
| nodeId | String | Unique identifier for the node when connected to the Edge Intelligence service. |
| 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 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 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 Edge Intelligence outbound peer versus playing time. |
| nodeId | String | Unique identifier for the Edge Intelligence outbound peer. |
| status | String | The status of the connection for the Edge Intelligence 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.
Content Steering¶
To access the optional content steering feature, you'll need to set a valid content steering resource in your SDK. You can obtain the resource URI from the ESP (Edge Services Platform). To accomplish this, follow these steps:
- Create a SDK configuration object.
- Set the value of the
contentSteeringEndpointfield in the configuration object to the valid resource obtained from the ESP portal. By setting the content steering resource, you enable the content steering feature in your application.Remember to replace// Pass your content steering resource to the SDK var s73Config = { apiKey: '<YOUR_API_KEY>', // mandatory channelId: '<CHANNEL_ID>', // optional sharingContent: 'ONLY_ON_LAN', // default contentSteeringEndpoint: '<YOUR_CONTENT_STEERING_RESOURCE>' // content steering resource };'<YOUR_CONTENT_STEERING_RESOURCE>'with the actual valid resource URI you obtained from the ESP portal.
Multi-feature capabilities [Optional]¶
You can control System73 Edge Intelligence SDK's logic on a feature-by-feature basis using its instance.
| Function | Description |
|---|---|
| wrapper.enable() | Enable all Edge Intelligence features at once. |
| wrapper.disable() | Disable all Edge Intelligence features at once. |
| wrapper.p2p.enable() | Enable just the P2P functionality. |
| wrapper.p2p.disable() | Disable just the P2P functionality. |
| wrapper.contentSteering.enable() | Enable just Content Steering. Note that it will only be really enabled if properly configured in the configuration object (s73Config below). You can see more details in the snippet section of each player. |
| wrapper.contentSteering.disable() | Disable just Content Steering. |
Extra custom dimensions [Optional]¶
Using custom dimensions, the System73 Edge Intelligence SDK allows you to report extra data that is not defined in the existing set of metrics.
At the moment, the SDK supports 3 extra custom dimensions. Each custom dimension is a String value, which you can populate with any custom data or metadata suited to your needs. Note this String value is limited to max. 256 characters, and will be trimmed down to this length.
| Function | Description |
|---|---|
| wrapper.dimensions.setCustomDimension1(value) | Set value of custom dimension string #1. |
| wrapper.dimensions.setCustomDimension2(value) | Set value of custom dimension string #2. |
| wrapper.dimensions.setCustomDimension3(value) | Set value of custom dimension string #3. |
Other considerations [Optional]¶
Sharing content restriction¶
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.
var s73Config = {
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.
This section was last updated 2024-11-29