Amazon Input SDK

With the Amazon Input SDK, you can show your users help dialogs that explain how to use your app with a keyboard and mouse. This can provide a pleasant and useful experience to users who don't typically interact with your app using a keyboard and mouse. Before following this guide, make sure you have enabled keyboard and mouse support in your app. For help with adding keyboard and mouse support, see Input Controls in the Windows Compatibility Guide.

If you are using Unity, see Amazon Input SDK for Unity.

• Requirements
• Add the Input SDK to your project
  • Option 1: Manually add the SDK
  • Option 2: Use Maven Central to add the SDK
• Create an input map
  • Define an input action
  • Define an input group
  • Build an input map
  • Create an input mapping provider
  • Register an input mapping provider
  • Display the help screen
• API reference for the Amazon Input SDK
  • InputControls
  • InputAction
  • InputGroup
  • MouseSettings
  • InputMap
  • InputMappingProvider
  • InputMappingClient
  • Input
  • TriggerHandler
  • UIMode

Requirements

The Amazon Input SDK requires a minimum Android SDK version of API level 19 or above.

Add the Input SDK to your project

Download the Amazon Input SDK here.

Amazon Input SDK

The download includes the AAR file, Javadocs, and a sample app.

Option 1: Manually add the SDK

To add the Amazon Input SDK to your project, import the AAR file as a library with these steps.

1. Open your project in Android Studio. Use the Project folder structure view.
2. Create a libs folder under the app folder if it doesn't exist. Copy the AAR file into the app/libs folder.
3. Right click the project folder and select Open Module Settings.
4. On the sidebar, click Dependencies and select the app module (or equivalent).
5. Click the plus sign under Declared Dependencies and provide the path to the SDK AAR location: libs/inputmapping-[x].aar. This automatically adds the dependency to the build.gradle file.
6. Click OK.

7. Verify the dependency is added to the app-level build.gradle file as shown in this example.

    dependencies {
        implementation files('libs/inputmapping-1.0.1.aar')
    }
   

8. Add the following two dependencies to the app-level build.gradle file:

    implementation 'com.android.support.constraint:constraint-layout:2.0.4'
    implementation 'com.android.support:recyclerview-v7:28.0.0'
   

Option 2: Use Maven Central to add the SDK

1. Add the Amazon Input SDK into the dependencies section of your app-level build.gradle file as shown below.

  dependencies {
      ...
      implementation 'com.amazon.device.inputmapping:inputmapping:1.0.1'
  }

1. Make sure your project's top-level build.gradle file has the Maven Central repository defined, or add it as shown.

  allprojects {
      repositories {
          mavenCentral()
      }
      dependencies {
          ...
      }
  }

Create an input map

With the Amazon Input SDK, you'll map key events and mouse clicks to input actions, group those actions into input groups, and create an input map from the input groups, as indicated in the following diagram.

Define an input action

An input action is an event corresponding to an app action. The input action can be mapped to a key or a combination of keys. In the following example, the "Jump" action is mapped to the space key, and the "Move" action is mapped to mouse movement.

• Java
• Kotlin

InputAction jumpInputAction = InputAction.create(
        "Jump",
        MyGameActions.JUMP, // MyGameActions here is an enumeration in the game
        InputControls.create(
                Collections.singletonList(KeyEvent.KEYCODE_SPACE),
                Collections.emptyList()
        )
);

InputAction cmbMove = InputAction.create(
        "Move",
         MyGameActions.MOVE,
        InputControls.create(
                Collections.emptyList(),
                Collections.singletonList(InputControls.MOUSE_MOVEMENT)
        )
);

val jumpInputAction = InputAction.create(
            "Jump",
            MyGameActions.JUMP.ordinal, // MyGameActions here is an enumeration in the game
            InputControls.create(
                listOf(KeyEvent.KEYCODE_SPACE),
                emptyList()
            )
        )

val move = InputAction.create(
            "Move",
            MyGameActions.MOVE.ordinal,
            InputControls.create(
                emptyList(),
                listOf(InputControls.MOUSE_MOVEMENT)
            )
        )

Input SDK methods used in example:

• InputAction.create(String actionLabel, int uniqueId, InputControls inputControls)
  • Considerations:
    • For uniqueId, use enums.
• InputControls.create(List<Integer> keyboardActions, List<Integer> mouseActions)
  • Considerations:
    • For keyboardActions, use key code constants from the Android framework KeyEvent class.
    • For mouseActions, use constants from the Amazon Input SDK InputControls class.

Define an input group

An input group is a group of multiple input actions. An input group has a group label and a list of input actions that belong to the group. Each InputAction must be associated with an InputGroup. The following example shows a "Basic Movement" input group created with the input actions defined in the previous section.

• Java
• Kotlin

InputGroup movementInputGroup = InputGroup.create("Basic Movement",
        Arrays.asList(jumpInputAction, move));

var movementGroup = InputGroup.create("Basic Movement", 
        listOf(move, jumpInputAction)
)

Input SDK methods used in example:

• InputGroup.create(String groupName, List<InputAction> actions)

Build an input map

An input map is the collection of input groups for the app. The input map also contains the mouse settings that are applicable for the app. After you have defined all the input actions and grouped them into input groups, create the input map like in this example.

• Java
• Kotlin

return InputMap.create(
        Arrays.asList(movementInputGroup, specialInputGroup),
        MouseSettings.create(true, true));

