Introducing the Input SDK for Amazon Appstore
Published: 2023-07-06 14:07:14

by Gio Laquidara

Imagine a skilled game developer successfully launches a popular game for Android. The mobile game features intuitive touch controls and engaging gameplay. There are hundreds of positive reviews in the appstore, and user growth is the current priority.

There's now a sizable opportunity to expand the game to PCs through [Amazon Appstore for Windows 11](https://developer.amazon.com/docs/appstore-on-windows/overview.html?cmp=_07_devg&ch=soc&chlast=soc&pub=devto&publast=devto&type=org&typelast=org) and the [Windows Subsystem for Android (WSA)](https://learn.microsoft.com/en-us/windows/android/wsa/). However in order to support Android apps on PCs, the existing touch screen controls need to now work with mouse and keyboard inputs which can pose refactoring challenges. How can you ensure the best user experience for PC gamers? To understand how to support keyboard and mouse inputs in existing touch-based game or app, read my recent suggestions in this [developer article on mapping inputs](https://developer.amazon.com/apps-and-games/blogs/2023/03/mapping-app-input-with-wsa?cmp=_07_devg&ch=soc&chlast=soc&pub=devto&publast=devto&type=org&typelast=org).

The [Amazon Input SDK](https://developer.amazon.com/docs/appstore-on-windows/input-sdk.html?cmp=_07_devg&ch=soc&chlast=soc&pub=devto&publast=devto&type=org&typelast=org) enhances the user experience by providing display on-screen information for the available inputs for specific actions in games. This article will show how to use the Input SDK to help users understand how to navigate and interact using mouse and keyboard inputs.

![Help Screen](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/v3w69lao4zq3ofeo18zm.png)

Whether you prefer native Android development or building with Unity, we have you covered. The Amazon Input SDK comes in two versions:

1. [Amazon Input SDK (Java/Kotlin)](https://developer.amazon.com/docs/appstore-on-windows/input-sdk.html?cmp=_07_devg&ch=soc&chlast=soc&pub=devto&publast=devto&type=org&typelast=org)
2. [Amazon Input SDK for Unity](https://developer.amazon.com/docs/appstore-on-windows/input-sdk-unity.html?cmp=_07_devg&ch=soc&chlast=soc&pub=devto&publast=devto&type=org&typelast=org)

The following sections cover how integrate both flavors of the Input SDK. 

### Amazon Input SDK (Java/Kotlin)
 
Let's start by exploring the usage of the [Amazon Input SDK for Java/Kotlin](https://developer.amazon.com/docs/appstore-on-windows/input-sdk.html?cmp=_07_devg&ch=soc&chlast=soc&pub=devto&publast=devto&type=org&typelast=org).

To begin using the SDK in your app, add the Amazon Input SDK to the dependencies section of your app-level build.gradle file:


```groovy
  dependencies {
      ...
      implementation 'com.amazon.device.inputmapping:inputsdklib:1.0.0'
  }
```

The main component of this SDK is the `InputMappingProvider`.

When a user requests a help screen, the SDK will use this provider to present the control-action map. The first step in using this SDK is to implement the InputMappingProvider interface and return your input map in the onProvideInputMap method.

```kotlin
class CustomInputMapProvider: InputMappingProvider {

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

Once you have implemented this interface, you can register your input mapping provider through the Input static class.

```kotlin
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 is not affected by the activities lifecycle events and remains valid across different activities. However, you can change it whenever you prefer by using the InputMappingClient and setting a different input mapping provider.

After defining the input mapping provider, you can simply call the following method

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

This will display the help screen to guide users on how to play your game.

Now let's dive into the details of the **Input Map**.

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/1llf0asi1ngqw3ux3tsm.png)

An `InputMap` is the collection of your app's input-action mappings `InputAction` arranged in groups `InputGroup`.

An input action refers to an event that corresponds to an action performed within the app. This action can be associated with a single key or a combination of keys. For instance, in the given example, the action "Jump" is linked to the pressing of the space key, while the action "Move" is associated with the movement of the mouse.

```kotlin
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)
            )
        )
```

Each input action must be linked to a specific input group. Each input group consists of a label and a collection of input actions categorized within the group. In the previous section, we defined various input actions, and now we can illustrate this concept with an example. Let's create an input group called "Basic Movement," which includes the defined input actions from the previous section:
  
```kotlin
var movementGroup = InputGroup.create("Basic Movement", 
        listOf(move, jumpInputAction)
)
```

After defining all the necessary groups, you can pass them to the InputMap.create method to return the input map for your app:

```kotlin
return InputMap.create(
    listOf(moveGroup, gameControls),
    MouseSettings.create(true, true)
)
```
  
The `InputMap.create()` method allows you to define the mouse settings applicable to the app.

Specifically, you can enable the adjustment of the mouse sensitivity and invert the Y-axis:
  
```kotlin
MouseSettings.create(boolean adjustableSensitivity, boolean invertedYAxis)
```

### Unity SDK
If you are using Unity for your game and want to use the Amazon Input SDK, here are the steps to integrate the SDK into your Unity projects:

1. Download the Amazon Input SDK for Unity [here](https://developer.amazon.com/docs/appstore-on-windows/input-sdk-unity.html?cmp=_07_devg&ch=soc&chlast=soc&pub=devto&publast=devto&type=org&typelast=org). The download includes the `.unitypackage` file and a sample app.

2. From the Assets menu, select Import Package > Custom Package.

3. Browse for `amazon.device.inputmapping.unitypackage` and select it.

4. Select all the files in the subsequent import dialog and click Import.

5. Go to Preferences > External Tools. In the Android section, uncheck Gradle installed with Unity and choose the required Gradle version for your project. We recommend Version 5.6.4.

6. Go to Project settings > Player, select the Android tab, and expand the Publishing settings section.
   In the Build section, click the checkbox for Custom Launcher Gradle Template as shown in the following image.

![Custom launcher Gradle Option](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/w6dkw8aum74j6pwlxz4a.png)

1. Add the following dependencies in the dependency section of the Gradle launcher template file

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

After setting up the Input SDK for your Unity Project, you are ready to use the main component that provides the input map on request: the InputMappingProvider interface.

Implement this interface and the Amazon Input SDK for Unity will be able to show the input mapping when a user requests a help screen:

```csharp

// C# example for Unity
private class CustomInputMappingProvider : InputMappingProvider
{
    public InputMap OnProvideInputMap()
    {
        // create an input map
        return inputMap;
    }
}
```

To use your custom Input Mapping Provider, you need to register it by calling SetInputMappingProvider of the InputMappingClient, as shown in the code below.
  
```csharp

 void Start()
{
    var _inputMappingClient = Input.GetInputMappingClient();
    _inputMappingClient.SetInputMappingProvider(new CustomInputMappingProvider());
}
```

After registering it you will be able to show the help screen with the mapping to the user calling

```csharp
TriggerHandler.ShowHelp("My App");
```

### The Input Map

The input map returned from the OnProvideInputMap of your CustomInputMappingProvider will contains all the mapping key events/mouse click to input actions.


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.

```csharp
var jump = InputAction.Create(
        "Jump",
        Actions.JUMP, //where Actions is an enumeration for the game actions
        InputControls.Create(
                new[] 
                {
                    AndroidKeyCode.KEYCODE_SPACE
                },
                null
        )
);
```

Here, the "Move Left" action is mapped to the left key on the numeric keypad and "Move Right" is mapped to the right key on the numeric keypad.

```csharp
var moveLeft = InputAction.Create(
        "Move Left",
        Actions.MOVE_LEFT,
        InputControls.Create(
                new[]
                {
                    AndroidKeyCode.KEYCODE_NUMPAD_LEFT
                },
                null
        )
);

var moveRight = InputAction.Create(
        "Move Right",
        Actions.MOVE_RIGHT,
        InputControls.Create(
                new[]
                {
                    AndroidKeyCode.KEYCODE_NUMPAD_RIGHT
                },
                null
        )
);
```

You will have to group all the desired actions in a InputGroup

An input group has a group label and a list of input actions that belong to the group. The following example shows a "Basic Movement" input group created with the input actions defined in the previous section.

```csharp
InputGroup movementInputGroup = InputGroup.Create("Basic Movement",
    new[]
    {
        jump, moveLeft, moveRight
    }
);
```

You can then collect all your groups of input and pass it to the InputMap creation. The input map also contains the mouse settings that are applicable for the app, such as allowing the adjustment of the sensitivity of the mouse or inverting the Y Axis (in the following code false and true respectively).
 

```csharp
var inputMap = InputMap.Create(
    new[]
    {
        movementInputGroup
    },
    MouseSettings.Create(false, true)
);
```
You are ready not to return your input map from the OnProvideInputMap of your InputMappingProvider

### Wrap up
By integrating the Amazon Input SDK in touch games on Android, you can provide clear instructions to players on how to use keyboard and mouse inputs effectively on devices with keyboard and mice. This will help ensure a smooth transition from touch controls to PC inputs and enhance the overall user experience.


To know more about Amazon Input SDK head over to [our docs](https://developer.amazon.com/docs/appstore-on-windows/input-sdk.html?cmp=2023_07_devg&ch=soc&chlast=soc&pub=devto&publast=devto&type=org&typelast=org).


**Stay updated** 

For the latest Amazon Appstore developer news, product releases, tutorials, and more:

📣 Follow [@AmazonAppDev](https://twitter.com/AmazonAppDev) and [our team](https://twitter.com/i/lists/1580293569897984000/members) on Twitter

📺 Subscribe to our [Youtube channel](https://www.youtube.com/amazonappstoredevelopers)

📧 Sign up for the [Developer Newsletter](https://m.amazonappservices.com/devto-newsletter-subscribe)

### About the author

Giovanni ("Gio") Laquidara is a Senior Dev Advocate at Amazon, where he works on supporting developers around the world using the Amazon Appstore across many devices. 

Previously, Gio worked as a software engineer building mobile apps, real-time defence systems, and VR/AR experiences. For fun, Gio enjoys low level programming, IoT hacking, and command line apps ⌨️✨.

_You can connect with Gio on [Twitter](https://twitter.com/giolaq), [Linkedin](https://www.linkedin.com/in/glaquidara/), and [giolaq.dev](https://giolaq.dev)._