Step 3: Integrate the Alexa Client Library (VSK Fire TV)

To integrate Alexa into your app, you will need to integrate the Alexa Client Library. The Alexa Client Library allows your application to communicate with Alexa and handle Video Skill API directives intended for your application.

Sample App Instructions

The sample app already has the Alexa Client Library version 1.4.6 integrated. (The Project pane shows an "AlexaClientLib" module.) If the Alexa Client Library has iterated to later versions, you can Update the Alexa Client Library in your Fire TV App. You can also browse the MainActivity.java and VSKFireTVMessageHandler.java files in the sample app to see the how the Alexa Client Library is integrated and initialized. Otherwise, proceed to the next step, Step 4: Integrate Amazon Device Messaging (ADM).

Download the Alexa Client Library
About the Alexa Client Library
Update the Alexa Client Library in your Fire TV App
Add the Alexa Client Library to your Fire TV App
Configure Proguard
Initialize the Alexa Client Library from Your App's onCreate
Next Steps

Download the Alexa Client Library

You can download the Alexa Client Library here:

Note that by downloading the Alexa Client Library, you agree to Amazon's Program Materials License Agreement.

For more details on versions, see the Alexa Client Library Release Notes.

About the Alexa Client Library

The Alexa Client Library allows you to do the following:

Authenticates with Amazon using Login with Amazon (LWA) for Android.
Automatically pairs your skill with an Echo device by inferring a relationship from an existing Echo to Fire TV (rather than requiring a customer to add the skill through the Alexa App).
Manages application lifecycle events and sends those events back to Alexa (which will help Alexa make more intelligent decisions when users interact with voice-enabled Fire TV apps).
Sends Alexa responses to directives received in your application.

For a Javadoc detailing the fields, methods, and implementation requirements for the Alexa Client Library, see Class AlexaClientManager.

Update the Alexa Client Library in your Fire TV App

To update an existing version of the Alexa Client Library in your Android Studio project:

Download the Alexa Client Library. After downloading the file, unzip it. The zip folder contains a file called AlexaClientLib.aar.
In Android Studio, right-click the AlexaClientLib module and select Reveal in Finder (Mac) or Show in Explorer (Windows).
Open the AlexaClientLib folder.
Drag in the new AlexaClientLib.aar file, replacing the existing one. When asked if you want to overwrite the file, choose "Replace."

Add the Alexa Client Library to your Fire TV App

To add the Alexa Client Library (AlexaClientLib.aar) into your Android Studio project, do the following:

Download the Alexa Client Library from the link above. After downloading the file, unzip it. The zip contains a file called AlexaClientLib.aar and some documentation.
In your Android Studio project, go to File > New > New Module.
Select Import .JAR/.AAR Package and click Next.
In the File name field, select the AlexaClientLib.aar file and click Open, and then click Finish.
Go to File > Project Structure.
Under Modules in the left menu, select app.
Go to Dependencies tab.
If you don't already see AlexaClientLib in the list of dependencies, click the + button in the bottom and select 3. Module dependency.
Select the AlexaClientLib from the list.

Configure Proguard

If you're using ProGuard in your Android project, make the following update:

Locate your proguard rules file.

Add the following configuration:

-libraryjars ../AlexaClientLib

# Keep the LWA and Alexa Client Library classes
-dontwarn com.amazon.identity.auth.device.**
-dontwarn com.amazon.alexa.vsk.clientlib.**

-keep class com.amazon.identity.auth.device.** { *; }
-keep class com.amazon.alexa.vsk.clientlib.** { *; }

Initialize the Alexa Client Library from Your App's onCreate

The Alexa Client Library must be initialized for the client library to work correctly. Declare initializeAlexaClientLibrary() in your Application class. Reference the code sample below. Make sure to call initializeAlexaClientLibrary() from onCreate().

public class YourApplication extends Application {

    @Override
    protected void onCreate() {
      super.onCreate();

      // Initialize the Alexa Client Library first
      initializeAlexaClientLibrary();

      // Initialize ADM
      initializeAdm();

      // (Optional) Enable the VSK client library so that VSK start auto-pairing in background
      // immediately which will enable your user use Voice service ASAP.
      // You can delay this step until active user signed-in to your application.
      AlexaClientManager.getSharedInstance().setAlexaEnabled(true);
    }

