Develop

Meta VR OS Java Software Development Kit Integration Guide

Updated: Oct 13, 2026

The following sections explain how to integrate the Meta VR OS Java Software Development Kit (JSDK) into a project using Android Studio. For an introduction to the JSDK, see the Meta VR OS Java Software Development Kit Overview.

Prerequisites

Android Studio 2025.2.* or newer
Android Gradle Plugin 8.9.0 or higher
Gradle 8.13 or higher
A physical Meta VR device running Horizon OS
- Note: Each API requires a minimum version of Horizon OS. See the API reference documentation for details.

Alternative Android Studio configurations may function, but are not officially supported.

These instructions assume your project uses the Kotlin DSL (build.gradle.kts) for the Build configuration language option.

Project Setup

The JSDK is provided as an Android Archive (AAR) package containing API stubs and Javadoc documentation. Since the JSDK is an operating system library, add the JSDK AAR to your app as a build-time-only dependency. Avoid packaging it into your app’s build. The full API implementations are supplied to your app by Horizon OS at runtime.

Add the JSDK AAR as a build dependency using one of these methods:

Option A: Gradle dependency (recommended): Configure your project to download the JSDK AAR from Maven Central.
Option B: Manual integration: Download the JSDK AAR manually and add it to your project using Android Studio’s Project Structure tool or by directly modifying your project’s Gradle configuration files.

Option A: Gradle Dependency

This option configures the project to fetch the JSDK from Maven Central automatically.

Step A1: Add Maven Central Repository

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

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()   // Required for JSDK
    }
}

Step A2: Add JSDK to Library Catalog

The JSDK is published on Maven Central⁠ as com.meta.metavr:metavr-os-jsdk:207.

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

[libraries]
metavr-os-jsdk = { group = "com.meta.metavr", name = "metavr-os-jsdk", version = "207" }

Replace the version with the JSDK version you wish to use. If you import the MetaVRX BOM (com.meta.metavrx:metavrx-bom), omit the version, as the BOM manages the JSDK version for you.

Step A3: Add JSDK Dependency to Modules

In each module needing access to JSDK APIs, add a compileOnly dependency in the module’s build.gradle.kts file (for example, app/build.gradle.kts):

dependencies {
    compileOnly(libs.metavr.os.jsdk)
}

Option B: Manual Integration

Use this method if you work offline or do not want to use Maven Central.

Step B1: Download JSDK AAR and Add to Project

Download the latest JSDK AAR from the official distribution page, then place it into your project’s directory structure.

For example, in a project whose main module is named app, the AAR could be added to the project under <project root>/app/lib/.

Step B2: Add JSDK Dependency

Add the JSDK as a dependency using one of these options:

Option 1: Use Android Studio’s Project Structure tool
Option 2: Modify Gradle build configuration files manually

Option 1: Using Android Studio Project Structure

This section is based on recent Android Studio versions, such as Otter 2, on macOS. User interface and menu options may vary depending on your Android Studio version and operating system.

Open File > Project Structure.
Select the Dependencies tab.
Under Modules, select the module from which you want to invoke JSDK APIs (for example, app).
Click the + button in the Declared Dependencies section.
Select JAR/AAR Dependency.
In the dialog’s Step 1 field, enter the relative path to the JSDK AAR file. For example, if your module is named app and the AAR is under <project root>/app/lib, enter lib/metavr-os-jsdk-207.aar.
In the dialog’s Step 2 field, manually enter compileOnly. This option may not appear by default in the dropdown menu but can be selected via autocomplete once you start typing.
Click OK to confirm.

Repeat steps 3-8 for each module from which you want to access JSDK.

Option 2: Modify Gradle Build Files Manually

For each module from which you want to invoke JSDK APIs, open the module’s build.gradle.kts file (for example, <project root>/app/build.gradle.kts).

In the dependencies section, add a compileOnly entry for the AAR, for example:

compileOnly(files("lib/metavr-os-jsdk-207.aar"))

Run Gradle Sync to apply the change.

Configuring your app’s manifest

To access the JSDK APIs, your app must declare the uses-metavr-sdk element in its manifest. See the documentation on Meta VR OS SDK versioning for more information.