Android SDK¶
This document applies to our SDK version 3 for Android.
Usage¶
Imports¶
You will need to import classes from com.system73.polynet.android.sdk
and com.system73.polynet.android.sdk.core.metrics
packages. For example:
...
import com.system73.polynet.android.sdk.PolyNet;
...
Connecting¶
The following parameters are needed for a successful integration with our SDK:
Name | Type | Description |
---|---|---|
manifestUrl | Mandatory | The URL of the manifest video playlist. |
apiKey | Mandatory | Api Key provided by System73. Contact us in order to obtain it. |
context | Mandatory | Android Context of the Activity where the video player is shown. |
channelId | Optional | Custom identifier for the channel. |
playerBufferSize | Optional | The video player's buffer size in seconds, if you know it or can get it from the player. |
regex | Optional | A regular expression to mask user tokens in the media URLs |
Initialise an instance of Edge Intelligence SDK object and use its property localManifestUrl
to initialise the player.
try {
PolyNetConfiguration configuration = PolyNetConfiguration.builder()
.setManifestUrl(manifestUrl)
.setChannelId(channelId)
.setApiKey(apiKey)
.setBufferSize(playerBufferSize)
.setContext(context)
.build();
PolyNet polyNet = new PolyNet(configuration);
// Init the player with the local manifest URL.
//
// For example:
// initialisePlayer(polyNet.getLocalManifestUrl())
} catch {
// The SDK CANNOT be used as there was an initialisation issue.
// Init the player with the original manifest URL.
//
// For example:
// initialisePlayer(manifesUrl)
// Where manifestUrl is the original URL of the manifest.
}
Warning
Do not start the player with the original manifest URL unless the SDK object fails to init.
If any required parameter is missing, invalid, or there are other problems during initialisation, an exception of class PolyNetException
might be thrown. You should catch it, examine the error message, and check your integration. If problem persists, contact support at support@system73.com.
List of initialisation errors¶
This is the list of the possible initialisation errors that may be thrown. You can obtain the error code with the getCode()
method of class PolyNetException
.
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. |
Providing metrics¶
You MUST provide the SDK instance with some of the video player's metrics. To provide the required metrics to the SDK, you have 2 options, Plugin Integration or Manual Player Integration:
Plugin Integration (Recommended)¶
Using the plugin integration, you have to pass the player instance to the SDK. The SDK will take care of getting to the required metrics directly from the player.
If the player you are using is not listed in the supported players, use the Manual Player Integration
Supported players:
- ExoPlayer2
...
import com.google.android.exoplayer2.ExoPlayer;
...
// Pass your ExoPlayer instance to the SDK
polynet.setPlayer(new PolyNetExoPlayerWrapper(player));
- Media3 ExoPlayer
...
import androidx.media3.exoplayer.ExoPlayer;
...
// Pass your ExoPlayer instance to the SDK
polynet.setPlayer(new PolyNetExoPlayerMedia3Wrapper(player));
Important
If you are using a different version of the player than the one being used by the SDK, gradle by default will select the latest version. If you face any conflicts, try to solve them by upgrading your source code to use the latest version of the player. If not possible, use the Manual Player Integration instead.
Manual Player Integration¶
If you are not using one of the supported players mentioned above or if you would like to manually listen to the player metrics and pass each metric separately to the SDK, check the following instructions.
Handling events [Optional]¶
There are different events provided by the SDK that you could listen to. To start listening to the events you can add your listener and override only the methods you are interested in.
polyNet.setAnalyticsListener(new PolyNetAnalyticsListener() {
// ... methods you are interested in overridiing
});
Error event¶
When the SDK finds a run-time problem (such as the Internet could not be accessed, etc.), a corresponding PolyNetException
can be obtained from the onError()
method inside the polyNetAnalyticsListener
. Nevertheless, the SDK will keep working as reliably as possible. This method is useful in the debugging of the integration process.
For example in our Sample App using ExoPlayer 2, this source code is added in the PlayerActivity
class.
// ... rest of code
@Override
public void onError(PolyNet polyNet, PolyNetException e) {
Log.e(TAG, "Edge Intelligence SDK error", e);
}
// ... rest of code
You should print it to the logs, examine the error message, and check your integration. If the problem persists, contact support at support@system73.com.
List of run-time errors¶
This is the list of the possible run-time errors that may be thrown. You can obtain the error code with the getCode()
method of class PolyNetException
.
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 | Invalid or revoked CS endpoint. Detail: (...). If problem persists, contact support at support@system73.com. |
Metrics event¶
You can get some of Edge Intelligence SDK metrics from the onMetrics
method inside the polyNetAnalyticsListener
. For each reported metric, call the specific get
method of the PolyNetMetrics instance:
// ... rest of code
@Override
public void onMetrics(PolyNetMetrics polyNetMetrics) {
// Access metrics
}
// ... rest of code
The reported metrics are as following:
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). |
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 Edge Intelligence 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 Edge Intelligence. |
natType | String | The type of NAT. This depends on the device connection to Internet. |
nodeId | String | Unique identifier for the node when connected to the Edge Intelligence service. |
outboundMetrics | [PolynetOutboundMetrics] | Metrics for outbound peers. See below Outbound Metrics. |
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 SDK until the player starts playback. (milliseconds). |
p2pDownThroughput | String | The amount of data as payload received from P2P during the last reporting period. (Kilobits). |
primaryManifestUrl | String | HLS: This is the master playlist URL with .m3u or .m3u8 extensions. DASH: This is the manifest URL with .mpd extension. |
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). |
secondaryManifestUrl | String | HLS: This is the media playlist URL with .m3u or .m3u8 extensions. |
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. |
upSpeed | String | The last computed upload speed. (Kilobits). |
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. |
Disconnecting from Edge Intelligence Service¶
Listeners can be unsubscribed from the SDK instance as shown below.
To disconnect:
polyNet.dispose();
Warning
Once you destroy the SDK instance, you CANNOT use it again. If you want to connect to a new channel or the same channel, go back to the initialisation steps and create a new instance.
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:
- Access an instance of the PolyNetConfiguration object.
- Access the
setContentSteeringEndpoint
property of the PolyNetConfiguration object. - Set the value of
setContentSteeringEndpoint
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 configuration.setContentSteeringEndpoint("YOUR_CONTENT_STEERING_RESOURCE");
"YOUR_CONTENT_STEERING_RESOURCE"
with the actual valid resource URI you obtained from the ESP portal.
Multi-Features¶
Content Steering¶
To control content steering in your application, you can utilize the SDK object. To enable or disable content steering, follow these steps:
- Access an instance of the Edge Intelligence SDK object.
- Access the property named
enableContentSteering
of the SDK object. - Set the value of
enableContentSteering
totrue
to enable content steering orfalse
to disable it. By default, if you provide a content steering resource, content steering will be enabled. Therefore, if you don't explicitly set the property, content steering will be enabled.
polyNet.enableContentSteering(true);
Peer to Peer¶
To control the availability of peer-to-peer in your application, follow these steps:
- Access an instance of the Edge Intelligence SDK object.
- Access the
enableP2P
property of the SDK object. - Set the value of
enableP2P
totrue
to enable peer-to-peer orfalse
to disable it. By default, peer-to-peer is enabled, so if you don't explicitly modify the property, peer-to-peer functionality will remain enabled.
polyNet.enableP2P(true);
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 |
---|---|
polyNet.setCustomDimension1() | Set value of custom dimension string #1. |
polyNet.setCustomDimension2() | Set value of custom dimension string #2. |
polyNet.setCustomDimension3() | Set value of custom dimension string #3. |
To control the availability of custom dimension in your application, follow these steps:
- Access an instance of the Edge Intelligence SDK object.
- Access, for example, to the
setCustomDimension1
property of the SDK object. - Set the string value for this custom dimension.
polyNet.setCustomDimension1("String");
Other considerations [Optional]¶
Streams with encryption keys¶
The optional property manageEncryptionKeys
can be used to initialise the SDK instance. You may call the corresponding manageEncryptionKeys
method in the PolyNetConfiguration.Builder
to set or unset it:
PolyNetConfiguration configuration = PolyNetConfiguration.builder()
.setManifestUrl(manifestUrl)
.setChannelId(channelId)
// ... rest of code
.manageEncryptionKeys(false) // true by default
.build();
PolyNet polyNet = new PolyNet(configuration);
Setting or re-setting this property is relevant on some scenarios where the stream is encrypted:
-
when the media segments need to be decrypted, the player usually needs to retrieve specific Key files. With the
manageEncryptionKeys
property you can choose whether these Key files are handled by the SDK (true
) or by the player (false
). This is relevant depending on the authentication scheme required to access the license servers and Key files. -
When this property is set to
false
, Our SDK delegates to the player all requests related to Key files. This is useful when authentication is managed with cookies that need to be handled externally or before the initialisation of the player.
This property is set to true
by default on the PolyNetConfiguration
.
Sharing content¶
The optional property sharingContent
controls whether the SDK shares the video content with other peers. This property is used after initialising the SDK instance.
Accepts values from the SharingContent
enum which are the following:
Option | Description |
---|---|
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. |
ALWAYS | The video content will be shared with other peers whenever possible. |
This property is set to ONLY_ON_LAN
by default.
You will need to import the following class from com.system73.polynet.android.sdk
package.
import com.system73.polynet.android.sdk.SharingContent;
sharingContent
method to set or unset it. For example:
PolyNet polyNet = new PolyNet(configuration);
// ... rest of code
polyNet.sharingContent(SharingContent.ONLY_ON_LAN);
Using cookies containing authentication tokens¶
Some content providers implement authentication with cookies containing the access tokens. Properly handling those cookies is necessary to grant access to the content.
To support content streams with cookies, the SDK instance needs access to an Android CookieHandler
. Video players (like ExoPlayer) should be able to access one, in order to properly handle cookies themselves. You should share the same CookieHandler
instance between the video player and the SDK instance. If you don't explicitly provide the SDK with a CookieHandler
, it will try to access the system-wide default CookieHandler
instead.
The method to set the cookie handler is setCookieHandler
in PolyNetConfiguration.Builder
.
This section was last updated 2024-10-07