Customer-defined session and licence management

To test this feature and view the example code, please see the Android SDK 5 Example Code Quick Start guide.

The SDK provides the means for a client to define their own session management and licence management logic through two classes:

OTVCustomerSSMCallback - This class provides the abstract method getLicense() as the entry point for a custom implementation of session set-up, licence acquisition and licence renewal.
OTVSSMLicenseResponse - This is a data class consisting of a content license and the session's heartbeat in seconds. This is the return type of OTVCustomerSSMCallback#getLicense().

Setting up the callback

This implementation must maintain the session token (see mSessionToken) to manage the session and renew the content licence; it will be set when the session has been created. A content token must be passed to the SSM server to create the session; it must be passed to the callback before playing the content using setContentToken().

This could be a constructor argument instead, but providing a specific method enables the callback to be reused with more than one piece of content.

JAVA

public class CustomerSSMCallback extends OTVCustomerSSMCallback {

  private String mLicenseServerUrl;
  private String mSsmServerUrl;

  private String mContentToken = "";
  private String mSessionToken = "";

  public CustomerSSMCallback(@NonNull String licenseServerUrl, @NonNull String ssmUrl) {
    mLicenseServerUrl = licenseServerUrl;
    mSsmServerUrl = ssmUrl;
  }

  public final void setContentToken(@NonNull String contentToken) {
    mContentToken = contentToken;
  }

Setting up the session, acquiring and renewing the licence

OTVCustomerSSMCallback#getLicense() receives the UUID string of the content key system (e.g. Widevine or PlayReady), the payload to be passed to the SSM or license server, and the licence type. The licenseType string will be one of the following:

"license-request" - A new session must be created, and a licence for the content must be retrieved.
"license-renewal" - A new content licence must be retrieved for the existing session.

JAVA

  @Override
  public OTVSSMLicenseResponse getLicense(@NonNull String keySystem, @NonNull byte[] payload, @NonNull String licenseType) {
    OTVSSMLicenseResponse response = null;
    if (licenseType.equals("license-request")) {
      APIGateway.Response gatewayResponse = APIGateway.getLicense(mLicenseServerUrl, mSsmServerUrl, UUID.fromString(keySystem), payload,
          mContentToken);
      mSessionToken = gatewayResponse.getSessionToken();
      response = new OTVSSMLicenseResponse(gatewayResponse.getLicense(), gatewayResponse.getHeartbeat());
    } else if (licenseType.equals("license-renewal")) {
      APIGateway.Response gatewayResponse = APIGateway.renewLicense(mSsmServerUrl, payload, mSessionToken);
      mSessionToken = gatewayResponse.getSessionToken();
      response = new OTVSSMLicenseResponse(gatewayResponse.getLicense(), 0);
    }
    return response;
  }

Session teardown

This step is optional as the session will expire after the number of seconds specified in the heartbeat in the OTVSSMLicenseResponse. However, it may be desirable to proactively remove sessions that are no longer required so that the server does not leave them open longer than necessary. Calling reset() will reset the internal state of the OTVCustomerSSMCallback and ensure that getLicense() is next called with a licenceType value of "license-request". This will enable the callback to start a new session.

JAVA

  public void tearDown() {
    reset();
    Thread tearDownThread = new Thread() {
      @Override
      public void run() {
        APIGateway.tearDownSession(mSsmServerUrl, mSessionToken);
      }
    };
    tearDownThread.start();
  }
}