Ti ringraziamo per la visita. Questa pagina è per il momento disponibile solo in inglese.

Step 5: Sign Your App and Configure a Security Profile (VSK FTV)

For your production app, Amazon handles your APK signature based on your Amazon account. However, for testing an app that incorporates a video skill, you need to sign your APK and associate this signature with an Amazon security profile.

Sample App Instructions

Even if you're working with the sample Fire TV app, you must still complete all the tasks described in this topic.

About Signing Your App During Development

Your app's signature is a hash value that is applied to every Android app when it is built. When you run your app from Android Studio (as you're developing your app), Android automatically signs your app with a debug key by default (see Sign your debug build in the Android docs).

However, this default debug key provided by Android Studio won't be accepted by Fire TV for projects that include video skills, and your app won't run. Even during local development of an app with a video skill, you must sign your APK with a signature whose MD5 and SHA256 values are associated with an Amazon security profile. The security profile will provide you with an API key that you incorporate into your app to authorize the communication from Amazon Device Messaging.

In short, just running your app on a Fire TV with Android Studio's default debug signing key won't work. Follow the steps below to properly sign your app during development in a way that authorizes your app on Fire TV.

Note that in the production version of your app, if you use the Amazon Appstore to sign your app (the default), the API key is provided automatically. However, if you sign the release version of your app using your own certificate, you will need to create an additional API key for the release version of your app.

Step 5.1: Create a Key to Sign Your App

The first step is to create a key to sign your app. Keys for signing your app are stored in a keystore. Generally, for Android apps there is a debug keystore and a release keystore. To create a signing key:

  1. If you already have a custom debug key (not the default Android debug key) to sign your app, make sure you know the keystore location, keystore password, key alias, and key password. Then skip to the next section, Step 5.2: Automatically Sign App with Key.
  2. Assuming you don't have a custom debug key, in Android Studio, click Build in the top navigation and select Generate Signed Bundle / APK.
  3. In the "Generate Signed Bundle or APK" dialog box, select APK. Then click Next.
  4. Click Create new and define the fields for a new key. See Generate an upload key and keystore in the Android documentation for more details. Make a note of your keystore location, keystore password, key alias, and key password, as you will need this information in the next section. When finished, click Apply.

    Selecting keys to sign your app
    Selecting keys to sign your app
  5. Close the dialog box without generating the APK. Continue on to the next step.

For more information, see Generate a key and keystore in the Android documentation.

Step 5.2: Automatically Sign App with Key

In the previous step, you created a custom key to sign your app. In this step, you will update your project to automatically sign your APK with this key. To automate the signing of your app with a particular key:

  1. Open your Fire TV app project in Android Studio.
  2. Go to Build and select Edit Build Types. Then click Modules on the left.
  3. Click the Signing Configs tab at the top.
  4. Create a new signing config by clicking the plus sign + in the main pane, and then typing a name for the configuration, such as "video_skill".
  5. Configure your new signing configuration by selecting the Store File, Store Password, Key Alias, and Key Password based on the information noted from the previous section (Step 5.1: Create a Key to Sign Your App).

    Creating a new signing config
    Creating a new signing config
  6. Click Apply.
  7. Click the Default Config tab.
  8. In the Signing Config drop-down menu, select your signing profile (e.g., "$signingConfigs.video_skill").
  9. Click OK to close the dialog box.
  10. In the left pane, expand Gradle Scripts and double-click your build.gradle (Module: app) file. Verify that an object called signingConfigs appears with details about your signing config profile. For example:

     android {
       signingConfigs {
          video_skill {
              storeFile file('/Users/yourusername/android_signature/androidkeys.jks')
              storePassword 'yourstorepassword'
              keyAlias = 'myandroidkey'
              keyPassword 'yourkeypassword'
          }
        ...
       }
     }
    

    Additionally, because you selected a signing profile for the default configuration, you should see the signing config in the defaultConfig object:

     defaultConfig {
       ...
        signingConfig signingConfigs.video_skill
     }
    

    Now when you run your app from Android Studio, the key you specified will be used to sign your app. For more information about signing your app, see Configure the build process to automatically sign your app in the Android docs.

    You can vary from the above process for signing your app as long as you keep the general principle in mind here: As you develop and run your app on Fire TV, sign your app with a key that isn't your default Android Studio debug key, as this key must be associated with a security profile on Amazon.

Step 5.3: Get the MD5 and SHA-256 Values from Your Key

You need to get the MD5 and SHA-256 values from your signing key before you can generate an API key from an Amazon security profile (described in the next step). To do this, you will use the keytool utility (a key and certificate management tool that is part of Java) to extract the MD5 and SHA-256 values.

