No results found

Try a different or more specific query
Developer Console

Windows Compatibility Guide

If you are a developer with an existing app looking to fix a specific issue, see the Troubleshooting Index for Windows.

If you are a developer who has a new or existing Android app and want to make sure it's compatible with Windows Subsystem for Android™, or if you are new to the Amazon Appstore and are curious about porting your app to Windows 11 devices, browse the following topics.

To port your Android app to Windows 11, start by reviewing the following topics.

Upgrade to Android 12 - Windows Subsystem for Android is based on Android 12. Update your app to align with Android 12 requirements.
Topics: Scoped storage


Build for Windows - Learn how to handle Windows-specific use cases.
Topics: Input controls | Graphics | Window management and resizing | Camera features | Support x86 ABI architecture


Handle unsupported features - Learn how to handle unsupported features, including hardware or software service dependencies.
Topics: Common features - unsupported | Common features - limited support| Disable unsupported ad SDKs | Handle unsupported Google Play services | Conditionally disable unsupported features | Unsupported feature tables


Upgrade to Android 12

Topics: Scoped storage

Windows Subsystem for Android is based on Android 12. If your app is built to target an older version of Android, upgrade your app to be compatible with Android 12 features.

The Android developer documentation provides important information about the changes between the different versions of Android. Review these guides to help transition to Android 12.

If your app requires file access, there are specific features on Android 10 and higher that might affect how your app behaves on these versions of Android, including Windows Subsystem for Android. Issues relating to file access are most commonly caused by scoped storage. To prevent apps from experiencing file access issues, follow these guidelines.

Scoped storage

File storage issues that occur in apps tested on Windows Subsystem for Android are often caused by scoped storage. Scoped storage is an Android feature introduced in Android 10 and enforced in Android 11. With scoped storage, apps only have access to an app-specific directory on external storage and media that the app created. For more information on scoped storage, see the Android developer guide on Android storage use cases and best practices .

↑ Back to top


Build for Windows

Topics: Input controls | Graphics | Window management and resizing | Camera features | Support x86 ABI architecture

To provide a pleasant user experience, your app needs to be able to run in a large screened, windowed environment such as Windows Subsystem for Android. There are additional details in this environment that you might not have needed to handle on mobile devices. Consider the following topics. If you need help with an issue not listed here, visit the Amazon developer forums for help from the developer community.

Input controls

Apps that are natively designed for Android or other touchscreen mobile devices might not handle keyboard and mouse input effectively. To make the app compatible with the input controls available on a non-touchscreen Windows device, follow the guidelines in this section.

Keyboard input

For keyboard input design considerations, see the Android developer guide on Input support. For details on how to handle keyboard inputs, use the following Android developer guides:

To help provide a keyboard-first experience, you can check if the device has a keyboard with the following code:

 

Copied to clipboard.

private boolean isKeyboardConnected() {
    return getResources().getConfiguration().keyboard == Configuration.KEYBOARD_QWERTY;
}

 

Copied to clipboard.

private fun isKeyboardConnected(): Boolean {
    return resources.configuration.keyboard == Configuration.KEYBOARD_QWERTY
}

Your app should handle common controls for Windows apps and games that might not be automatically handled by the Android framework. Consider how to handle the following keyboard inputs when building mobile apps that are compatible with Windows devices.

  • Enter key
  • Arrow key navigation
  • Tab key navigation
  • Ctrl-based shortcuts (for example, Ctrl-C for copy and Ctrl-V for paste)
  • Changing the highlight color of a selected item
  • Right click to show context menu
  • W, A, S, and D keys to move in games
  • Spacebar to jump in games

Example: Allow a player to press Ctrl-J for a special move in a game.

@Override
public boolean onKeyUp(int keyCode, KeyEvent event) {
    switch (keyCode) {
        ...
        case KeyEvent.KEYCODE_J:
            if (event.isCtrlPressed()) {
                superJumpCombo();
            } 
        ...
        default:
            return super.onKeyUp(keyCode, event);
    }
}
override fun onKeyUp(keyCode: Int, event: KeyEvent): Boolean {
    return when (keyCode) {
        ...
        KeyEvent.KEYCODE_J -> {
            if (event.isCtrlPressed) {
                superJumpCombo()
            } 
            true
        }
        ...
        else -> super.onKeyUp(keyCode, event)
    }
}

