Develop

Meta VR OS Utility Library Integration Guide

Updated: Sep 14, 2026

The Meta VR OS Utility Library helps your Android app adapt to Horizon OS at runtime. It answers two questions that a single build shared across Meta Quest and other Android platforms has to ask: is this app running on Horizon OS, and which Meta VR OS SDK version does this device provide?

The library is written in Java, so you can call it from Java, Kotlin, and other languages that interoperate with Java. It can coexist in a project alongside other Meta SDKs.

The following sections explain what the library provides, how to add it to an app project, and how to call it.

How the Utility Library relates to the JSDK

The Meta VR OS Java Software Development Kit (JSDK) exposes the Horizon OS system APIs themselves. Horizon OS supplies their implementations at runtime, so you add the JSDK to your build as a compile-time-only dependency and never package it into your app.

This Utility Library works the other way around. It is a static library that compiles into your app, and it wraps the underlying version APIs behind calls that keep working on Horizon OS versions released before those APIs existed - and on devices that do not run Horizon OS at all. That is what makes it useful from a single build artifact.

Add the Utility Library when you ship one build for Horizon OS and other Android platforms. Add the JSDK when you need a Horizon OS system API. Projects can use both.

What the library provides

API	Purpose
`metavrx.os.HorizonOsDetector.isOnHorizonOs(Context)`	Reports whether the app is running on Horizon OS.
`metavrx.os.MetaVrOsSdkVersion.isAtOrAbove(int)`	Reports whether the device’s Meta VR OS SDK version is at or above a version you name.

See the API reference documentation for API details.

Add the library to your project

The Utility Library is published to Maven Central⁠ as com.meta.metavrx.util:util. It carries its own version number, separate from the Meta VR OS SDK version, so declare that version yourself.

These instructions assume your project uses the Kotlin DSL (build.gradle.kts) for the Build configuration language option, with a version catalog at gradle/libs.versions.toml.

Step 1: Add the Maven Central repository

In your project’s settings.gradle.kts file, ensure mavenCentral() appears under dependencyResolutionManagement.repositories:

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()   // Required for the Utility Library
    }
}

Step 2: Add the library to your version catalog

In gradle/libs.versions.toml, add the Utility Library entry under [libraries]:

[libraries]
metavrx-util = { group = "com.meta.metavrx.util", name = "util", version = "1.0.0" }

Replace 1.0.0 with the version you want to use.

Step 3: Add the dependency to your modules

In each module that calls the Utility Library, add an implementation dependency in the module’s build.gradle.kts file (for example, app/build.gradle.kts):

dependencies {
    implementation(libs.metavrx.util)
}

Use implementation, not compileOnly. Horizon OS does not supply this library at runtime, so it has to ship inside your app.

Run Gradle Sync to apply the change.

Declare the dependency without a version catalog

If your project does not use a version catalog, name the coordinates directly. For Kotlin DSL (app/build.gradle.kts):

dependencies {
    implementation("com.meta.metavrx.util:util:1.0.0")
}

For Groovy (app/build.gradle):

dependencies {
    implementation 'com.meta.metavrx.util:util:1.0.0'
}

Detect Horizon OS at runtime

Call HorizonOsDetector.isOnHorizonOs() and pass it an Android Context⁠:

import android.content.Context
import metavrx.os.HorizonOsDetector

fun renderScene(context: Context) {
    if (HorizonOsDetector.isOnHorizonOs(context)) {
        // Run the code path for Horizon OS
    } else {
        // Run the code path for other Android platforms
    }
}

Guard the entire call chain into an unsupported dependency with this check, so its classes never load on Horizon OS.

Detection is not reliable on first-generation Meta Quest devices running older Horizon OS versions, or on devices that predate them.

Runtime detection is one of two approaches to running a single codebase on Horizon OS and other Android platforms. For the alternative, which strips unsupported code from the Horizon OS build at compile time, see product flavors.

Check the Meta VR OS SDK version

Horizon OS reports an integer Meta VR OS SDK version, and each API requires a minimum version of it. Call MetaVrOsSdkVersion.isAtOrAbove() to branch on that number:

import metavrx.os.MetaVrOsSdkVersion

if (MetaVrOsSdkVersion.isAtOrAbove(207)) {
    // Call the API introduced in Meta VR OS SDK version 207
} else {
    // Fall back to behavior available on earlier versions
}

isAtOrAbove() supports version numbers 61 and above. It returns false on a device whose Meta VR OS SDK version is below the number you pass, including a device old enough that the version APIs it wraps are absent. Passing a version number below 61 to a device where neither version API exists throws UnsupportedOperationException.

For how these version numbers are assigned, how to pick the ones your app declares in its manifest, and how to pair a runtime check with the uses-metavr-sdk Android manifest element, see Meta VR OS SDK versioning.

Java is a registered trademark of Oracle and/or its affiliates.