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

Step 3: Integrate the Alexa Client Library (VSK FTV)

In this step, you will take the video skill you created and make it interact with your Fire TV app. 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

If you're working with the sample Fire TV app, the sample app already has the Alexa Client Library integrated. Skip down to Sample App: Viewing the Alexa Client Library section below for details on configuring the video skill ID.

Capabilities Provided by the Alexa Client Library

This Alexa Client Library allows you to do the following:

  • Authenticate with Amazon using Login with Amazon (LWA) for Android.
  • Automatically pair 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).
  • Manage application lifecycle events and send those events back to Alexa (which will help Alexa make more intelligent decisions when users interact with voice-enabled Fire TV apps).
  • Send Alexa responses to directives received in your application.

Prerequisites

It will help to have some familiarity with Node.js and NPM, though expertise in this area is not required at this stage. Just make sure that you have at Node.js version 8.1 or later. You can check if Node and NPM are already installed by typing node -v and npm -v.

For more information about the expected Alexa directives your app should handle, see Step 7: Interpreting and Reacting to Directives.

Step 3.1: Add the Alexa Client Library to your Fire TV App

If you are using Gradle with Android Studio, you can integrate Alexa Video Skill Client Library using the Android Archive (AAR) file contained in the released SDK. To add the Alexa Video Skill Client Library (AlexaClientLib.aar) into your project in Android Studio, do the following:

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

Step 3.2: Configure Proguard

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

  1. Locate your proguard rules file.
  2. 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.** { *; }
    

Step 3.3: Initialize the Alexa Client Library

The Alexa Client Library must be initialized for the client library to work correctly. To initialize the library:

  1. 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();
         }
    
    
        public static void initializeAlexaClientLibrary(Activity mainActivity) {
            // Retrieve the shared instance of the AlexaClientManager
            AlexaClientManager clientManager = AlexaClientManager.getSharedInstance();
    
            // Gather your Skill ID and list of capabilities
            final String alexaSkillId = "YOUR_SKILL_ID";
    
            // Create a list of supported capabilities in your skill.
            List<String> capabilities = new ArrayList<>();
            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);
    
            clientManager.initialize(mainActivity,
                alexaSkillId,
                AlexaClientManager.SKILL_STAGE_DEVELOPMENT,
                capabilities);
        }
    }
    

    Note that 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);
    

    If your app doesn't support these capabilities, omit these lines. Alexa will send directives related to these capabilities. For example, if you indicate CAPABILITY_CHANNEL_CONTROLLER, Alexa will send ChangeChannel directives when users say "Change the channel to PBS." For more detail, see the Discover Directives.

  2. In previous code, replace YOUR_SKILL_ID with your own Skill ID (which you copied during Step 1.1: Begin Creating a Video Skill.

Step 3.4: Initialize 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 below. The down-channel is a stream primarily used to deliver cloud-initiated directives to your Fire TV app. This service uses Amazon Device Messaging, which you will integrate more fully in Step 4: Integrate Amazon Device Messaging (ADM).

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 ADM service (initializeAdm();) at application creation time as shown below.

The following code shows a sample ADM reference implementation:

public class YourApplication extends Application {

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

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

      // Initialize ADM.
      initializeAdm();
    }

    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(TAG, "ADM registration Id:" + admRegistrationId);

              // Provide the acquired ADM registration ID.
              final AlexaClientManager alexaClientManager = AlexaClientManager.getSharedInstance();
              alexaClientManager.setDownChannelReady(true, admRegistrationId);
           }
         }
       } catch (Exception ex) {
          Log.e(TAG, "ADM initialization is failed with exception", ex);
      }
   }
}

Step 3.5: Enable/Disable Alexa Targeting for the App when user signs in/out

The function setAlexaEnabled() is used to enable or disable an app instance as a targetable endpoint by the user. Do the following:

  • Call setAlexaEnabled(true) when the user logs into your app
  • Call setAlexaEnabled(false) when the user logs out.
// User is logged in with active subscription
AlexaClientManager.getSharedInstance().setAlexaEnabled(true);

// User is logged out or does not have a valid subscription
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.

Sample App: Viewing the Alexa Client Library

The sample app configures all of the above steps for integrating the Alexa Client Library, so you aren't required to do any coding here. However, you do need to configure the your video skill ID. To configure your video skill ID in the sample app:

  1. Press Shift twice and search for TenFootApp.java.
  2. Customize the value for ALEXA_SKILL_ID with your own video skill ID. For example:

    private static final String ALEXA_SKILL_ID = "amzn1.ask.skill.544641fd-b4b3-40ab-a9f6-c9757bda68b6";
    

    You're done. You can explore the sample app's integration a bit more, or continue on to the next step in the integration process.

Explore the Sample App Integration:

To see some of the above code with initializing the Alexa Client Library, ADM, and the down channel service in the sample app, do the following:

  • Double-click the AlexaClientLib module name. Android Studio opens up the Project Structure dialog box with the Modules tab selected. Click the Dependencies tab and you will see the AlexaClientLib listed.
  • Press Shift twice and search for proguard to view the proguard-rules.pro file (inside AMZNMediaPlayerComponent).
  • Press Shift twice and search for TenFootApp.java (inside TVUIComponent). This code shows the initialization of the Alexa Client Library with initializeAlexaClientLibrary().
  • In the same TenFootApp.java file, look for the initialization of ADM with initializeAdm().

Next Steps

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