Amazon Developer

as

Settings
Sign out
Notifications
Alexa
Amazon Appstore
Ring
AWS
Documentation
Support
Contact Us
My Cases
Develop
Test
Publish
Monetize
Engage users
Device specifications
Resources
Skip to main content

Prerequisites

Install Android Studio

We recommend you download the latest version of Android Studio, but it isn’t required to implement the Predictive Touch API. If you’re using another IDE, make sure you have the Android SDK (30 or higher) installed and meet all other system requirements necessary for Android development. This documentation assumes you’re using Android Studio.

Download the Amazon Stylus SDK for Fire Tablets

This download allows you to implement Predictive Touch in your Stylus enabled Apps. Extract the SDK contents to a location of your choice.

Add the SDK to Android Studio

  1. Download the SDK, save it to a preferred folder, and extract the zip file.
  2. Open your existing project or make a new project in Android Studio.
  3. Change the folder structure from Android to Project. What you should see when changing folder structure in Android Studio
  4. If not already created, inside of the app (old Android Studio) or Application (newer Android Studio), create a libs folder. What you should see when changing folder structure in Android Studio
  5. Copy the StylusSDKSupportLibrary-1.0.aar extracted in step 1 to the libs folder you created.
  6. In your app’s build.gradle file, reference the AAR file in the dependencies object: Add the implementation files (libs/StylusSDKSupportLibrary-1.0.aar) in the build.gradle file’s dependency section.
Now, you can use the Amazon Stylus SDK APIs in your project.

API specifications

You will be working with these classes and APIs for predictive touch:
  • com.amazon.stylussupportsdk.predictedtouches.AmazonPredictiveTouch
  • com.amazon.stylussupportsdk.predictedtouches.AmazonPredictedEvents
AmazonPredictiveTouch This class is to carry out all the tasks like registering/deregistering for Predictive Touches. It also helps in getting the predicted points, so that apps can ask for them. Always call isFeatureRuntimeAvailable(Context) to know if the Predictive Touches are supported at runtime on device. If not supported, apps can refrain from calling other API’s as those won’t be useful. The App then needs to initialize AmazonPredictiveTouch using init(Context) in order to use predictions. AmazonPredictiveTouch This class contains the predicted coordinates. An instance of this is supplied to the app it is using AmazonPredictiveTouch#getLatestPredictions(long).

Implementing the Amazon Stylus SDK

Overview

  1. Check for feature availability using AmazonPredictiveTouch.isFeatureRuntimeAvailable().
  2. Initialize the AmazonPredictiveTouch using AmazonPredictiveTouch.init().
  3. Check if PredictiveTouches is registered using public static boolean isPredictiveTouchesRegistered().
  4. Register for predictions using AmazonPredictiveTouch.registerPredictiveTouches().
  5. Set the view for which you will use predictions using AmazonPredictiveTouch.setCurrentView().
  6. Identify if it’s a MOVE event in onTouchEvent and note its timestamp and coordinates.
  7. Get predictions using AmazonPredictiveTouch.getLatestPredictions() and draw using AmazonPredictedEvents.
  8. Deregister predictions using AmazonPredictiveTouch.deregisterPredictiveTouches().
See the following sections for details on each of these.

Step 1: Check for Amazon Predictive Touch availability

Use the AmazonPredictiveTouch.isFeatureRuntimeAvailable(android.content.Context context``) method to know whether the feature is available on the device. If the feature is not available or supported, this method returns false. Otherwise, it returns true.

Step 2: Initialize the AmazonPredictiveTouch

Use the AmazonPredictiveTouch.init(android.content.Context context) method to initialize. This should be done using the onCreate``() method of an Activity or during View creation (if needed only for that view). Initialization also registers with the PredictionService by default, so you can skip calling AmazonPredictiveTouch.registerPredictiveTouches() after this step. Now, predictive touch APIs can be used in all app processes.

Step 3: Check if PredictiveTouches is registered

Use the utility method isPredictiveTouchesRegistered() to check if PredictiveTouches is registered. This returns a boolean value. For the App to receive predictive points, you must initialize or register the listener with either init() or registerPredictiveTouches(). You only need to use registerPredictiveTouches() in the cases where you have called deregisterPredictiveTouches() on certain views where you do not want the prediction and then come back to the view where the prediction is needed.