Mouse input

By default, Windows Subsystem for Android converts a left mouse click to a virtual touch event and a mouse wheel scroll to a swipe event. This is done to enable compatibility of most apps built for touchscreen that don't handle mouse input. For other mouse actions, update your code to handle the specific inputs. Consider addressing the following actions:

  • Right click
  • Drag and drop
  • Tooltips and hover text
  • Hover effects

Learn to handle mouse inputs by following the Android developer guides:

Graphics

To give users an optimal experience when they run your app on a Windows computer, support larger screens and use enhanced graphics in your app. Use the following recommendations to improve how users experience your app on Windows.

OpenGL ES Version. Windows Subsystem for Android supports OpenGL ES 1.1, 2.0, and 3.0. OpenGL ES 3.1 and higher are not currently supported.

Max frame rate. It's likely that your app can be run at higher frame rates on a Windows computer than on a mobile device. For the best experience on Windows, set the maximum frame rate to 60 FPS or higher, or remove the maximum frame rate limit.

UI scaling. Make sure all UI elements are appropriately sized for a larger screen. It's recommended that HUDs be less than 20% of the screen.

Aspect ratios. For an optimal experience on larger devices, support multiple aspect ratios including 16:9, 16:10, and 3:2.

Window management and resizing

On Windows Subsystem for Android, apps always open in multi-window mode, and can be resized by a user. Users can also snap an app window to the edge or corner of the screen using Windows' actions. These features can cause users to have a different experience in your app on Windows than on mobile devices.

If your app doesn't work well while resizing, you can configure your app to maintain a fixed size or orientation regardless of display size or device orientation. However, it's recommended to enable multi-window support for better compatibility across device form factors.

On Windows Subsystem for Android, if an app has a fixed orientation, or isn't resizable and its maximum or minimum aspect ratio doesn't align with the aspect ratio of the device display, the app is rendered using letterboxing or pillarboxing. Depending on your app, you might want to use some of the following configuration settings in your app's manifest to control app orientation and resizing.

  • android:resizeableActivity: Use this attribute to specify support for multi-window mode. For specific behaviors based on API levels, see the Android documentation for resizeableActivity.
  • android:screenOrientation: Use this attribute to specify the orientation of your app. To use this attribute, resizeableActivity must be set to false. For more details on this attribute, see the Android documentation for screenOrientation.
  • android:maxAspectRatio: Use this attribute to specify the maximum aspect ratio your app supports. To use this attribute, resizeableActivity must be set to false. For more details on this attribute, see the Android developer documentation for maxAspectRatio.
  • android:minAspectRatio: Use this attribute to specify the minimum aspect ratio your app supports. To use this attribute, resizeableActivity must be set to false. For more details on this attribute, see the Android developer documentation for minAspectRatio.

Letterboxing and pillarboxing

When the aspect ratio of content isn't aligned with the display that contains it, letterboxing or pillarboxing can occur for apps that are unable to be resized. In letterboxing, the original content is wider than the display it's being viewed on. To preserve the aspect ratio of the content and see the full width, bars are added to the top and bottom of the content.

a white box with blue bars on the top and bottom
Letterboxing

In pillarboxing, the original content is narrower than the display it's being viewed on. To preserve the aspect ratio, bars are added to the sides.

a white box with blue bars on the left and right sides
Pillarboxing

The added bars can be light or dark themed depending on the system settings. Letterboxing and pillarboxing occur when the app is snapped, maximized, or manually resized.

Multi-window mode

When your app runs on Windows Subsystem for Android, it opens in multi-window mode. This could create issues when your app is minimized, when the device screen is locked, or when the computer wakes up from sleep.

To prevent issues, it's important to use proper windowing mechanisms. For details on how to support windowing mechanisms, see the Android developer guide Multi-window support . You must also handle the activity lifecycle as it relates to multi-window mode to make sure the app state is saved and loaded correctly. For details, see the Android developer guide Activity lifecycle in multi-window mode .