    private void initializeAlexaClient() {
        // Retrieve the shared instance of the AlexaClientManager
        AlexaClientManager clientManager = AlexaClientManager.getSharedInstance();

        // Gather your Skill ID
        final String alexaSkillId = "YOUR_SKILL_ID";

        // Create a list of supported capabilities in your skill
        List capabilities = new ArrayList<>();
        capabilities.add(AlexaClientManager.CAPABILITY_CHANNEL_CONTROLLER);
        capabilities.add(AlexaClientManager.CAPABILITY_PLAY_BACK_CONTROLLER);
        capabilities.add(AlexaClientManager.CAPABILITY_REMOTE_VIDEO_PLAYER);
        capabilities.add(AlexaClientManager.CAPABILITY_SEEK_CONTROLLER);

        // Initialize the client library by calling initialize()
        clientManager.initialize(getApplicationContext(),
                alexaSkillId,
                AlexaClientManager.SKILL_STAGE_DEVELOPMENT,
                capabilities);
    }

    private void initializeAdm() {
      try {
       final ADM adm = new ADM(this);
          if (adm.isSupported()) {
            if (adm.getRegistrationId() == null) {
              // ADM is not ready now. You have to start ADM registration by calling
              // startRegister() API. ADM will calls onRegister() API on your ADM
              // handler service when ADM registration was completed with registered ADM id.
              adm.startRegister();
            } else {
              // [IMPORTANT]
              // ADM down-channel is already available. This is a common case that your
              // application restarted. ADM manager on your Fire TV caches the previous
              // ADM registration info and provides it immediately when your application
              // is identified as restarted.

              // You have to provide the retrieved ADM registration Id to the Alexa Client library
              final String admRegistrationId = adm.getRegistrationId();
              Log.i("ADM registration Id:" + admRegistrationId);
              // Provide the acquired ADM registration ID
              AlexaClientManager.getSharedInstance().setDownChannelReady(true, admRegistrationId);
           }
         }
       } catch (Exception ex) {
          Log.e(TAG, "ADM initialization is failed with exception", ex);
      }
   }
}

General Notes

The skill stage is set to SKILL_STAGE_DEVELOPMENT. Later in the development process, when you're ready to publish your app (in Step 12: Go Live!), you will change AlexaClientManager.SKILL_STAGE_DEVELOPMENT to AlexaClientManager.SKILL_STAGE_LIVE.
If an event (for example, a visibility change, such as backgrounding/foregrounding the app) occurs before initialize is called, the app will not respond to voice until the app is force-stopped and restarted.

Declaring Capabilities

The sample code above declares support for these capabilities:

capabilities.add(AlexaClientManager.CAPABILITY_CHANNEL_CONTROLLER);
capabilities.add(AlexaClientManager.CAPABILITY_REMOTE_VIDEO_PLAYER);
capabilities.add(AlexaClientManager.CAPABILITY_PLAY_BACK_CONTROLLER);
capabilities.add(AlexaClientManager.CAPABILITY_SEEK_CONTROLLER);

Alexa will send directives related to these capabilities listed here. For example, if you indicate AlexaClientManager.CAPABILITY_CHANNEL_CONTROLLER, Alexa will send ChangeChannel directives when users say "Change the channel to PBS." If you don't have the capability declared, Alexa won't send directives related to the capability. For more detail, see the Discover Directives.

If your app doesn't support a particular capability, omit that capability from the above. Additionally, you can add AlexaClientManager.CAPABILITY_RECORD_CONTROLLER and AlexaClientManager.CAPABILITY_KEYPAD_CONTROLLER if your app supports the functionality of these APIs. The capabilities are described in the following table.