Step 4: Register for predictions

This is required when you used AmazonPredictiveTouch.deregisterPredictiveTouches() earlier to save compute/memory resources as you didn’t need predictions, but now you again need predictions to be enabled. In order to start receiving predictions again, use the AmazonPredictiveTouch.registerPredictiveTouches() method. This is an idempotent API, so calling it multiple times is not needed and won’t result in different behavior. It returns true if registration is successful, otherwise it returns false.

Step 5: Set the view for which you will use predictions

Each view has its own geometrical transform. For instance, its position on the screen, possible rotation, or scaling effects. The touch points need to be transformed accordingly. In order to provide accurate predicted events to the current view where you will use predictions, set your current view. This can be done by switching to a new view that uses predictions. Use the method setCurrentView``(android.view.View view). Call this method before drawing in onTouchEvent() for MotionEvent.ACTION_DOWN for each view, which gets called every time a view is touched.

Step 6: Identify if it’s a MOVE event using TouchEvent and note its timestamp and coordinates

Only use predictions for MOVE events. You can identify if it’s a MOVE event using the onTouchEvent() method. Make note of its timestamp and coordinates. To predict points for the latest MOVE event, use the timestamp. Also, we want to draw predicted points after the latest touch points X, Y coordinates, so we need the coordinates for it. This can be done using onTouchEvent() with variables such as mLatestX, mLatestY, and mCurrentMoveTime. See the following sample code.

Step 7: Get the predictions and draw

Now that we know it’s a MOVE event and have its timestamp and its coordinates, we need to get the predictions corresponding to this timestamp.
  1. Use getLatestPredictions(long t) to get the predictions.
  2. This gives the AmazonPredictedEvents object. You can use this object to find the following:
    1. The number of predictions using the getNumberOfPredictions() method. This returns an integer.
    2. Event time using getEventTimeAt(int index). This returns a timestamp of type long.
    3. X / Y coordinates using the getXAt(int index) and getYAt(int index) methods. These return float values.
  3. Add the predictions to the current path or separate path for predictions to draw.
  4. Draw the path containing predictions.

Step 8: Deregister predictions

Call the deregisterPredictiveTouches() method to deregister PredictiveTouches. You may consider doing this when the app moves to an Activity or View that does not need predictions, or your app goes into the background, to reduce CPU/Memory usage. It is important that you link deregisterPredictiveTouches() of PredictiveTouches with the lifecycle of the Activity/View where it was initialized. For example, for an activity, use init() in the onCreate() method and use deregisterPredictiveTouches() in the onDestroy() method. In scenarios where the process is not terminated but the Activity or View is destroyed, you won’t be able re-initialize PredictiveTouches in the onCreate() method if it was not deregistered earlier. Display rotation is an example where the process is not killed (the process is still registered with the service), but the activity is re-created (which tries to create a new instance). On a successful deregister, the method returns true, otherwise it returns false.

Troubleshooting

If you are having trouble getting or drawing predictions, check the following: Is the feature available on the device? Solution: Update Fire OS to latest version and call AmazonPredictiveTouch.isFeatureRuntimeAvailable() to check if your device supports this feature. Refer to Step 1 for details. Do I need to maintain two APKs if my app will also be available on devices that don’t support Predictive Touch? Solution: No, there is no need to maintain two different APKs. Use AmazonPredictiveTouch.isFeatureRuntimeAvailable() to determine if the device supports Predictive Touch before initializing AmazonPredictiveTouch. Can I draw the predictions with a separate paint object (like a different color) and see that the predictions are being drawn? Solution: Use the code sample in Step 7. Registering predictions (Step 4) or setting the view for predictions (Step 5) fails: Currently, for a process we only support one channel for receiving predictions, and so init() should only be called once in a process. It’s not uncommon to have multiple activities or a rotation case where the same activity is recreated and init() is called again. Solutions:
  • Use deregisterPredictiveTouches() when exiting an activity/view where init() was called.
  • Use the isPredictiveTouchesRegistered() API to check if init() needs to be called. If it returns true, there is no need to call init() again.
Last modified on November 10, 2023