Additional resizing considerations

To make your mobile apps compatible with the window management and resizing capabilities of Windows devices, consider the following topics.

  • Initial launch size - set the display size and orientation when the app launches
  • Windows dimensions
    • Contents bounds - avoid truncated or inaccessible content
    • Free-form sizing - support window resizing
  • Screen orientation - consider supporting portrait and landscape modes

For more details on each topic, see the Android developer guide for Window Management .

Camera features

Follow these guidelines if your app uses a camera and you are targeting Windows devices.

  • Use Android's CameraManager APIs to check for available camera devices before attempting to use a device's camera. Unlike mobile devices, Windows devices might have a single camera, multiple cameras, no camera, or an external camera. The Amazon Appstore recommends handling each possible case.
  • Check which preview sizes are supported by the Windows device's cameras and use those for taking pictures and showing previews.
  • Test your app's orientation for landscape devices like laptops and adjust the rotation accordingly.
  • If you encounter the "Your hardware doesn't support this application error", a legacy native library might exist in the Assets/Plugins/Android/lib/armeabi folder. When you build a native library, outputs for x86, armeabi, armeabi-v7a, and others are created by default. Support for armeabi was deprecated in Unity 5.x, so to avoid this error, don't use armeabi with Unity 5.x or higher.

For more details on how to support a camera in your app, see the Android developer documentation Camera orientations .

Support x86 ABI architecture

Most Windows devices use either Intel or AMD processors, which are x86-based. Windows Subsystem for Android uses Intel Bridge Technology to emulate Arm® applications on x86-based processors. The emulation layer induces a performance overhead, so for optimal performance, submit your application for both the x86-64 and Arm64 architectures. For details on how to support x86 ABI architecture, see the Android developer guide to Include x86 ABI architecture .

↑ Back to top

Handle unsupported features

Topics: Common features - unsupported | Common features - limited support| Disable unsupported ad SDKs | Handle unsupported Google Play services | Conditionally disable unsupported features | Unsupported feature tables

Some features and services that are available on mobile devices, aren't available on Windows Subsystem for Android, or might only have limited support. Requests to use unsupported features and services will fail when your app runs on Windows. This section describes how to handle unsupported features in your app.

To check if a feature or API is unsupported, you can go directly to the unsupported features tables here:

System features, including Wi-Fi management, brightness, and sound controls, aren't currently supported on Windows Subsystem for Android. If you have one of these features in your app and test on Windows, you might encounter issues when trying to control or access that feature. To check if a feature is unsupported, see Unsupported features.

Apps on Windows Subsystem for Android aren't allowed to change the system settings of Windows. If your app tries to switch the device Wi-Fi or sound, it will fail.

If these system dependencies are primary features of your app, the Amazon Appstore recommends waiting until these features are supported before trying to target Windows devices. If these are secondary features in your app, make sure exceptions are handled gracefully before targeting Windows devices.

Follow these recommendations to handle unsupported features:

  • For all features that are not supported by Windows Subsystem for Android, add android: required="false" to the <uses-feature> declaration in your app manifest. This applies to only the features already declared in your app manifest. For example, to disable NFC, your code might look like the following:
    <uses-feature android:name="android.hardware.nfc" android:required="false"/>
    
  • Disable features from your app that depend on hardware and software features that are unsupported on Windows Subsystem for Android. If you are using the same APK for your mobile app, use conditional logic to disable the unsupported features for Windows Subsystem for Android. For more details, see Conditionally disable unsupported features.

Common features - unsupported

The following features are currently unsupported on Windows Subsystem for Android.

Custom Wi-Fi hotspots. If your app creates a custom hotspot to host a LAN-based game or to transfer files, the feature might not work as expected as Wi-Fi hotspots aren't supported on Windows Subsystem for Android. However, if the devices running the apps are on the same network, your app should be able to create a host.

