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 license 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, license acquisition and license 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 enable it to manage the session and renew the content license; 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 have been a constructor argument instead, but providing a specific method enables the callback to be reused with more than one piece of content.

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;
  }

JAVA

Setting up the session, acquiring and renewing the license

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 license type. The licenseType string will be one of the following:

  • "license-request" - A new session must be created, and a license for the content must be retrieved
  • "license-renewal" - A new content licence must be retrieved for the existing session
  @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;
  }
JAVA

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.

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