DRM Sample App

This sample app shows you how to incorporate DRM license checking with the code described in DRM Overview. Exploring the sample app can give you a better sense of how to incorporate DRM in context. The sample app can run on either Fire TV or Fire tablets.

Step 1: Use the necessary assets
Step 2: Add the Appstore SDK JAR to the sample app
Step 3: Add the PEM file into your project's assets
Step 4: Connect to your Fire device through ADB
Step 5: Install Amazon App Tester on your Fire device
Step 6: Enter sandbox mode
Step 7: Run your app
Understanding the sample app

Step 1: Use the necessary assets

First, gather all the necessary assets for your project. Download and unzip the following:

DRM Sample App - Part of the Appstore SDK
Appstore SDK - See SDK Downloads
Amazon App Tester (on your Fire device) - Download the App Tester from here

You also need a AppstoreAuthenticationKey.pem file, but you can download this during Step 3 of the tutorial.

Additionally, you will need the following:

Android Studio
Fire TV or Fire tablet device

Step 2: Add the Appstore SDK JAR to the sample app

The Appstore SDK JAR isn't automatically bundled into the DRM sample app you are about to create. (Otherwise, the sample app would become outdated with each new release of the Appstore SDK). To add the SDK JAR into the sample app:

Open Android Studio and select Open an existing Android Studio project.
Browse to the SampleDRMApplication folder and select it. Then click Open.
Change to the Project view.

Project view

Note: All instructions in this tutorial assume that you're in Android's Project view.
Copy the amazon-appstore-sdk-[x].jar file.
In the Android Studio project, expand app and select libs. Paste the amazon-appstore-sdk-[x].jar file into this directory.
Expand the app folder and open the build.gradle file. Customize the dependency on the amazon-appstore-sdk-[x].jar file you added. For example, if the Appstore SDK is version 3.0.3, your code would look as follows:
```
dependencies {
    implementation files('libs/amazon-appstore-sdk-3.0.3.jar')
}
```
Build the project by going to Build > Rebuild Project.

It may take Android Studio a few minutes to build the project, as Gradle gets needed assets and builds the project. If Android Studio needs any specific files or libraries, you'll be prompted to download them. After installing any needed assets, Android Studio will rebuild the project.

Step 3: Add the PEM file into your project's assets

To add the PEM file to the sample app:

Log into the Developer Console with your developer account.
If you already have an app, go to Apps & Services > My Apps. Then click your app. If you don't already have an app, see Submitting Apps to the Amazon Appstore.
Create a new version of your app. In the area below your app's name, click Upcoming Version.

Important: The link to the public key appears only when you create a new version or when you create a new app. If you had a new version in progress prior to the release of the Appstore SDK, you must complete your existing version and then create a new version — then the public key link will appear. Alternatively, for this tutorial you can just create a new Android app.
Go to the Upload Your App File screen.
In the Additional information section, click View public key.
In the Public Key dialog box that appears, click the AppstoreAuthenticationKey.pem link to download the PEM file. This file contains your public key.

PEM file download link
Copy the AppstoreAuthenticationKey.pem file and paste it into the app/src/main/assets folder of your Android Studio project.

Step 4: Connect to your Fire device through ADB

Connect your computer to either a Fire TV or Fire tablet through ADB. (The sample app runs on either Fire TV or Fire tablets.) See one of the following for details:

Important: Make sure ADB is included in your PATH. You can check by typing adb version in a terminal or command prompt. If ADB is unrecognized, see Step C. Add Android Debug Bridge to Your Path.

In the sample app, note that the AndroidManifest.xml file (inside app > src > main), has the following feature defined:

<uses-feature
android:name="android.hardware.touchscreen"
android:required="false" />

Setting the touchscreen property to false to support Fire TV. Without this, Fire TV devices won't support your app.

Step 5: Install Amazon App Tester on your Fire device

When you're developing your app with DRM or IAP (both of which need to communicate with the Appstore), you test your app using an APK called Amazon App Tester. The Amazon App Tester app simulates the Amazon Appstore client. To set up Amazon App Tester:

