AlexaClientManager (app API)

java.lang.Object
- com.amazon.alexa.vsk.clientlib.AlexaClientManager

public final class AlexaClientManager
extends java.lang.Object

AlexaClientManager provides a single entry to get provided services for hosting application.

VSK client library initialization is started by calling AlexaClientManager.initialize() from your Application creation code.

Library initialization code are recommended to be called from onCreate() of your Application.
All required setup will be automatically started and completed.

Reference the following sample code:

Initialize the VSK client library from your Application creation time.


  public class YourApplication extends Application {
      @Override
      protected void onCreate() {
          super.onCreate();

          // [IMPORTANT]
          // initialize the VSK client library.
          initializeAlexaClient();

          ...
      }

      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_LIVE,
                  capabilities);

         // (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.
         clientManager.setAlexaEnabled(true);
      }
  }

Enable or disable the VSK Client library when user signed in or out.


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

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

To receive directives from Alexa Service, you have to construct down-channel service.

When your down-channel service is ready, call setDownChannelReady() API with true as first parameter(isDownChannelReady), and unique string identifier used to identify your application instance universally as second parameter(applicationInstanceId). If you are using external services like ADM as your down-channel, you can use ADM registration ID as application instance id.
When your down-channel service status is changed, you have to call setDownChannelReady() API each time with proper status flag value.

Reference following ADM sample implementation:

Initialize ADM service at application creation time.


 public class YourApplication extends Application {
      @Override
      protected void onCreate() {
          super.onCreate();

          // initialize the VSK client library.
          // We recommend to initialize VSK client library before initialize ADM.
          initializeAlexaClient();

          // Initialize the ADM service.
          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 downchannel is already available. This is a common case that your
                      // application restarted. ADM manager on your FireTV cache the previous
                      // ADM registration info and provide it immediately when your application
                      // is identified as restarted.
                      //
                      // You have to provide the retrieved ADM registration Id to the AlexaClient library.
                      final String admRegistrationId = adm.getRegistrationId();
                      Log.i(TAG, "ADM registration Id:" + admRegistrationId);

                      // Set the downchannel as ready with 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);
          }
      }
  }

Provide 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.
          final AlexaClientManager alexaClientManager = AlexaClientManager.getSharedInstance();
          alexaClientManager.setDownChannelReady(true, registrationId);
      }
  }

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static interface`	`AlexaClientManager.AuthManager`
`static interface`	`AlexaClientManager.EventManager`
`static class`	`AlexaClientManager.EventType`

Field Summary

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`CAPABILITY_CHANNEL_CONTROLLER` Channel control capability.
`static java.lang.String`	`CAPABILITY_KEYPAD_CONTROLLER` Keypad controller capability;
`static java.lang.String`	`CAPABILITY_PLAY_BACK_CONTROLLER` Playback control capability.
`static java.lang.String`	`CAPABILITY_REMOTE_VIDEO_PLAYER` Remote video play capability.
`static java.lang.String`	`CAPABILITY_SEEK_CONTROLLER` Seek control capability.
`static java.lang.String`	`PREFERENCE_POST_EVENT_ALWAYS_FOR_TESTING` Control event posting logic for testing
`static java.lang.String`	`PREFERENCE_SKIP_DISCOVERY_EVENT_FOR_TESTING`
`static java.lang.String`	`PREFERENCE_SKIP_STATUSCHANGED_EVENT_FOR_TESTING`
`static java.lang.String`	`PREFERENCE_USE_LOCAL_TEST_SERVER` Use local test server for testing.
`static java.lang.String`	`PREFERENCE_USE_MILTIPART_BODY_PAYLOAD` Use multi-part payload for event data posting.
`static java.lang.String`	`SKILL_STAGE_CERTIFICATION` Certification skill stage that host application can select when initializing client library.
`static java.lang.String`	`SKILL_STAGE_DEVELOPMENT` Development skill stage that host application can select when initializing client library.
`static java.lang.String`	`SKILL_STAGE_LIVE` Live skill stage that host application can select when initializing client library.
`static java.lang.String`	`VSK_VERSION` VSK client library version number

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addCapabilities(org.json.JSONObject endpoint)`
`AlexaApiEndpointProvider`	`getAlexaApiEndpointProvider()`
`static java.lang.String`	`getAndroidId()`
`android.content.Context`	`getApplicationContext()`
`java.lang.String`	`getApplicationInstanceId()`
`AlexaClientManager.AuthManager`	`getAuthManager()`
`static java.lang.String`	`getCapabilitiesHashValue()`
`android.content.SharedPreferences`	`getClientLibrarySharedPrefernces()`
`static java.lang.String`	`getDsn()`
`AlexaClientManager.EventManager`	`getEventManager()`
`static java.lang.String`	`getPreferenceValue(java.lang.String key, java.lang.String defaultValue)`
`static AlexaClientManager`	`getSharedInstance()` Retrieves the global shared client library manager instance.
`java.lang.String`	`getSkillId()`
`java.lang.String`	`getSkillStage()`
`AlexaClientManager`	`initialize(android.content.Context applicationContext, java.lang.String skillId, java.lang.String skillStage, java.util.List<java.lang.String> capabilities)` Initialize the alexa video client library.
`boolean`	`isCollectAppUsageDataEnabled()` Check the user allow Appstore to collect information on the frequency and duration of use of downloaded apps.
`static boolean`	`isPreferenceExist(java.lang.String key)`
`static boolean`	`isPreferenceSet(java.lang.String key)`
`AlexaClientManager`	`setAlexaEnabled(boolean isAlexaEnabled)` Enable the Alexa Client library when the user meets all requirements for the current hosting application.
`AlexaClientManager`	`setDownChannelReady(boolean isDownChannelReady, java.lang.String applicationInstanceId)` Set the down channel ready status.
`AlexaClientManager`	`setPreference(java.lang.String key, java.lang.String value)` Set preference with key and value pair.

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - CAPABILITY_CHANNEL_CONTROLLER
```
public static final java.lang.String CAPABILITY_CHANNEL_CONTROLLER
```
    Channel control capability. See https://developer.amazon.com/docs/device-apis/alexa-channelcontroller.html.
    
    See Also:
    
    Constant Field Values
  - CAPABILITY_PLAY_BACK_CONTROLLER