To extract the MD5 and SHA256 values from your signing key:

  1. Copy the following command into a text file:

    keytool -list -alias myandroidkey -keystore /Users/johndoe/androidkeys.jks -storepass mykeystorepassword -keypass mykeypassword -v
    
  2. Customize the parameters as follows:

    • Change myandroidkey to the alias for the key you're using to sign your app.
    • Change /Users/johndoe/androidkeys.jks to the path to the keystore.
    • Change mykeystorepassword to the key storage password.
    • Change mykeypassword to the key password.

    Customize these values with your own key information based on how you set up the key.

  3. Paste the customized keytool command into your Terminal or command-line and press Enter.

    The response will include the following "certificate fingerprints" (along with other information):

    Certificate fingerprints:
    	 MD5:  02:6C:8B:83:77:96:39:C8:E8:C6:45:AC:6A:CE:B2:5B
    	 SHA1: 45:40:AD:E1:0B:B2:AE:CC:CB:21:65:BD:5A:01:82:A8:07:29:73:D7
    	 SHA256: 12:8F:C1:5D:3D:E9:BD:00:E0:ED:77:B3:84:71:AB:8F:6E:7D:C0:9E:E5:FE:64:EF:8F:BD:DA:EF:77:1F:E8:5E
    ...
    

    Only the MD5 and SHA256 values are needed. Copy these MD5 and SHA256 values into a convenient location, as you will need them to create a security profile (described in the next step).

Step 5.4: Create a Security Profile