return InputMap.create(
    listOf(moveGroup, gameControls),
    MouseSettings.create(true, true)
)

Input SDK methods used in example:

• InputMap.create(List<InputGroup> inputGroups, MouseSettings mouseSettings)
• MouseSettings.create(boolean adjustableSensitivity, boolean invertedYAxis)

Create an input mapping provider

To provide the input map on request, implement the InputMappingProvider interface. The Amazon Input SDK invokes the input mapping provider when a user requests a help screen.

• Java
• Kotlin

public class CustomInputMapProvider implements InputMappingProvider {

    @Override
    public InputMap onProvideInputMap() {
        // returns the input map
    }
}

class CustomInputMapProvider: InputMappingProvider {

    override fun onProvideInputMap(): InputMap {
        // returns the input map
    }
}

Register an input mapping provider

There can only be one active input map at a time. When a user accesses the help screen, they are shown the currently active input map. Register an input mapping provider as the active input mapping provider through the Input static class as shown in the following example.

• Java
• Kotlin

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    InputMappingClient inputMappingClient = Input.getInputMappingClient(this);
    inputMappingClient.setInputMappingProvider(new CustomInputMapProvider());
}

override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        val inputMappingClient = Input.getInputMappingClient(this)
        inputMappingClient.inputMappingProvider = CustomInputMapProvider();
    }

The active input mapping provider remains intact across activities and isn't affected by lifecycle events. However, you can change the active input map using the InputMappingClient and setting a different input mapping provider.

Display the help screen

To display the help screen, the Appstore recommends displaying a visual element to the user that, when clicked, opens the help screen. You can place the visual indicator either within the game window, or in a separate screen, such as a preferences or controls page. Display the help screen using the TriggerHandler.showHelp() method as shown.

• Java
• Kotlin

TriggerHandler.getInstance().showHelp(this, "My App");

TriggerHandler.getInstance().showHelp(this, "My App");

API reference for the Amazon Input SDK

Browse this section for an introduction to some of the APIs in the Amazon Input SDK. For a complete API reference, see the Amazon Input SDK API Reference.

InputControls

InputControls.create(List<Integer> keyboardActions, List<Integer> mouseActions)

The InputControls object contains a list of keyboard actions and a list of mouse actions. The object is created using the static method InputControls.create().

The InputControls.create() method returns a new InputControls object. Use an InputControls object to create an InputAction.

InputAction

InputAction.create(String actionLabel, int uniqueId, InputControls inputControls)

The InputAction object contains a label, a unique ID and an InputControls object. The object is created using the static method InputAction.create().

The InputAction.create() method returns a new InputAction object. Use InputAction objects to create an InputGroup.

InputGroup

InputGroup.create(String groupName, List<InputAction> actions)

The InputGroup object contains a name and a list of InputAction objects. The object is created using the static method InputGroup.create().

The InputGroup.create() method returns a new InputGroup object. Use an InputGroup along with MouseSettings to create an InputMap.

MouseSettings

MouseSettings.create(boolean adjustableSensitivity, boolean invertedYAxis)

The MouseSettings object contains boolean mouse settings for adjustable sensitivity and inverted y-axis. The object is created using the static method MouseSettings.create().

The MouseSettings.create() method returns a new MouseSettings object. Use MouseSettings along with InputGroup to create an InputMap.

InputMap

InputMap.create(List<InputGroup> inputGroups, MouseSettings mouseSettings)

The InputMap object contains a list of InputGroup objects, and a MouseSettings object. The object is created using the static method InputMap.create().

The InputMap.create() method returns a new InputMap object. Return an InputMap from your InputMappingProvider implementation.

InputMappingProvider

The InputMappingProvider interface provides the onProvideInputMap() method. In your implementation, override this method to return an InputMap. The InputMap data will be displayed when a user accesses the help screen.

InputMappingClient

The InputMappingClient allows you to manage the InputMappingProvider and provides the following methods:

• setInputMappingProvider(InputMappingProvider inputMappingProvider): assigns an InputMappingProvider to this instance of InputMappingClient.
• clearInputMappingProvider(): removes the currently assigned InputMappingProvider and makes it null.
• getInputMappingProvider(): returns the currently assigned InputMappingProvider.

Input

This class is used to instantiate an InputMappingClient and provides the following method:

• getInputMappingClient(Activity activity): returns a singleton instance of the InputMappingClient.

TriggerHandler

This class provides a method to display the help dialog and contains the following methods:

• getInstance(): returns a singleton instance of the TriggerHandler.
• showHelp(Activity activity, String title): shows the input help dialog box. Populates the dialog box by taking data from the registered InputMap. Takes the following parameters.
  • activity - the activity that contains the help dialog
  • title - the title of the app to display on the dialog
• showHelp(Activity activity, String title, UIMode uiMode): shows the input help dialog box with a specified theme (light or dark). Takes the following parameters.
  • activity - the activity that contains the help dialog
  • title - the title of the app to display on the dialog
  • uiMode - the theme setting, valid values are UIMode.AUTO, UIMode.LIGHT, UIMode.DARK
• setUiMode(UIMode uiMode): sets the theme for the dialog box. Takes the following parameters.
  • uiMode - the theme setting, valid values are UIMode.AUTO, UIMode.LIGHT, UIMode.DARK

UIMode

This is an enum that defines the constants you can use to set the theme on the help dialog. The constants are:

• AUTO - follow system theme
• DARK - use dark them
• LIGHT - use light theme

Last updated: Mar 05, 2024