Connected audio devices. Connected audio devices such as earphones or headphones, cannot be detected by your app on Windows Subsystem for Android. If earphones are required in your app, and you use the isAudioConnected method for mandatory verification, skip or ignore this mandatory verification for your app on Windows Subsystem for Android.

System sound settings. Controlling system sound settings, such as volume, from within an app is not currently supported on Windows Subsystem for Android. To optimize sound settings in your app, see the Android developer guide Working with fixed-volume devices .

Picture-in-picture. Picture-in-picture (PiP) mode is not supported on Windows Subsystem for Android.

Common features - limited support

The following features currently have limited support on Windows Subsystem for Android.

Wi-Fi. Windows Subsystem for Android uses a virtual Wi-Fi interface and doesn't have visibility to direct Wi-Fi signals. Apps that scan for Wi-Fi signals won't see available Wi-Fi networks. Other Wi-Fi features like Wi-Fi hotspots and Wi-Fi Direct aren't currently supported on Windows Subsystem for Android. If your app is dependent on Wi-Fi scanning, or other Wi-Fi management features, don't target Windows devices as these features will fail.

Local network connection. If your app has the ability to connect to other devices that are running your app on the same network, this feature is supported, but advanced network settings on Windows Subsystem for Android must be enabled.

Video DRM. Widevine L3 DRM and Clearkey DRM are supported. Widevine L1, L2, and other video DRM formats (such as PlayReady) are not supported on Windows Subsystem for Android.

Audio recording. Microphone recording is supported on Windows Subsystem for Android. However, recording system audio is not currently supported.

Disable unsupported ad SDKs

If your app uses an ad SDK, it's important to test your app on Windows. To get started with testing your app on Windows, follow Microsoft's Test and debug  guide.

Some ad SDKs are incompatible with Windows Subsystem for Android. If the ad SDK is incompatible, the ads might not be fulfilled or delivered, which might cause issues in your app. If your ad SDK causes any unexpected behavior, follow these guidelines to disable it.

  • Disable all mobile ad units, including banners, interstitials, and ad rewards (which grant a user an in-app reward for watching an ad). The following example shows one way to conditionally set the layout based on whether ads are available.

    boolean adsDisabled = "Subsystem for Android(TM)".equals(Build.MODEL);
    
    if (adsDisabled) {
        setContentView(R.layout.layoutNoAds);
    } else {
        setContentView(R.layout.layoutWithAds);
    }
    
    val adsDisabled = "Subsystem for Android(TM)" == Build.MODEL
    
    if (adsDisabled) {
        setContentView(R.layout.layoutNoAds)
    } else {
        setContentView(R.layout.layoutWithAds)
    }
    
  • Disable features in your app that depend on ad rewards. For example, if a user must click a button to watch an ad for a reward, disable or remove the button.
  • If you are using the same APK for your mobile app, use conditional logic to make these changes only for Windows Subsystem for Android.

Handle unsupported Google Play services

Google Play services is not available on Windows Subsystem for Android. If your app uses Google Play services, make sure you have logic to launch an alternative service, or degrade gracefully if the service isn't available. Use the following guidelines.

Cloud messaging. If you've implemented both Firebase Cloud Messaging (FCM) and Amazon Device Messaging (ADM) in your app, use logic to check for and use ADM when it's available. For details, see Gracefully degrade if ADM is unavailable in the ADM documentation.

In-app purchasing. If you've implemented both Google In-App Billing (IAB) and Amazon In-App Purchasing (IAP) in your app, use logic to check for and use Amazon IAP when it's available. For details, see Implementing logic to mediate between Google Play Billing and IAP.

Maps. Google Maps and Amazon Maps are unavailable on Windows Subsystem for Android. For Windows, make sure to update your app to degrade gracefully.

Conditionally disable unsupported features

Whenever possible, check for feature availability rather than using device detection when conditionally disabling unsupported features. This allows you to maintain a common codebase while supporting multiple device types for your app.

To check for hardware or software features, use the hasSystemFeature() method from the Android PackageManager API. The following example shows how to detect if the device has an accelerometer available.

PackageManager packageManager = context.getPackageManager();
boolean hasAccelerometer = packageManager.hasSystemFeature(PackageManager.FEATURE_SENSOR_ACCELEROMETER);

