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

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.

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 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 to authorize the communication from Amazon Device Messaging.

Warning: If you sign your app with the default debug signing key that Android Studio uses, your app won't run when you run it on your Fire TV. You'll see an error that says "Invalid API Key" in Logcat in Android Studio.

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:

Create a file called api_key.txt located inside your project's assets folder. Placing the file in this specific directory is required.
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 > Upload Your App File > 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.

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:

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.
If you don't alreday have a custom debug key, in Android Studio, click Build in the top navigation and select Generate Signed Bundle / APK.
In the "Generate Signed Bundle or APK" dialog box, select APK. Then click Next.
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.
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

For more information, see Generate a key and keystore in the Android documentation.
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 step (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:

Open your Fire TV app project in Android Studio.
Go to File > Project Structure.
Click Modules on the left.
Click the Signing Configs tab at the top.
Click the + button and create a new config called firetv.
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

Tip: When you choose the Store Password and Key Password, Android lets you store this information as a variable ($var). Storing passwords as variables is recommended. Otherwise, your passwords will be present in the build.gradle (Module: app) file, making any Git checkin problematic. When you store these values as a variable, the storePassword and keyPassword values in the build.gradle file are displayed as var.
Click Apply and then OK to close the dialog box. Gradle syncs your project with the updated signing information.
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 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 — Create a Security Profile). Fire TV will then authorize the app to install.

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 — 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 easily get these values from the Gradle menu in Android Studio by doing the following:

In Android Studio, click the Gradle side pane on the right and expand it.
Expand app > Tasks > android.
Double click signingReport.

Signing Report in Android Studio

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

Signing keys shown through Android Studio
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 (described in the next step).

You can also use the keytool utility (a key and certificate management tool that is part of Java) to extract the MD5 and SHA-256 values. Expand the button below for details.

Keytool utility method

To extract the MD5 and SHA-256 values from your signing key using the Java keytool utility:

Copy the following command into a text file:

Mac:

/Library/Java/JavaVirtualMachines/jdk1.8.0_231.jdk/Contents/Home/bin/keytool -v -list -alias myandroidkeys -keystore /Users/johndoe/android_signature/androidkeys.jks -storepass somepassword -keypass somepassword

Windows:

"C:\Program Files\Java\jdk1.8.0_231.jdk\bin\keytool" -v -list -alias myandroidkey -keystore "C:\Users\johndoe\androidkeys.jks" -storepass italttby1J# -keypass italttby1J#

Customize the parameters as follows:
- Change the path to point to where your keytool utility is stored on your computer (or browse to where keytool is stored before running the command). The sample command assumes your keytool is located in a certain location that might not be the case on your computer.
- Change myandroidkey to the alias for the key you're using to sign your app.
- Change /Users/johndoe/androidkeys.jks or C:\Users\johndoe\androidkeys.jks to the path to the keystore.
- Change mykeystorepassword to your key storage password.
- Change mykeypassword to your key password.
Customize these values with your own key information based on how you set up the key.

If keytool is already added to your PATH, you might not need to specify the path before it. However, sometimes the MD5 value won't appear unless you supply the full path to keytool.
Paste the customized keytool command into your terminal or command prompt 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 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 (described in the next step).

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 and allow the Alexa Client Library to run.

To create the security profile:

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).
Click Settings and then click Security Profiles from the second row of subtabs.
Click the Create a New Security Profile button.
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
Click Save.
Click the Android/Kindle Settings tab.

Configuring the Security Profile

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.example.vskfiretv`
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 the 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.

Click Generate New Key.
Under API Key, click Show and copy the API key. Save it in the same file where you stored your video ID and other details.

API Key Details

Note: If different versions of your app have different signatures or package names, such as for one or more testing versions and a production version, each version will require its own API Key. From the Android/Kindle Settings of your app, click the Add an API Key button to create additional keys for your app (one per version).
Close the API Key Details window. Then click the Web Settings tab.
Copy the Client ID and Client Secret into your notes. You will use the Client ID and Client Secret when you finalize your Lambda code.

Copying the client secret and client ID

Enable Login with Amazon for Your Security Profile

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

In the Developer Console, click Login with Amazon on the top navigation.
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
Click the Confirm button.
In the Enter Consent Screen Information dialog box, add a Consent Privacy Notice URL URL and Consent Logo Image as desired, and then click Save. (If you're just testing, you can enter your website for the privacy URL for now.)

The logo is displayed on the signin and consent screens when the user logs into your website or mobile app. It should be a square logo, 150px x 150px in size, PNG format. If your logo is a different size, it will be scaled to fit.

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 Amazon Device Messaging (ADM). To add the API key to your app:

In Android Studio, open your Fire TV app project.
Inside your project's assets folder, create a file called api_key.txt. Placing the file in this specific directory is required.

Sample App

The sample app already has a file called api_key.txt. Press your spacebar twice and search for the file, and then remove its contents and paste in your API key.
Insert your API key as the only data in this api_key.txt file.

Important: ADM won't recognize your API key if it contains any spaces or line breaks.

Generate a Signed APK for the Developer Console

You need to generate your APK and upload it into the Developer Console so that you can associate your app with your security profile with a specific app's package name. To generate a signed APK from Android Studio:

In Android Studio, generate a signed APK by going to Build and then selecting Generate Signed Bundle / APK. Select APK, and then click Next.
Select the same signing key you configured earlier. Then click Next.
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.
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

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 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:

Sign in to the Developer Console and go to the Dashboard (click the Developer Console link in the upper-right corner).
Click Apps & Services and then click My Apps.
Click the Add New App button and then select Android.
Give your app a name in the App title field and a category in the App category field. For more information about these fields, see Step 1: Upload Your App File in the app submission process.
Click Save.
On the Upload Your App File screen, drag the APK from the destination folder (where you generated it) over to the Upload your app file box. Wait for the file to upload. Then, complete the other required fields.

For more details about this screen, see Step 1: Upload Your App File.
Select a checkbox in the Language Support section (for example, English).

The remaining details you'll complete 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.

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:

If you're not already viewing your app in the Developer Console, sign in to https://developer.amazon.com and click Apps & Services and then select My Apps. Then select your app.
In the column of subtabs on the left, click the App Services tab.
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

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.
In the Device Messaging section, click the Enable Device Messaging button.

Enable Device Messaging
This same security profile will be shown as attached for the Login with Amazon sections as well.

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

Next Steps

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

(If you run into any issues that prevent you from continuing, see Troubleshooting for Cloudside Integrations.)

Last updated: Oct 02, 2023