A security profile associates your security credentials with your app. To create a security profile:

  1. Sign in to https://developer.amazon.com and click Developer Console. This takes you into the Appstore Developer Console (as opposed to the Alexa Developer Console).
  2. Click Settings and then click Security Profiles from the second row of subtabs.
  3. Click Create a New Security Profile.
  4. In the Name field, give your security profile a friendly name (such as your app's name). Also type a description as desired in the Description field.

    Naming your security profile
    Naming your security profile
  5. Click Save.
  6. Click the Android/Kindle Settings tab.

    Configuring the Security Profile
    Configuring the Security Profile
  7. Complete the following fields:

    Field Description
    API Key Name This does not have to be the official name of your app. It simply identifies this particular Android app among the apps and websites registered to your security profile.
    Package This must match the package name of your Android project. In Android Studio, expand your app folder, expand manifests, and double-click AndroidManifest.XML Look for the package name near the top. For example: com.acme.sample.hawaiiapp
    MD5 Signature This signature is used to verify your application. The MD5 signature must be in the form of 16 hexadecimal pairs separated by colons. For example: 02:6C:8B:83:77:96:39:C8:E8:C6:45:AC:6A:CE:B2:5B

    You extracted this value from your signing key using keytool in the previous section, Step 5.3: Get the MD5 and SHA-256 Values from Your Key.
    SHA256 Signature This signature is used to verify your application. The SHA-256 signature must be in the form of 32 hexadecimal pairs separated by colons. For example: 12:8F:C1:5D:3D:E9:BD:00:E0:ED:77:B3:84:71:AB:8F:6E :7D:C0:9E:E5:FE:64:EF:8F:BD:DA:EF:77:1F:E8:5E

    You extracted this value from your signing key using keytool in the previous section, Step 5.3: Get the MD5 and SHA-256 Values from Your Key.
  8. Click Generate New Key.
  9. Under API Key, click Show and copy the API key. Save it in a convenient location, as you'll need to add it to your Fire TV project.

    API Key Details
    API Key Details
  10. Close the API Key Details window. Then click the Web Settings tab.
  11. Copy the Client ID and Client Secret into a convenient location. You will use the Client ID and Client Secret when you finalize your Lambda code in Step 6: Create and Deploy Lambda Package.

    Copying the client ID and client secret
    Copying the client secret and client ID

Step 5.5: Enable Login with Amazon for Your Security Profile

You need to enable Login with Amazon for your security profile:

  1. In the Developer Console, click Login with Amazon on the top navigation.
  2. On the Login with Amazon Console, select your security profile from the Select a Security Profile drop-down menu.

    Enable Login with Amazon for your security profile
    Enable Login with Amazon for your security profile
  3. Click the Confirm button.
  4. In the "Enter Consent Screen Information" dialog box, add a privacy URL and consent logo as desired, and then click Save. (If you're just testing, you can enter your website for the privacy URL for now.)

Step 5.6: Add Your API Key into Your Fire TV Project

In this step, you need to add the API key from your security profile into your Fire TV project. This will enable your app to receive messages from Amazon Device Messaging (ADM). To add the API key to your app:

  1. In Android Studio, open your Fire TV app project.
  2. Inside your project's assets folder, create a file called api_key.txt. Placing the file in this specific directory is required.
  3. Insert your API key as the only data in this api_key.txt file.

Step 5.7: Upload your APK into the Developer Console

If you haven't already uploaded your app to the Developer Console (even if not published), you will need to do so in order to associate your security profile with a specific app's package name.

Typically, most partners already have an app in the Developer Console. But if not, or if you're working with a sample app, you must upload this app into the Developer Console to activate the security profile (even just to enable local development).

First, generate a signed APK from Android Studio:

  1. In Android Studio, generated a signed APK by going to Build and then selecting Generate Signed Bundle / APK. Select APK, and then click Next.
  2. If Amazon is signing your app post-upload, then it doesn't matter which key you use to sign your app, since Amazon simply resigns your app after you upload it. If you are managing your own signature, select the appropriate key to sign your app. Then click Next.
  3. Select the desired Destination Folder (e.g., release). Select the V1 (Jar Signature) check box. Then click Finish.
  4. After Android Studio builds your project, it shows a small message window with a locate link to open the destination folder where your APK was built. Click locate and open your destination folder to easily access the APK.

    Locating your built APK
    Locating your built APK

Next, upload your APK to your app in the Developer Console:

  1. Sign in to the Developer Console and go to the Dashboard (click the Developer Console link in the upper-right corner).
  2. Click Apps & Services and then click My Apps.
  3. In the lower-right corner, click Add New App and then select Android.
  4. Give your app a name in the App title field and a category in the App category field. (More information about these fields is provided in Add General Information in the App Submission process.)
  5. Click Save.
  6. Click the APK Files tab, and then click Edit in the lower-right corner if the fields aren't already editable.
  7. Drag the APK from the destination folder (where you generated it) over to the Drop APK here box in the APK Files tab in the Developer Console.

    More information about the APK Files tab is available in Upload APK Files. If desired, select a language for your app and add other details. You can do all of this later as per the documentation in Getting Started with App Submission. For now, you just need to have an app to attach the security profile to. The security profile requires a package name.

  8. Click Save.

Step 5.8: Attach the Security Profile to Your App

You need to attach the security profile to your app. This will allow your app to be authorized on Fire TV. To attach the security profile to your app:

  1. If you're not already viewing your app in the Develper Console, sign in to https://developer.amazon.com and click Apps & Services and then select My Apps. Then select your app.
  2. In the first row of subtabs below your app's name, click the App Services tab.

    Selecting App Services
    Selecting App Services
  3. In the Security Profile section, expand the Select existing security profile or create new link. Then in the Security Profile drop-down that appears, select the security profile you created earlier and click Enable Security Profile.

    Selecting the security profile for your app
    Selecting the security profile for your app

    You will see a confirmation message that says, Security profile "{Name}" has been successfully enabled for your app with details about the attached security profile.

  4. In the Device Messaging section, click the Enable Device Messaging button.

    Enable Device Messaging
    Enable Device Messaging
  5. This same security profile will be shown as attached for the Login with Amazon sections as well. If for some reason you're prompted to enable it for Login with Amazon as well, do so.

    Note that once you attach a security profile to an app, you cannot remove or change the security profile's attachment to the app.

Step 5.9: Connect to Fire TV Through adb

Now that you've configured the security profile, you're ready to run your app on Fire TV to make sure everything works and is authorized. See Connect to Fire TV Through adb for full details on running your app on Fire TV. The abbreviated version is as follows:

  1. On your Fire TV, go My Fire TV > Developer Options. Enable ADB Debugging and Apps from Unknown Sources.
  2. On Fire TV, go to Settings, and then browse to My Fire TV > About > Network. (Some Fire TV models might say "Device" instead of "My Fire TV.") Make a note of the IP address listed on this screen.
  3. Open up a terminal window and run the following:

    adb connect <ipaddress>:<port>
    

    For example:

    adb connect 10.49.172.51:5555
    

    If you run into connection issues, see the more detailed documentation for Connecting to Fire TV Through adb.

  4. After successfully connecting to Fire TV, open Android Studio and run your app by clicking the Run App button Run 'app' .
  5. Choose the connected Fire TV device and click OK.

    Selecting the target Fire TV device
    Selecting the target Fire TV device
  6. Verify that your app runs. Open Logcat in Android Studio to monitor the log messages. If it runs, then you know that you have configured the security profile correctly.

    If you encounter issues related to fingerprints, see Troubleshooting.

Troubleshooting

This section lists common errors and ways to fix them. If you run your app on Fire TV and open Logcat in Android Studio, you can see the reasons why apps fail to install or run on Fire TV. You might need to filter on Error to more easily see these messages.

Error: Fingerprint checking:<obscured> W/com.amazon.identity.auth.device.appid. APIKeyDecoder: Failed to decode: Decoding failed: certificate fingerprint can't be verified!

The app fails due to the fingerprint certifications in the security profile. Make sure your security profile is associated with your app's package name based on the instructions in the above sections.

Error: com.amazon.identity.auth.device.appid.APIKeyDecoder: Unable to decode APIKey for pkg=com.some.package.name

The app fails due to the API key in the security profile. Make sure your security profile is associated with your app based on the instructions in the above sections.

Error: java.lang.IllegalArgumentException: Invalid API Key

The API key might be valid, but Android Studio might not be signing your app with the right signing configuration.

Next Steps

Continue on to the next step: Step 6: Create and Deploy Lambda Package.