Customize the Fire App Builder Sample Project

I: Get Set Up

STEP 1:
Download and Build Sample App

→

STEP 2:
Connect Through adb

→

STEP 3:
Take an App Tour

→

STEP 4:
Try the Alexa Integration

→

STEP 5:
Customize the Sample Project

The first step in creating your app is to customize the "Application" folder. The Application folder contains the sample app created with Fire App Builder.

Note: If you haven't downloaded and built the "Application" project, see this topic first: Download Fire App Builder and Build an App and then Run Fire App Builder on a Fire TV Device. This ensures that you have your build environment set up successfully before you continue.

Customize the Application
Clean and Build the Project
Next Steps

Customize the Application

Expand the Project pane (but not the Project view) in the upper-left corner to view the files. Make sure you're in the Android View. Unless specifically noted, this documentation will always refer to file locations using the Android View.
In the folders in the Project pane, expand app and then go to res > values > custom.xml. In the app_name string, type the name of your app. For example:
```
<string translatable="false" name="app_name">Write the Docs Podcast</string>
```
Note that the AndroidManifest.xml file (inside app > manifests) reads the name of the application from the string you just edited. (In Android Manifest, the code referencing the string is android:label="@string/app_name". This is how most of Fire App Builder is set up — code that you customize is extracted out into XML files so you don't have to directly edit Java.) The references don't need to point to a specific XML file because Android Studio will look in all XML files for the references. Any string in the app's custom.xml file will overwrite strings in the other XML files.

Note that the app_name and app_name_short strings have a translatable="false" property. The name of your app is not translated.

In res > values > strings folder, there are multiple strings.xml files to support different locales for your app. If someone from a German locale opens your app (assuming your app is available in that market), the "strings.xml (de)" file will be used. If someone from Japan opens your app, the "strings.xml (ja)" file will be used, and so on. If no language specific string is found, the app falls back on strings.xml.
In the app_name_short string, add an abbreviated name for your app that is no longer than 15 characters. (If you're app's name is already this short, then just use the same app name.)
```
 <string translatable="false" name="app_name_short">WTD Podcast</string>
```
The abbreviated app name is used with recommendations (this is an optional feature). The space on the Fire TV home screen (where recommendations appear) doesn't allow your app name to be longer than 15 characters.
Open your app's AndroidManifest.xml file (located in app > manifests) and update the package name com.fireappbuilder.android.calypso name to a package name that reflects your app's new name. For example, if your app was named "acmemedia," you might change it to the following:
```
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.fireappbuilder.android.acmemedia">
```
Warning: The package name for apps you submit to the Amazon Appstore must be unique and must not contain the string amazon. Using amazon in your package name creates conflicts when integrating with the Amazon Catalog. Additionally, your app's package name must remain the same through the life of your app. If you change the package name, the app will not retain any history or association with previously submitted apps. As per requirements with Android package names, the package name must start with letters.

The sample app in Fire App Builder doesn't have any classes in the com.fireappbuilder.android.acmemedia package, but you can add custom classes to overwrite existing Fire App Builder functionality or add to it.

In the Android View, expand the Gradle Scripts folder and open the build.gradle (Module: app) file. Update the applicationId property to match your package name. For example:

defaultConfig {
    applicationId "com.fireappbuilder.android.acmemedia"
    minSdkVersion 21
    targetSdkVersion 23
    versionCode 10
    versionName "1.0.7"
    testInstrumentationRunner "android.support.test.runner.AndroidJUnitRunner"
    multiDexEnabled true
}

Note: In this documentation, unless otherwise noted, paths to files are described using the Android view.

Here's an example:

In this same build.gradle (Module: app) file, note the versionCode and versionName. You can leave these values as is. However, if you submit an update to your application, you will need to increment the versions. Here's the difference between these two codes:
- The versionCode (an integer) is an internal numbering scheme for your app's version. Each APK you upload to the Appstore must have a uniquely incremented versionCode. The initial versionCode can be any number, but when you submit an update to your APK, you must increment the versionCode. See android:versionCode in the Android documentation for more details.
- The versionName (a string) is the version that users see. It doesn't have to match the versionCode and can be anything. See android:versionName in the Android documentation for more details.
Note that you do not need the versionCode and versionName elements in your app's manifest. When you upload your APK into the Amazon Appstore, the Appstore will read the information from both the "build.gradle (Module: app)" file instead of the AndroidManifest.xml.
Expand the Gradle Scripts folder and open the gradle.properties (Project Properties) file. Customize the applicationName to your app's name without using spaces. Android Studio uses this name in the APK filename (which you'll generate later when you create a signed APK to submit your app into the Appstore).
When you make changes to Gradle files, you're prompted to synchronize Gradle with your project. Click the Sync Now link in the upper-right corner.

Clean and Build the Project

Go to Build > Rebuild Project. This will clean up any artifacts from the previous app and then rebuild your project (and it can take a few minutes for this process to finish.
Build your new app by clicking the Run 'app' button .

If the app fails to build or install on your Fire TV, try running Build > Rebuild Project again. Also note that you can't have two apps with the same package name on Fire TV, so if you updated your package name to com.acme.media, but another app on your Fire TV already has this package name (perhaps the official app you've already published in the Appstore?), you'll need to uninstall the other app first (by going to Settings > Applications > Manage Installed Applications on your Fire TV) before you can sideload (through ADB) the app you're developing.

Next Steps

Now that you've built and customized the default app in Fire App Builder, it's time to load and configure your media feed. Go to Load Your Media Feed. This next series of steps follows II: Configure Your Feed map.

Last updated: Aug 22, 2017