No results found

Try a different or more specific query
Developer Console

Step 9: Sign Your App and Configure a Security Profile (VSK Fire TV)

This page will lead you through the process to sign your app and create your API key to authorize it.

Sample App Notes

Even if you're just exploring the sample app, you still need to perform all the steps 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 default debug key by default.

However, this default debug key provided by Android Studio won't be accepted by Fire TV for projects that incorporate the VSK, and your app won't run. Even during local development of an app (sideloading onto Fire TV), you must sign your APK with a signature whose MD5 and SHA-256 values are associated with an Amazon security profile. The security profile will provide you with an API key that you incorporate into your app.

Follow the steps below to customize the debug signing key in Android Studio in order to properly sign your app for Fire TV.

Create a Key to Sign Your App

For a pre-release or "debug" version of your app, you must create an API key and store it in your project. To add the API key to your app:

  1. Create a file called api_key.txt located inside your project's assets folder. Placing the file in this specific directory is required.
  2. Insert your API key as the only data in this api_key.txt file.

For a release or "production" version of your app, if your app uses the Appstore SDK, you must create an additional API key for the release version of your app. If using the older IAP SDK v2.0 and you sign your app using your own certificate, you must also create an API key for the release version of your app. In contrast, if using the IAP SDK v2.0 and you allow Amazon to sign your app on your behalf, you do not need to create an additional API key. For a summary, see the following table.

You can find your AppStore certificate hash values in the Developer Console to create the API keys for existing apps. Go to My apps > select your app > App Information > Appstore Certificate Hashes.

Here's a quick reference for how you should sign your app:

Uses Appstore SDK Self-signs release app Production or development version How to sign your app
prod The API key is automatically generated and injected for release apps, no need to do anything else.
prod Developer must create API key using their own release certificate hashes and add it to assets.
prod Developer must create API key using release certificate hashes from Developer Console and add it to assets
prod Developer must create API key using their own release certificate hashes and add it to assets.
any any development Developer must create API key using their own release certificate hashes and add it to assets.

Keys for signing your app are stored in a keystore. For Android apps, usually 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: Automatically Sign App with Key.
  2. Assuming you don't have a custom debug key, open Android Studio and 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. Fill out at least one of the fields in the Certificate form. When finished, click OK.
  5. Make a note of your keystore location, keystore password, key alias, and key password, as you will need this information in the next section.

    Creating signing keys
    Creating signing keys

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

  6. Close the dialog box without proceeding through the other wizard screens to generate the APK. Continue on to the next step.

Automatically Sign Your App with the Custom Key

In the previous section (Create a Key to Sign Your App), you created a custom key to sign your app. In this step, you will update the key that your debug profile uses in Android Studio. To customize the signing key used with your debug profile:

  1. Open your Fire TV app project in Android Studio and go to File > Project Structure.
  2. Click Modules on the left.
  3. Click the Signing Configs tab at the top.
  4. Click the + button and create a new config called firetv.
  5. Configure your new firetv signing configuration by selecting the Store File, Store Password, Key Alias, and Key Password based on the information noted from the previous section (Create a Key to Sign Your App).

    Configuring signing keys
    Configuring signing keys
  6. Click Apply and then OK to close the dialog box. Gradle syncs your project with the updated signing information.
  7. In the left pane, expand Gradle Scripts and double-click your build.gradle (Module: app) file.
  8. Verify that an object called signingConfigs appears with details about your firetv signing config profile. For example:

     android {
         signingConfigs {
             firetv {
                 storeFile file('/Users/johndoe/android_signature/androidkeys.jks')
                 storePassword var
                 keyAlias = 'myandroidkeys'
                 keyPassword var
             }
         }
         ...
       }
       ...
     }
    

    The buildTypes property should also specify to use the firetv signing key for both release and debug builds. If these are commented out in the sample app, uncomment them.

     buildTypes {
         release {
             minifyEnabled false
             proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
             signingConfig signingConfigs.firetv
         }
         debug {
             signingConfig signingConfigs.firetv
         }
     }
    

    Now your builds will be signed with an API key that will match the API key used in your Amazon developer security profile (which you will create in an upcoming step). Fire TV will then allow the app to be installed on a Fire TV device.

    For more information about signing your app, see Configure the build process to automatically sign your app in the Android documentation.

    You can vary from the above process for signing your app as long as you keep the general principle in mind here — when you develop and run your app on Fire TV, sign your app with a key that isn't your default Android Studio debug key but rather is a key associated with a security profile on Amazon. (You'll associate this key with a security profile in an upcoming section.)

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). You can get these values from the Gradle menu in Android Studio by doing the following:

  1. In Android Studio, click the Gradle side pane on the right and expand it.
  2. Expand [app name] > Tasks > android.
  3. Double click signingReport.

    Signing Report in Android Studio
    Signing Report in Android Studio

    Gradle reads from your keystore and shows the MD5 and SHA-256 values in a bottom pane.

    Signing keys
    Signing keys shown through Android Studio
  4. Only the MD5 and SHA-256 values are needed. Copy these MD5 and SHA-256 values into a convenient location, as you will need them to create a security profile.

Create an Amazon Developer Account

If you don't yet have an Amazon developer account, create an account at developer.amazon.com by clicking Sign In in the upper-right corner and then click Create your Amazon Developer account. If this is your first time, you will need to complete some informational fields. See Create a Developer Account for more details.

Create a Security Profile