```
public static final java.lang.String CAPABILITY_PLAY_BACK_CONTROLLER
```
    Playback control capability. See https://developer.amazon.com/docs/device-apis/alexa-playbackcontroller.html.
    
    See Also:
    
    Constant Field Values
  - CAPABILITY_REMOTE_VIDEO_PLAYER
```
public static final java.lang.String CAPABILITY_REMOTE_VIDEO_PLAYER
```
    Remote video play capability. See https://developer.amazon.com/docs/device-apis/alexa-remotevideoplayer.html.
    
    See Also:
    
    Constant Field Values
  - CAPABILITY_SEEK_CONTROLLER
```
public static final java.lang.String CAPABILITY_SEEK_CONTROLLER
```
    Seek control capability. See https://developer.amazon.com/docs/device-apis/alexa-seekcontroller.html.
    
    See Also:
    
    Constant Field Values
  - CAPABILITY_KEYPAD_CONTROLLER
```
public static final java.lang.String CAPABILITY_KEYPAD_CONTROLLER
```
    Keypad controller capability;
    
    See Also:
    
    Constant Field Values
  - SKILL_STAGE_DEVELOPMENT
```
public static final java.lang.String SKILL_STAGE_DEVELOPMENT
```
    Development skill stage that host application can select when initializing client library.
    
    See Also:
    
    Constant Field Values
  - SKILL_STAGE_CERTIFICATION
```
public static final java.lang.String SKILL_STAGE_CERTIFICATION
```
    Certification skill stage that host application can select when initializing client library.
    
    See Also:
    
    Constant Field Values
  - SKILL_STAGE_LIVE
```
public static final java.lang.String SKILL_STAGE_LIVE
```
    Live skill stage that host application can select when initializing client library.
    
    See Also:
    
    Constant Field Values
  - PREFERENCE_USE_LOCAL_TEST_SERVER
```
public static final java.lang.String PREFERENCE_USE_LOCAL_TEST_SERVER
```
    Use local test server for testing. Provide URL for locally running test server as value.
    
    See Also:
    
    Constant Field Values
  - PREFERENCE_USE_MILTIPART_BODY_PAYLOAD
```
public static final java.lang.String PREFERENCE_USE_MILTIPART_BODY_PAYLOAD
```
    Use multi-part payload for event data posting.
    
    See Also:
    
    Constant Field Values
  - VSK_VERSION
```
public static final java.lang.String VSK_VERSION
```
    VSK client library version number
    
    See Also:
    
    Constant Field Values
  - PREFERENCE_POST_EVENT_ALWAYS_FOR_TESTING
```
public static final java.lang.String PREFERENCE_POST_EVENT_ALWAYS_FOR_TESTING
```
    Control event posting logic for testing
    
    See Also:
    
    Constant Field Values
  - PREFERENCE_SKIP_DISCOVERY_EVENT_FOR_TESTING
```
public static final java.lang.String PREFERENCE_SKIP_DISCOVERY_EVENT_FOR_TESTING
```
    See Also:
    
    Constant Field Values
  - PREFERENCE_SKIP_STATUSCHANGED_EVENT_FOR_TESTING
```
public static final java.lang.String PREFERENCE_SKIP_STATUSCHANGED_EVENT_FOR_TESTING
```
    See Also:
    
    Constant Field Values
- Method Detail
  - getSharedInstance
```
public static AlexaClientManager getSharedInstance()
```
    Retrieves the global shared client library manager instance.
    
    Returns:
    
    Global shared instance.
  - initialize
```
public AlexaClientManager initialize(android.content.Context applicationContext,
                                     java.lang.String skillId,
                                     java.lang.String skillStage,
                                     java.util.List<java.lang.String> capabilities)
```
    Initialize the alexa video client library.
    
    Parameters:
    
    applicationContext - ApplicationContext of the hosting application.
    
    skillId - Skill ID associated with current hosting application.
    
    skillStage - Skill Stage associated with current hosting application.
    
    capabilities - List of strings describing supported capabilities.
  - setAlexaEnabled