if (hasAccelerometer) {
  // Accelerometer is available on this device.
} else {
  // Accelerometer is *NOT* available. Disable the feature.
}
val packageManager: PackageManager = context.packageManager
val hasAccelerometer: Boolean = packageManager.hasSystemFeature(PackageManager.FEATURE_SENSOR_ACCELEROMETER)

if (hasAccelerometer) {
  // Accelerometer is available on this device.
} else {
  // Accelerometer is *NOT* available. Disable the feature.
}

When possible, use the previous example to detect the specific feature. In cases where you are unable to check for a specific feature, use the following code.

if ("Subsystem for Android(TM)".equals(Build.MODEL)) {
  // App running on Windows Subsytem for Android
} else {
  // App *NOT* running on Windows Subsytem for Android
}
if ("Subsystem for Android(TM)" == Build.MODEL) {
  // App running on Windows Subsytem for Android
} else {
  // App *NOT* running on Windows Subsytem for Android
}

Unsupported feature tables

These tables list features which are currently unsupported on Windows Subsystem for Android.

Unsupported hardware features
Hardware feature App feature description
android.hardware.bluetooth Uses bluetooth to connect to other devices;
This feature appears available in WSA, but is currently inoperative
android.hardware.bluetooth_le Uses bluetooth to connect to other devices using Low Energy radio;
This feature appears available in WSA, but is currently inoperative
android.hardware.camera.autofocus Uses autofocus on camera
android.hardware.camera.flash Uses flash on camera
android.hardware.camera.level.full Uses FULL level image capture support on camera
android.hardware.consumerir Uses infrared (IR)
android.hardware.nfc Uses Near-Field Communication (NFC)
android.hardware.nfc.hce Uses NFC card emulation (deprecated)
android.hardware.telephony Uses telephony features, including radio with data communication services
android.hardware.telephony.cdma Uses Code Division Multiple Access (CDMA) network
android.hardware.telephony.gsm Uses Global System for Mobile Communications (GSM) network
android.hardware.type.automotive Uses automotive device screen UI
android.hardware.type.television Uses TV screen UI (deprecated)
android.hardware.usb.accessory Connects as a USB accessory;
This feature appears available in WSA, but is currently inoperative
android.hardware.usb.host Connects as a USB host;
This feature appears available in WSA, but is currently inoperative
android.hardware.sensor.accelerometer Uses accelerometer (detects device orientation)
android.hardware.sensor.barometer Uses barometer (detects air pressure)
android.hardware.sensor.compass Uses compass (determines direction)
android.hardware.sensor.gyroscope Uses gyroscope (detects rotation and twist)
android.hardware.sensor.light Uses light sensor
android.hardware.sensor.proximity Uses proximity sensor
android.hardware.sensor.stepcounter Uses step counter
android.hardware.sensor.stepdetector Uses step detector
Unsupported software features
Software feature App feature description
android.software.app_widgets Uses app widgets on the home screen;
WSA shows this feature as available, but it is currently always turned off
android.software.device_admin Uses device policy administration
android.software.home_screen Replaces device's Home screen
android.software.input_methods Uses a custom input method defined in InputMethodService
android.software.leanback Uses TV screen UI
android.software.live_tv Streams live TV
android.software.live_wallpaper Uses animated wallpapers
android.software.managed_users Allows secondary users and managed profiles
android.software.midi Connects to MIDI devices
android.software.sip Uses Session Initiation Protocol (SIP), which supports video conferencing and instant messaging
android.software.sip.voip Uses Voice Over Internet Protocol (VoIP), which supports two-way video conferencing
Picture-in-picture Allows small viewing window, usually video playback, to overlay screen
Amazon web apps Web-based application
Unsupported APIs
API Alternative
Google Play In-App Billing Use the Amazon In-App Purchasing API.
See Migration Guide.
Google Cloud Messaging Use Amazon Device Messaging.
See Migration Guide.
Google Maps None. Unsupported on Windows Subsystem for Android.

↑ Back to top



Last updated: Nov 18, 2022