Alexa Client Library Capability	Directive Capability	Directives
`CAPABILITY_CHANNEL_CONTROLLER`	`Alexa.ChannelController`	`ChangeChannel`
`CAPABILITY_REMOTE_VIDEO_PLAYER`	`Alexa.RemoteVideoPlayer`	`SearchAndDisplayResults` `SearchAndPlay`
`CAPABILITY_PLAY_BACK_CONTROLLER`	`Alexa.PlaybackController`	`Pause` `Play` `Stop` `Resume` `Next` `Previous` `FastForward` `Rewind` `StartOver`
`CAPABILITY_SEEK_CONTROLLER`	`Alexa.SeekController`	`AdjustSeekPosition`
`CAPABILITY_KEYPAD_CONTROLLER`	`Alexa.KeypadController`	`SendKeystroke`

If you would like to declare a capability without a predefined constant (e.g., List<String> capabilities) in the client library, you can do so by using the exact string name of that capability. For example, you would add the "Launcher" capability for GUI shortcuts as follows: capabilities.add(\"Alexa.Launcher\");.

Note: In addition to setting the capabilities here in your app's code, you must also list the capabilities in your Lambda code, which you will configure at a later stage. When your Lambda receives a Discover directive, your Lambda must send a Discover.Response back to indicate which capabilities your skill supports. See the Example response in the Discover directive documentation.

Customize the Skill ID

In the previous code, replace YOUR_SKILL_ID with your own Video Skill ID, which you copied earlier in Step 1: Create a Video Skill and Set Up Devices.

final String alexaSkillId = "YOUR_SKILL_ID";

The function setAlexaEnabled() is used to enable or disable an app instance as a targetable endpoint by the user. It's recommended that you enable Alexa (setting setAlexaEnabled(true)) only for subscribed customers. (Hence the inline comment in the code that says you can delay this step until the active user signs in to your application.) Do the following:

Call setAlexaEnabled(true) when the user logs into your app
Call setAlexaEnabled(false) when the user logs out

Important: You can set setAlexaEnabled to false in response to direct user action, but not in response to automatic events, such as HDMI events. Do not call setAlexaEnabled(false) when your app goes to background, or when it terminates.

The following code shows an example:

public class YourSigninActivity extends Activity {
    private void onUserSignedIn() {
        // Enable the AlexaClient when user sign-in
        AlexaClientManager.getSharedInstance().setAlexaEnabled(true);
    }

    private void onUserSignedOut() {
        // Disable the Alexa Client when user signed-out
        AlexaClientManager.getSharedInstance().setAlexaEnabled(false);
    }
}

The only exception to this rule is if your app does not have a user login — in other words, your content is available to users regardless of whether they're logged in or have a particular subscription.

Construct a Down-Channel Service

To receive directives from the Alexa Service, you must construct a down-channel service in your app as per the sample reference code above. The down-channel is a stream primarily used to deliver cloud-initiated directives to your Fire TV app. Note the following about the down-channel service.

When your down-channel service is ready, call the setDownChannelReady() API with parameters as follows:

The first parameter (isDownChannelReady) should be true to indicate that your down-channel is ready.
The second parameter (appInstanceId) should be a string that uniquely identifies your application instance. If you are using Amazon Device Messaging (ADM), use the app's ADM Registration ID for this parameter. (If you prefer not to use ADM, you can use another technology.)

When your down-channel service status changes, call the setDownChannelReady() API each time with the proper status flag value.

Initialize the ADM service (initializeAdm();) at application creation time as shown below. The preceding code shows a sample ADM reference implementation.

Provide the application instance ID when your down channel is ready.

public class YourADMHandler extends ADMMessageHandlerBase {
     @Override
     protected void onRegistered(final String registrationId) {
         // [IMPORTANT]
         // ADM down channel is ready. Set the downchannel as ready with acquired ADM registration Id.
         AlexaClientManager.getSharedInstance().setDownChannelReady(true, registrationId);
     }
 }

Warning: Do not pass false during application initialization unless you are certain the current user does not have access to content. Toggling this state off and on will result in Alexa unregistering and re-registering the endpoint, which will have unintended consequences to your skill.

Next Steps

Continue on to the next step: Step 4: Integrate Amazon Device Messaging (ADM).

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

Last updated: Mar 16, 2022