```
public AlexaClientManager setAlexaEnabled(boolean isAlexaEnabled)
```
    Enable the Alexa Client library when the user meets all requirements for the current hosting application. For examples, signed-in with valid credentials.
    
    For example, when the hosting application calls this function with True, it will trigger the Alexa client library to start Discovery action when it's first flips from False to True.
    
    Parameters:
    
    isAlexaEnabled - Current enabled status to be set.
  - setDownChannelReady
```
public AlexaClientManager setDownChannelReady(boolean isDownChannelReady,
                                              java.lang.String applicationInstanceId)
```
    Set the down channel ready status.
    
    By default, down channel status is initialized as False. Alexa client library will postpone all interface with Alexa Service until this down channel status set to True. Host application should call it to set down channel status when it's ready.
    
    Parameters:
    
    isDownChannelReady - Set the current down channel ready status. If set as True, you have to provide valid non-empty string value via applicationInstanceId parameter. If set as False, applicationInstanceId parameter is ignored.
    
    applicationInstanceId - Application instance ID of current hosting application.
    
    Returns:
    
    client service interface to be used.
  - setPreference
```
public AlexaClientManager setPreference(java.lang.String key,
                                        java.lang.String value)
```
    Set preference with key and value pair.
    
    Available keys will be conveyed through additional documentation.
    
    Parameters:
    
    key - Key for preference to set.
    
    value - Valid for preference to set.
  - getApplicationContext
```
public android.content.Context getApplicationContext()
```
  - getApplicationInstanceId
```
public java.lang.String getApplicationInstanceId()
```
  - getSkillId
```
public java.lang.String getSkillId()
```
  - getSkillStage
```
public java.lang.String getSkillStage()
```
  - getDsn
```
public static java.lang.String getDsn()
```
  - getAndroidId
```
public static java.lang.String getAndroidId()
```
  - getCapabilitiesHashValue
```
public static java.lang.String getCapabilitiesHashValue()
```
  - addCapabilities
```
public void addCapabilities(org.json.JSONObject endpoint)
                     throws org.json.JSONException
```
    Throws:
    
    org.json.JSONException
  - isCollectAppUsageDataEnabled
```
public boolean isCollectAppUsageDataEnabled()
```
    Check the user allow Appstore to collect information on the frequency and duration of use of downloaded apps. This configuration can be set by user from 'Settings > Applications > Collect App Usage Data' menu on fire TV.
    
    Video client library is used by 3P applications to integrate with Alexa. Client library keeps sending events like whether that app is in foreground/background and based on that we have our business logic whether the app is active/inactive. Library will not post any events in case "Collect App Usage Data" setting is disabled by the user.
    NOTE: This check is currently disabled (I'm not even sure this 'restrict usage data collection' feature exists at a pre app level in FireTV). This method always returns true.
    
    Returns:
    
    True if usage data collection is enabled. False, otherwise.
  - getEventManager
```
public AlexaClientManager.EventManager getEventManager()
```
  - getAuthManager
```
public AlexaClientManager.AuthManager getAuthManager()
```
  - getAlexaApiEndpointProvider
```
public AlexaApiEndpointProvider getAlexaApiEndpointProvider()
```
  - getClientLibrarySharedPrefernces
```
public android.content.SharedPreferences getClientLibrarySharedPrefernces()
```
  - isPreferenceSet
```
public static boolean isPreferenceSet(java.lang.String key)
```
  - isPreferenceExist
```
public static boolean isPreferenceExist(java.lang.String key)
```
  - getPreferenceValue
```
public static java.lang.String getPreferenceValue(java.lang.String key,
                                                  java.lang.String defaultValue)
```

Class AlexaClientManager

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

CAPABILITY_CHANNEL_CONTROLLER

CAPABILITY_PLAY_BACK_CONTROLLER

CAPABILITY_REMOTE_VIDEO_PLAYER

CAPABILITY_SEEK_CONTROLLER

CAPABILITY_KEYPAD_CONTROLLER

SKILL_STAGE_DEVELOPMENT

SKILL_STAGE_CERTIFICATION

SKILL_STAGE_LIVE

PREFERENCE_USE_LOCAL_TEST_SERVER

PREFERENCE_USE_MILTIPART_BODY_PAYLOAD

VSK_VERSION

PREFERENCE_POST_EVENT_ALWAYS_FOR_TESTING

PREFERENCE_SKIP_DISCOVERY_EVENT_FOR_TESTING

PREFERENCE_SKIP_STATUSCHANGED_EVENT_FOR_TESTING

Method Detail

getSharedInstance

initialize

setAlexaEnabled

setDownChannelReady

setPreference

getApplicationContext

getApplicationInstanceId

getSkillId

getSkillStage

getDsn

getAndroidId

getCapabilitiesHashValue

addCapabilities

isCollectAppUsageDataEnabled

getEventManager

getAuthManager

getAlexaApiEndpointProvider

getClientLibrarySharedPrefernces

isPreferenceSet

isPreferenceExist

getPreferenceValue