Requiring Minimum OS Versions

Updated: Jan 28, 2026

Applications may require a minimum version of the Horizon Operating System (HzOS) to launch. This restriction can be added:

Implicitly, by using a feature available only in a newer HzOS version. For example, if your application supports Quest 3, it requires a minimum HzOS version of v56, the first version that supports Quest 3.

Explicitly, by defining a minimum HzOS version in your app’s uses-horizonos-sdk meta-data element. This is useful if your app has implicit dependencies on a specific HzOS version, such as attempting to launch a system package with an intent supported only in a newer HzOS version, or for multiplayer applications that want to ensure all players have the latest security updates.

Handling API version compatibility

The Horizon Platform SDK evolves over time, with new APIs being added in each HzOS release. When your app calls an API that was introduced in a newer HzOS version than what the device is running, the API returns error code ProviderOperationNotSupported (1003).

You have two options for handling this:

Gracefully handle the error - Allow your app to run on older devices and handle the case when the API is not available

Require a minimum HzOS version - Prevent your app from being installed on devices that don’t support the APIs you need

Option 1: Gracefully handle the error

If the API is optional for your app’s functionality, you can call it and handle the error when it’s not supported. This allows your app to work on older devices while still taking advantage of newer features when available.

import horizon.platform.iap.Iap
import horizon.platform.iap.IapException

try {
    val products = Iap.getProductsBySku(listOf("product_sku_1"))
    // Use the products
} catch (e: IapException) {
    if (e.code == 1003) {
        // API not available on this device - use fallback behavior
        Log.w(TAG, "API not supported on this HzOS version: ${e.message}")
    } else {
        // Handle other errors
        Log.e(TAG, "IAP error: ${e.displayableMessage}")
    }
}

When to use this approach:

The API provides optional or enhanced functionality

You want maximum device compatibility

Your app can provide a reasonable fallback experience

Option 2: Require a minimum HzOS version

If your app requires certain APIs to function properly, you can declare a minimum HzOS version in your AndroidManifest.xml. This prevents your app from being installed or upgraded on devices running older HzOS versions. See the Requiring a minimum HzOS version section below for details.

When to use this approach:

Your app’s core functionality depends on specific APIs

You don’t want to maintain fallback code paths

You’re targeting newer devices with specific capabilities

Determining the required version for Platform SDK APIs

Each API in the Horizon Platform SDK documentation indicates when it was introduced. Look for notes like:

This API was added in HzOS v83.

To determine the minimum version for your app:

Identify all the Platform SDK APIs your app uses

Find the highest version number among those APIs

Use that version as your minSdkVersion

Determining the HzOS versions used by your app’s users

In your app’s Developer Dashboard⁠, access your App analytics pages. These pages contain dashboards, such as Performance analytics, which you can break down by the HzOS versions of your app’s users.

Your app can also determine the HzOS version of the currently running headset by calling the following code in a Java plugin built with your app:


PackageManager pm = context.getPackageManager();
try {
	return pm.getPackageInfo("com.oculus.systemdriver", PackageManager.GET_META_DATA).versionName;
} catch (Exception e) { return e.toString(); }

Requiring a minimum HzOS version to use your app

Some settings and features in your app implicitly require a minimum HzOS version. For example:

Setting android:minSdkVersion sets the minimum HzOS version to the first version that supports that SDK.

Adding a device to com.oculus.supportedDevices sets the minimum HzOS version to the first version that supports that device.

Using the Android Camera2 API for direct access to camera frames sets the minimum HzOS version to v74.

When multiple features apply, your app requires the highest minimum HzOS version among all relevant features. For example:

Using multiple Platform SDK APIs that were introduced in different HzOS versions requires the highest version among them.

You can also explicitly specify a minimum HzOS version by adding the uses-horizonos-sdk meta-data element to your app’s AndroidManifest.xml file:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:horizonos="http://schemas.meta.com/sdk/horizonos">

    <horizonos:uses-horizonos-sdk
        horizonos:minSdkVersion="83"
        horizonos:targetSdkVersion="83" />

    <!-- rest of your manifest -->
</manifest>

Replace 83 with the minimum HzOS version required by the APIs your app uses.

When you declare a minSdkVersion:

The Meta Horizon Store will only show your app to users on compatible devices

Users on older devices won’t be able to install or update to this version

You can safely call the APIs without error handling for version compatibility

Checking the minimum HzOS version for your app

To check the minimum HzOS version for your app, upload a build to the Developer Dashboard and view the build details in the Distribution > Build page for your app. See uploading a build to your Developer Dashboard for instructions on uploading the build.

The Developer Dashboard shows the reason it selected a specific “Minimum OS version” for your app as shown in the following screenshots.