DRM authentication before playback

When the DRM metadata for a video is separate from the media stream, perform authentication before beginning playback.

1. Use loadDRMMetadata to load the metadata URL content and parse the downloaded bytes to a DRMMetadata.

   Like any other network operation, this method is asynchronous, creating its own thread.

   public static void loadDRMMetadata(
       final DRMManager drmManager,
       final String drmMetadataUrl, 
       final DRMLoadMetadataListener loadMetadataListener); 

   For example:

   DRMHelper.loadDRMMetadata(drmManager, metadataURL, new DRMLoadMetadataListener());

2. Because the operation is asynchronous, it is a good idea to make the user aware of that. Otherwise, he'll wonder why his playback is not beginning. For example, show a spinner wheel while the DRM metadata is being downloaded and parsed.
3. Implement the callbacks in the DRMLoadMetadataListener. The loadDRMMetadata calls these event handlers (dispatches these events).

   public interface DRMLoadMetadataListener {
    public void onLoadMetadataUrlStart();
    /**
     * @param authNeeded
     *     whether DRM authentication is needed.
     * @param drmMetadata
     *     the parsed DRMMetadata obtained.    */
    public void onLoadMetadataUrlComplete(boolean authNeeded, DRMMetadata drmMetadata);
    public void onLoadMetadataUrlError();
   }

   • onLoadMetadataUrlStart detects when the metadata URL loading has begun.

   • onLoadMetadataUrlComplete detects when the metadata URL has finished loading.

   • onLoadMetadataUrlError indicates that the metadata failed to load.

4. When loading completes, inspect the DRMMetadata object to see whether DRM authentication is needed.

   public static boolean isAuthNeeded(DRMMetadata drmMetadata);

   For example:

   @Override
   public void onLoadMetadataUrlComplete(boolean authNeeded, DRMMetadata drmMetadata) { 
     Log.i(LOG_TAG + "#onLoadMetadataUrlComplete", 
                     "Loaded metadata URL contents. Auth needed:" + authNeeded + ".");
     if (!authNeeded) {
         // Auth is not required. Start player activity.    
         showLoadingSpinner(false);    
         startPlayerActivity(ASSET_URL);
         return;
     }

5. If authentication is not needed, begin playback.
6. If authentication is needed, perform the authentication by acquiring the license.

   /**
   * Helper method to perform DRM authentication.
   *
   * @param drmManager
   * the DRMManager, used to perform the authentication.
   * @param drmMetadata
   * the DRMMetadata, containing the DRM specific information.
   * @param authenticationListener
   * the listener, on which the user can be notified about the
   * authentication process status.
   */
   public static void performDrmAuthentication(
        final DRMManager drmManager, 
        final DRMMetadata drmMetadata,
        final String authUser, 
        final String authPass, 
        final DRMAuthenticationListener authenticationListener);

   This example, for simplicity, explicitly codes the user’s name and password.

   DRMHelper.performDrmAuthentication(drmManager, drmMetadata, DRM_USERNAME, DRM_PASSWORD, new
   DRMAuthenticationListener() {
    @Override
     public void onAuthenticationStart() {
         Log.i(LOG_TAG + "#onAuthenticationStart", "DRM authentication started.");
         // Spinner is already showing.
     }
     @Override
     public void onAuthenticationError(long majorCode, long minorCode, Exception e) { 
         Log.e(LOG_TAG + "#onAuthenticationError", 
             "DRM authentication failed. " + majorCode + " 0x" + Long.toHexString(minorCode));
          showToast(getString(R.string.drmAuthenticationError));  
        showLoadingSpinner(false);
     }
     @Override
     public void onAuthenticationComplete(byte[] authenticationToken) {
         Log.i(LOG_TAG + "#onAuthenticationComplete", "Auth successful. Launching content.");
         showLoadingSpinner(false);
         startPlayerActivity(ASSET_URL);
     }
   });

7. This also implies network communication, hence this is also an asynchronous operation. Use an event listener to check the authentication status.

   public interface DRMAuthenticationListener {
   /**
   *       Called to indicate that DRM authentication has started.
   */
   public void onAuthenticationStart();
   /**
   *       Called to indicate that DRM authentication has been successful.
   *
   * @param authenticationToken
   *       the obtained token, which can be stored locally.
   */
   public void onAuthenticationComplete(byte[] authenticationToken);
   /**
   *       Called to indicate that an error occurred while performing the DRM
   *       authentication.
   *
   * @param majorCode
   *       the major code.
   * @param minorCode
   *       the minor code.
   * @param e
   *       the exception thrown.
   */
   public void onAuthenticationError(long majorCode, long minorCode, Exception e);
   }

8. If authentication is successful, start playback.
9. If authentication is not successful, notify the user and do not start playback.

   Your application must handle any authentication errors. Failing to successfully authenticate before playing places the PSDK into an error state. That is, the PSDK changes its state to ERROR, an error is generated containing the error code from the DRM library, and the playback stops. Your application must resolve the issue, reset the player, and reload the resource.