Skip to main content

Generic

Player metricsAd trackingCustom player

The guide shows how to integrate yourself your own player with SmartLib in order to calculate metrics or handle ad tracking. Before starting, you need to have done the Session handling guide.

At this point, you should have initialized the lib, created a streaming session object and have integrated the session lifecycle into your app.

Following code samples use the actual player's API, you will need to adapt some part of the code you implemented in the previous step:

  • attach the player: create and attach the player instance
  • start a streaming session: get the final streaming URL and pass it to the player
  • stop a streaming session: stop the streaming session and the playback in case of user action or player error event
Requirements

1. Implement a player API​

The session has to be attached with a GenericPlayerApi implementation. The GenericPlayerApi is an abstract class which makes available the calls described in the next points (getPlayerName, getVersion…).

2. Bind player events to the session​

The following methods have to be called by the player or application to notify the session that events have happened.

3. Handler player errors​

The player errors have to be listened and reported to the session:

  • All non-recoverable errors (decoding error, format error) have to be mapped to a Broadpeak status code.
  • A non-recoverable error means that the playback cannot be retrieved once it has been triggered.

The errors have to be mapped to a Broadpeak error code:

NameCodeDescription
BPSessionEndsNormally200The streaming session ended normally.
BPFormatNotSupportedError3001An error has occurred because the format is not supported by the player.
BPDecodingError3002An error has occurred during the decoding of the video content. This error can be triggered during video playback.
BPNetworkingError3003An error has occurred during the transmission/reception of data over the network.
BPAccessRightError3004An error has occurred because user does not have sufficient rights to display the video. This error is triggered when there is a problem to connect to the DRM server.
BPUnspecifiedError3005An unspecified error has occurred.
note
  • A decoding error that crash the player is a non-recoverable error.
  • A timeout error while downloading one chunk but the network is not really down is a recoverable error, it does not have to be reported to SmartLib.

4. Attach a player to the session​

When creating the player instance, attach it to the current session.

info

It has to be done before starting the session (before session.getURL(...)).

5. Start a streaming session​

The getURL method is used to get the actual streaming URL and start the streaming session. This method is also the starting point of the analytics calculation, for instance the startup time starts from this method.

The returned URL can be different for every video session. In case of using a Broadpeak CDN or a nanoCDN, it includes a unique token. It can be used only once per session object, once called the session is actually started.

When getURL returns an error, it means no streaming URL can be found. It has to trigger a specific behaviour on the application (error message, dialog...) and stopStreamingSession has to be called. Find more details about getURL errors on the session errors page.

It is recommended to perform this call on a different thread than the main thread, the method runs HTTP requests.

info

This method has to be called even for non-Broadpeak content URLs. In this case, the method will return the same URL.

6. Stop a streaming session​

The stopStreamingSession method must be called each time the session is stopped:

  • end users: when the playback is stopped by a user action
  • loading errors: when the streaming session cannot be started through the getURL method
  • player errors: when the player triggers a non-recoverable error during the playback (as a decoding error)
  • application or any others actions: when the app is killed

7. Full example​

info

The sample code does not implement an actual player API, it has to be adapted depending on your player API.

All related codes to a player is mandatory only if a player integration is required.