A security profile associates your security credentials with your app. You'll create this security profile in the developer portal and include the MD5 and SHA-256 values in the profile's configuration. This will create an authorization between your app and the security profile. To create the security profile:

  1. Sign in to https://developer.amazon.com and click Developer Console. This takes you into the Appstore Developer Console.
  2. Click Settings and then click Security Profiles from the second row of subtabs.
  3. Click the Create a New Security Profile button (in the lower-right corner).
  4. In the Security Profile Name field, give your security profile a friendly name (such as your app's name). Also type a description as desired in the Security Profile 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 customized package name of your Android project. In Android Studio, find your manifest in app > manifests > AndroidManifest.XML and look for the package name near the top. For example: com.example.vskfiretv.mystreamz
    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:91:39:C3:E8:C6:45:AC:6A:CE:B2:5B. You extracted this value in a previous section, 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 in the previous section, 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 and save it in a convenient location.

    API Key Details
    API Key Details
  10. Close the API Key Details window.

Add Your API Key into Your Fire TV Project

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 Alexa. 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. (If you don't have an assets folder with this file in your app, create the folder and file.) Placing the file in this specific directory is required.
  3. Insert your API key as the only data in this api_key.txt file.
Sample App Notes

This api_key.txt file is already present in the sample app. Press Shift twice and type the file name to quickly locate it. Replace <INSERT YOUR API KEY HERE> with your API key.

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 necessary, sign in to https://developer.amazon.com and do one of the following:

    • If you're working with an existing app, go to Apps & Services > My Apps. Then select your app.
    • If you're creating a new test app for the sample app, click Add New App > Android. Complete the required fields (title, category, etc.) on the New App Submission screen, and then click Save.
  2. In the column of subtabs on the left, click the App Services tab.
  3. In the Security Profile section, expand the Select existing security profile or create new link.
  4. 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.

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

Generate a Signed APK for the Developer Console

You need to generate a signed APK and upload it into the Developer Console so that you can submit your app into Live App Testing (LAT) in a later step. The APK you generate must be a release APK rather than a debug APK. To generate a signed APK from Android Studio:

  1. In Android Studio, generate a signed release APK by going to Build and then selecting Generate Signed Bundle / APK. Select APK, and then click Next. (Do not generate a debug APK, as it will not be accepted by the Developer Console.)
  2. Select the same signing key you configured earlier. Then click Next.
  3. Select the desired Destination Folder (this is where Android Studio will generate the built APK). Select the release build (note that Appstore will reject debug builds). 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

    If this window disappears, you can find the info by clicking the Event Log tab in the lower-right corner. The location within your project is app/release and the file's default name is app-release.apk.

Upload Your APK into the Developer Console

Now that you generated a signed release APK, upload it into the Developer Console. To upload your APK:

  1. If necessary, sign in to the Developer Console and go to the Dashboard.
  2. Go to Apps & Services > My Apps.
  3. Click the Add New App button 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 App Information in the app submission process.)

    App Title field
  5. Click Save.
  6. Click the App Information tab. (If the fields aren't already editable, click Edit in the lower-right corner.)
  7. Drag the APK from the destination folder over to the Drop APK here box and complete the other required fields.

    For more details about this tab, see Add App Information.

  8. On the Other Information tab, select a checkbox in Language Support (for example, English), and select the Export Compliance checkbox.

    For more details about this tab, see Add Other Information. You can fill out the details later as you follow the Getting Started with App Submission guide. For now, you must have an app to attach the security profile to. The security profile requires a package name.

  9. Click Save.

    You'll be prompted with a message that says, "You have targeted 'Amazon Fire TV Devices' for your APK(s), but have not added mandatory Fire TV assets. Please provide required assets under Images & Multimedia tab." The Appstore is reading your manifest and seeing that your app is a Fire TV app. In the next step, you'll complete the missing information.

Complete All the App Submission Tabs

Before you can submit your app into Live App Testing (an upcoming step), you need to complete all the required information on the app submission tabs. However, you should not submit your app into the Appstore at this time. To complete the tabs:

  1. Go through each tab and provide required information as needed. See Submitting Apps to the Amazon Appstore for details on all the fields.

  2. When each tab has been completed, a green check mark appears for the tab. Make sure each tab has a green check mark.

Submit Your App to Live App Test (LAT) (New Apps Only)

Although you don't need to submit the app into the Appstore, if you have a new app, or if you're working with the sample app, you do need to submit the app into Live App Testing (LAT) so that Amazon's backend can map the package name to your catalog. By putting your app into LAT, Amazon's backend can perform this essential processing. (Although you indicated your partner ID in the catalogs property in the RemoteVideoPlayer Supported Capabilities, Amazon actually gets your app's catalog through a mapping of your app title and ASIN. But it can't perform the mapping unless you put your app into either a LAT or prod environment.)

To start a LAT for your app:

  1. In the Developer Console, go to Apps & Services > My Apps and click your app.
  2. In the left sidebar, click Live App Testing.
  3. Click New Test, and then click OK to confirm that you want to create a new test.

    The Appstore redirects you to the view of your app's tabs. This would allow you to adjust the version of your app that you're submitting into LAT. However, you don't need to make any adjustments here.

  4. In the lower-right corner, click Go to Dashboard to return to the LAT Dashboard.
  5. In the Actions column, click the vertical dots and then click Submit. In the Submit confirmation dialog, click OK.

    There's no need to add testers for this LAT, since the LAT submission is purely so that Amazon's backend systems can map your catalog to your package. You will not be using the LAT version of the app and can ignore any LAT emails.

Next Steps

Go to the next step: Step 10: Test Utterances and Observe Logs.


Last updated: Jun 09, 2022