If you already have a previous version of Amazon App Tester installed, first uninstall it. (Note that this app is different from Web App Tester.)
In your terminal or command prompt, browse to the directory where you downloaded the Amazon App Tester APK.
Install the APK on your Fire device using ADB:
```
adb install -r amazon-app-tester.apk
```
The -r parameter reinstalls the APK in case you already have App Tester installed.
Open the Amazon App Tester app on your Fire device. To locate the installed app, see the following:
- Fire tablets: Click the Games & Apps menu and then click Library. Next to Amazon App Tester, click Open. (If you don't see the app, check the Updates tab as well.)
- Fire TV: Go to Settings and click Applications. Click Manage Installed Applications. Click Amazon App Tester, and then select Launch application.
Click the Appstore SDK API's banner.
Click DRM API Response Settings.

If you don't see this DRM API Response Settings option, you aren't using the latest version of Amazon App Tester.
Select the license status you want for the app. If you leave it at the "Default," the LICENSED status will be used.

DRM API Response Settings in App Tester

Important: For Appstore SDK integrated apps, the App Tester is compatible with the debug versions of your app, but incompatible with release versions of your app.

Step 6: Enter sandbox mode

Sandbox mode constrains calls that would normally go to the Appstore client to route to the Amazon App Tester app instead. Use this mode only for testing locally.

In the same terminal where you connected to your Fire device through ADB, enter sandbox mode:
```
adb shell setprop debug.amazon.sandboxmode debug
```
(Note that if you need to exit sandbox mode, run the following: adb shell setprop debug.amazon.sandboxmode none.)

Every time you reconnect to your Fire device through ADB, you need to reinitiate sandbox mode.

Step 7: Run your app

In Android Studio, click the Logcat tab and filter on LicenseResponse.
Click the Run App button to run the app on your Fire device.

The sample app has a basic screen showing the license status and nothing more. A LICENSED license status looks as follows:

DRM sample app homescreen

A NOT_LICENSED response looks as follows:

License failure
You can also observe the messages logged to the console for the license status.

Logcat filtered on LicenseResponse

If you look in the app/src/java/com/amazon/sample/drm/ folder and open the LicenseVerificationCallback Java file, you'll see the logic for how the app handles the license verification. More details are provided in the next section.

Understanding the sample app

The purpose of the sample app is to demonstrate how to integrate DRM. In the sample app, the onCreate() method in the MainActivity class (app/src/main/java/com/amazon/sample/drm/MainActivity.java) initiates the verifyLicense() method from the LicensingService class.

protected void onCreate(final Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setupApplicationSpecificOnCreate();
    LicensingService.verifyLicense(getApplicationContext(), new LicenseVerificationCallback(this));
}

The verifyLicense() method passes in two parameters: the application context (getApplicationContext()) and an implementation of LicenseVerificationCallback (new LicenseVerificationCallback(getApplicationContext())).

You can see the implementation of LicenseVerificationCallback in the LicenseVerificationCallback.java class:

public class LicenseVerificationCallback implements com.amazon.device.drm.LicensingListener {
...
}

The LicenseVerificationCallback calls the onLicenseCommandResponse() method to get the license status:

public class LicenseVerificationCallback implements com.amazon.device.drm.LicensingListener {

       public void onLicenseCommandResponse(final LicenseResponse licenseResponse) {

          final LicenseResponse.RequestStatus status = licenseResponse.getRequestStatus();
          ...
       }
}

This onLicenseCommandResponse() method is called by the Appstore SDK after receiving the result of the verifyLicense() call from Amazon Appstore.

In this simple implementation, the app just logs the license status rather than triggering any kind of action:

public void onLicenseCommandResponse(final LicenseResponse licenseResponse) {
    final LicenseResponse.RequestStatus status = licenseResponse.getRequestStatus();
    switch (status) {
        case LICENSED:
            Log.d(TAG, "LicenseResponse status: " + status);
            break;
        case NOT_LICENSED:
            Log.d(TAG, "LicenseResponse status: " + status);
        case EXPIRED:
            Log.d(TAG, "LicenseResponse status: " + status);
            LicensingPromptHelper.showLicenseFailurePrompt(context, LicenseVerificationPromptContent.DEEP_LINK);
            break;
        case ERROR_VERIFICATION:
            Log.d(TAG, "LicenseResponse status: " + status);
        case ERROR_INVALID_LICENSING_KEYS:
            Log.d(TAG, "LicenseResponse status: " + status);
        case UNKNOWN_ERROR:
            Log.d(TAG, "LicenseResponse status: " + status);
            LicensingPromptHelper.showLicenseFailurePrompt(context, LicenseVerificationPromptContent.SHUT_DOWN);
    }
  }

The response about the license status will contain one of the following statuses:

LICENSED
NOT_LICENSED
EXPIRED
ERROR_VERIFICATION
ERROR_INVALID_LICENSING_KEYS
UNKNOWN_ERROR

In Logcat, after running the app on your Fire TV, filter on the word LicenseResponse and observe what gets logged. The license responses will allow you to check that users are authorized to run the app.

For descriptions about each license status, see License statuses.

Last updated: Oct 02, 2023