Develop

Migrate from the OVR Platform SDK to the VR Platform SDK

Updated: Oct 26, 2026

Overview

This guide moves an Android app from the OVR Platform SDK to the VR Platform SDK. The OVR Platform SDK is the Maven artifact com.meta.horizon.platform.ovr:android-platform-sdk, with the Java package com.meta.horizon.platform.ovr. The Java setup guide calls it the Android Platform SDK. The VR Platform SDK is the Kotlin SDK published under the Maven group com.meta.horizon.platform.sdk. This page describes VR Platform SDK 0.2.2.
Apps already built with the OVR Platform SDK keep working, because the OS on the device supplies the platform implementation. Migration is a source change: you swap the dependencies, replace initialization, and convert each call.

Prerequisites

  • An Android app that uses the OVR Platform SDK, and your app ID. To find the app ID, see Set up for platform development with Kotlin.
  • Kotlin Gradle plugin 2.1 or later. The 0.2.2 libraries are built with Kotlin 2.1.
  • Kotlin call sites. The VR Platform SDK is a Kotlin coroutines API: single-result calls are suspend functions and events are Flows, so call it from Kotlin. The SDK does not bring in kotlinx-coroutines, so add it to your app, as Step 2 shows.
  • mavenCentral() in your Gradle repositories.
  • Adding these libraries raises your app’s minimum Horizon OS SDK version to 77, or to 79 if you add iap-kotlin or user-age-category-kotlin. The core-kotlin library declares horizonos:minSdkVersion="77" in its uses-horizonos-sdk element, and this value merges into your app manifest. Most methods need a later Horizon OS than this floor, and each section of the Call mapping gives its minimum. On an older OS, such a call fails with status code 1003 (ProviderOperationNotSupported), so require that version in your manifest or handle the code. For more information, see Requiring minimum OS versions.

Steps

1. Check for features without an equivalent

Compare the OVR Platform SDK features your app uses with the list in Features without an equivalent. Decide what to do before Step 2, because Step 2 removes the OVR Platform SDK.
  • If your app depends on a feature that has no equivalent, stay on the OVR Platform SDK until you have a replacement. Existing apps keep working.
  • If your app checks entitlement through the OVR Platform SDK, move the check to the Entitlement check server APIs before you remove the OVR Platform SDK.
  • If your app uses Rich Presence, plan the move to Group Presence. For the replacement calls, see Rich Presence.
  • Together, Call mapping and that list cover every method of the OVR classes that the Call mapping introduction names. For a class in Other packages, check the Methods column. If there is no match, the call has no equivalent.
You now know which features need a different solution before you continue.

2. Replace the dependencies

In your app module’s Gradle file, remove the line that declares com.meta.horizon.platform.ovr:android-platform-sdk. Then add core-kotlin, one artifact for each feature your app uses, and kotlinx-coroutines. The samples on this page use lifecycleScope, so this example also adds lifecycle-runtime-ktx.
// app/build.gradle.kts
dependencies {
    implementation("com.meta.horizon.platform.sdk:core-kotlin:0.2.2")
    implementation("com.meta.horizon.platform.sdk:users-kotlin:0.2.2")
    implementation("com.meta.horizon.platform.sdk:leaderboards-kotlin:0.2.2")
    implementation("com.meta.horizon.platform.sdk:group-presence-kotlin:0.2.2")
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.9.0")
    implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.6.1")
}
The feature artifacts are:
  • Users: users-kotlin
  • Achievements: achievements-kotlin
  • Leaderboards: leaderboards-kotlin
  • Group Presence: group-presence-kotlin
  • In-app purchases: iap-kotlin
  • User age category: user-age-category-kotlin
Each feature artifact depends on core-kotlin. To declare the artifacts in a version catalog instead, see Set up for platform development with Kotlin.
If your app uses the Horizon Billing Compatibility SDK, versions before 2.0.0 depend on the OVR Platform SDK artifact. Use version 2.0.0 or later; see Horizon Billing Compatibility SDK.
Sync the project. The build now fails at each OVR call site until you convert it in the following steps. This is expected. To find every call site to convert, search your code for com.meta.horizon.platform.ovr imports.
Your Gradle file now declares the VR Platform SDK artifacts and no longer declares the OVR Platform SDK artifact.

3. Replace initialization

The OVR Platform SDK initializes through Core:
import com.meta.horizon.platform.ovr.Core;

Core.asyncInitialize(appID, context);
The VR Platform SDK initializes through HorizonServiceConnection.connect(). Pass your app ID to connect(). The VR Platform SDK does not read the app ID from the OVR manifest entry (com.meta.horizon.platform.ovr.OCULUS_APP_ID). Call it once, before you create any feature client, for example in your activity’s onCreate().
import androidx.lifecycle.lifecycleScope
import horizon.core.android.driver.coroutines.HorizonServiceConnection

private const val APPLICATION_ID = "YOUR_APP_ID"

// In your activity's onCreate()
HorizonServiceConnection.connect(APPLICATION_ID, applicationContext, lifecycleScope)
  • connect() is not a suspend function and returns nothing. It has no success callback.
  • Move work that ran in your asyncInitialize() success handler to your first feature call, because feature calls wait until the connection is ready.
  • Creating a feature client before you call connect() throws HzPlatformNotInitializedException. In contrast, calling a feature method after connect() but before the connection is ready waits until initialization completes. If initialization fails, that call throws its feature exception.
  • Calling connect() again reuses the existing connection. The app ID from the first call stays in effect.
  • The connection closes when a scope you passed to connect() ends. Use a scope that does not end when your app moves to the background, such as lifecycleScope in onCreate() or a viewModelScope.
Your code now calls connect() before it creates any feature client.

4. Convert callbacks to suspend calls

Use Call mapping to find the replacement for each OVR call.
OVR calls return a Request<T>, and you attach onSuccess() and onError() handlers. VR Platform SDK calls are instance methods on a feature client, such as Users(). Calls that return a single result are suspend functions that return the result directly. Call them from a coroutine and catch the feature exception.
import android.util.Log
import androidx.lifecycle.lifecycleScope
import horizon.platform.users.Users
import horizon.platform.users.UsersException
import kotlinx.coroutines.launch

// In your activity, after connect()
lifecycleScope.launch {
    try {
        val user = Users().getLoggedInUser()
        Log.i("Platform", "Logged-in user ID: ${user.id}")
    } catch (e: UsersException) {
        Log.e("Platform", "${e.requestName} failed with code ${e.code}")
    }
}
The remaining samples on this page omit the android.util.Log, androidx.lifecycle.lifecycleScope, and kotlinx.coroutines.launch imports, and imports that an earlier sample shows.
To handle errors:
  • Each feature throws its own exception: UsersException, AchievementsException, LeaderboardsException, GroupPresenceException, IapException, or UserAgeCategoryException. Each class is in its feature package, for example horizon.platform.users.UsersException.
  • Every feature exception extends horizon.core.android.common.HzPlatformSdkException. Read code, requestName, and displayableMessage where you read getCode() and getDisplayableMessage() on the OVR Error object.
  • Branch on code rather than on the message text.
  • Flows and paged calls report errors in a different way, as the following steps describe.
Each single-result OVR call is now a suspend call inside a coroutine, with a catch for its feature exception.

5. Replace notification callbacks with flows

The OVR Platform SDK delivers events through static setXxxNotificationCallbacks(onSuccess, onError) methods. The VR Platform SDK returns a Kotlin Flow instead:
  • GroupPresence.setJoinIntentReceivedNotificationCallbacks() becomes GroupPresence().joinIntentReceived(), a Flow<GroupPresenceJoinIntent>.
  • GroupPresence.setInvitationsSentNotificationCallbacks() becomes GroupPresence().invitationsSent(), a Flow<LaunchInvitePanelFlowResult>.
import horizon.platform.grouppresence.GroupPresence
import horizon.platform.grouppresence.GroupPresenceException

lifecycleScope.launch {
    try {
        GroupPresence().joinIntentReceived().collect { intent ->
            Log.i("Platform", "Join ${intent.destinationApiName}, lobby ${intent.lobbySessionId}")
        }
    } catch (e: GroupPresenceException) {
        Log.e("Platform", "Join intent failed with code ${e.code}")
    }
}
  • The flow starts listening when you collect it and stops when the collecting scope is cancelled.
  • An error is thrown out of collect as a GroupPresenceException. Catch it around collect, or use the catch operator.
Each OVR notification callback is now a collect on the matching flow, with a catch for the feature exception.
For a complete working implementation, see the Group Presence sample overview.

6. Replace array results with paged results

OVR list calls return an array object, such as UserArray, that you read with getElements(), hasNextPage(), and getNextPage(). In the VR Platform SDK, list calls return PagedResults<T>, except where the Call mapping tables note otherwise. These methods are not suspend functions, and they take a CoroutineScope as their first parameter.
import horizon.core.android.common.pagination.PageFetchException
import horizon.core.android.common.pagination.ext.initialPage
import horizon.core.android.common.pagination.ext.pages
import horizon.platform.users.Users

val friends = Users().getLoggedInUserFriends(lifecycleScope)
lifecycleScope.launch {
    try {
        friends.initialPage()
        friends.pages.collect { page -> Log.i("Platform", "Loaded ${page.contents.size} friends") }
    } catch (e: PageFetchException) {
        Log.e("Platform", "Fetching friends failed", e.cause)
    }
}
  • initialPage(), nextPage(), previousPage(), and pages are extensions in horizon.core.android.common.pagination.ext.
  • Always await initialPage() in a try/catch before you collect pages. If the first fetch fails, pages never emits or throws. The error comes only from initialPage().
  • To load more, call nextPage() from a coroutine. It returns false when there is no next page, and pages emits the new page.
  • OVR array methods map as follows: getElements() becomes page.contents, hasNextPage() stays hasNextPage(), getNextPage() becomes nextPage(), and LeaderboardEntryArray.getPreviousPage() becomes previousPage().
  • fetchedPages holds only the latest page. Collect pages to keep earlier pages.
  • A failed page fetch throws PageFetchException from initialPage() and nextPage(), not the feature exception. The feature exception is its cause.
Each paged call now awaits initialPage() inside a try/catch for PageFetchException before it collects pages. For more patterns, see Pagination.

7. Change user IDs from long to String

OVR user IDs are long values. VR Platform SDK user IDs are String values:
  • User.getID() returns long. User.id is a String holding the same ID as decimal text, so an ID you stored as a long converts with toString().
  • Core.getLoggedInUserID() becomes Users().getLoggedInUser().id, which is a String.
  • Parameters that took long or long[] now take String or List<String>. Examples are Users().get(userId), GroupPresence().sendInvites(userIds), and Leaderboards().getEntriesByIds(..., userIds).
import horizon.platform.leaderboards.Leaderboards
import horizon.platform.leaderboards.enums.LeaderboardStartAt
import kotlinx.coroutines.flow.first

lifecycleScope.launch {
    try {
        val userId: String = Users().getLoggedInUser().id
        val results = Leaderboards().getEntriesByIds(lifecycleScope, "MY_LEADERBOARD",
            limit = 1, startAt = LeaderboardStartAt.Top, userIds = listOf(userId))
        results.initialPage()
        results.pages.first().contents.firstOrNull()?.let { Log.i("Platform", "Rank ${it.rank}") }
    } catch (e: UsersException) {
        Log.e("Platform", "Getting the user failed", e)
    } catch (e: PageFetchException) {
        Log.e("Platform", "Fetching the entry failed", e.cause)
    }
}
Update any code that stores or compares user IDs as Long to use String. Your code now holds every user ID as a String.

8. Verify the migration

  1. Build the app. The build succeeds with no com.meta.horizon.platform.ovr imports left.
  2. Run the app on a device.
  3. Confirm that Users().getLoggedInUser() returns a user and that a paged call, such as getLoggedInUserFriends(), returns a first page.
  4. If you use Group Presence, follow an invite and confirm that a join intent arrives.
Your app now builds and runs on the VR Platform SDK.

Call mapping

Together with Features without an equivalent, this section lists every public method of the OVR Core, Users, Achievements, Leaderboards, GroupPresence, IAP, UserAgeCategory, and RichPresence classes. In the Kotlin column, a call such as Users().getLoggedInUser() is an instance method on a feature client. Methods that take coroutineScope return PagedResults<T>. Methods that return a Flow, and connect(), are not suspend. The other Kotlin methods are suspend functions.

Core

OVR Platform SDK (Java)VR Platform SDK (Kotlin)Notes
Core.asyncInitialize(appID, context), Core.initialize(appID, context)
HorizonServiceConnection.connect(applicationId, context, scope)
Not suspend; returns nothing.
Core.getLoggedInUserID()
Users().getLoggedInUser().id
Returns a String. getLoggedInUser() is suspend and needs Horizon OS v85.

Users

Minimum Horizon OS: v79 for get() and getAccessToken(); v85 for the other methods.
OVR Platform SDK (Java)VR Platform SDK (Kotlin)Notes
Users.getLoggedInUser()
Users().getLoggedInUser()
Returns User.
Users.get(long userID)
Users().get(userId: String)
ID is a String.
Users.getLoggedInUserFriends()
Users().getLoggedInUserFriends(coroutineScope)
Paged.
Users.getBlockedUsers()
Users().getBlockedUsers(coroutineScope)
Paged.
Users.getAccessToken(), Users.getUserProof()
Users().getAccessToken(), Users().getUserProof()
No change.
Users.getOrgScopedID(long)
Users().getOrgScopedId(userId: String)
Renamed. ID is a String.
Users.launchBlockFlow(long), Users.launchUnblockFlow(long)
Users().launchBlockFlow(userId: String), Users().launchUnblockFlow(userId: String)
ID is a String.
Users.getLinkedAccounts(UserOptions)
Users().getLinkedAccounts(userOptions)
Returns List<LinkedAccount>. Not paged. Build options with UserOptions.builder().
Users.getSdkAccounts()
Users().getSdkAccounts()
Returns List<SdkAccount>. Not paged.

Achievements

Minimum Horizon OS: v85.
OVR Platform SDK (Java)VR Platform SDK (Kotlin)Notes
Achievements.unlock(String)
Achievements().unlock(name)
Returns AchievementUpdate.
Achievements.addCount(String, long)
Achievements().addCount(name, count: ULong)
Count is a ULong.
Achievements.addFields(String, String)
Achievements().addFields(name, fields)
No change.
Achievements.getAllDefinitions(), Achievements.getAllProgress()
Achievements().getAllDefinitions(coroutineScope), Achievements().getAllProgress(coroutineScope)
Paged.
Achievements.getDefinitionsByName(String[]), Achievements.getProgressByName(String[])
Achievements().getDefinitionsByName(coroutineScope, names), Achievements().getProgressByName(coroutineScope, names)
Paged. Names are a List<String>.

Leaderboards

Minimum Horizon OS: v83.
OVR Platform SDK (Java)VR Platform SDK (Kotlin)Notes
Leaderboards.writeEntry(String, long, byte[], boolean)
Leaderboards().writeEntry(leaderboardName, score, extraData, forceUpdate)
Returns LeaderboardUpdateStatus. Read didUpdate. extraData and forceUpdate are optional.
Leaderboards.writeEntryWithSupplementaryMetric(...)
Leaderboards().writeEntryWithSupplementaryMetric(leaderboardName, score, supplementaryMetric, extraData, forceUpdate)
Returns LeaderboardUpdateStatus.
Leaderboards.getEntries(String, int, LeaderboardFilterType, LeaderboardStartAt)
Leaderboards().getEntries(coroutineScope, leaderboardName, limit, filter, startAt)
Paged.
Leaderboards.getEntriesAfterRank(String, int, long)
Leaderboards().getEntriesAfterRank(coroutineScope, leaderboardName, limit, afterRank: ULong)
Paged. Rank is a ULong.
Leaderboards.getEntriesByIds(String, int, LeaderboardStartAt, long[])
Leaderboards().getEntriesByIds(coroutineScope, leaderboardName, limit, startAt, userIds)
Paged. IDs are a List<String>.
Leaderboards.get(String)
Leaderboards().get(coroutineScope, leaderboardName)
Paged.

Group presence

Minimum Horizon OS: v79 for set(), clear(), the individual setters, getInvitableUsers(), and joinIntentReceived(); v85 for the other methods in this table.
OVR Platform SDK (Java)VR Platform SDK (Kotlin)Notes
GroupPresence.set(GroupPresenceOptions), with new GroupPresenceOptions() and setXxx() methods
GroupPresence().set(GroupPresenceOptions.builder().withXxx(...).build())
Options use a builder with withXxx() methods.
GroupPresence.clear()
GroupPresence().clear()
No change.
GroupPresence.setDestination(), setIsJoinable(), setLobbySession(), setMatchSession(), setDeeplinkMessageOverride()
Same names on GroupPresence()
No change.
GroupPresence.setJoinIntentReceivedNotificationCallbacks(onSuccess, onError)
GroupPresence().joinIntentReceived()
Returns Flow<GroupPresenceJoinIntent>.
GroupPresence.setInvitationsSentNotificationCallbacks(onSuccess, onError)
GroupPresence().invitationsSent()
Returns Flow<LaunchInvitePanelFlowResult>.
GroupPresence.launchInvitePanel(InviteOptions)
GroupPresence().launchInvitePanel(options)
Build options with InviteOptions.builder(). Returns InvitePanelResultInfo.
GroupPresence.sendInvites(long[])
GroupPresence().sendInvites(userIds: List<String>)
Returns SendInvitesResult.
GroupPresence.getInvitableUsers(InviteOptions)
GroupPresence().getInvitableUsers(coroutineScope, options)
Paged.
GroupPresence.getSentInvites()
GroupPresence().getSentInvites(coroutineScope)
Paged.
GroupPresence.launchRejoinDialog(), launchRosterPanel(), launchMultiplayerErrorDialog()
Same names on GroupPresence()
Build RosterOptions and MultiplayerErrorOptions with builder() and withXxx() methods. Suggested users are a List<String>.

In-app purchases

The OVR class IAP becomes the feature client Iap(). Minimum Horizon OS: v81.
OVR Platform SDK (Java)VR Platform SDK (Kotlin)Notes
IAP.getProductsBySKU(String[])
Iap().getProductsBySku(coroutineScope, skus: List<String>)
Method renamed. Paged.
IAP.getViewerPurchases()
Iap().getViewerPurchases()
Returns List<Purchase>. Not paged; see Features without an equivalent.
IAP.getViewerPurchasesDurableCache()
Iap().getViewerPurchasesDurableCache()
Returns List<Purchase>. Not paged; see Features without an equivalent.
IAP.launchCheckoutFlow(String)
Iap().launchCheckoutFlow(sku)
Returns Purchase.
IAP.consumePurchase(String)
Iap().consumePurchase(sku)
No change.

User age category

Minimum Horizon OS: v81.
OVR Platform SDK (Java)VR Platform SDK (Kotlin)Notes
UserAgeCategory.get()
UserAgeCategory().get()
Returns UserAccountAgeCategory. Read ageCategory, an AccountAgeCategory: Unknown, Ch, Tn, or Ad.

Other packages

These OVR Platform SDK classes also have a feature client in VR Platform SDK 0.2.2. The clients follow the same patterns as the other feature clients: suspend calls and flows. The Methods column lists each client’s methods in 0.2.2.
OVR classVR Platform SDK artifactKotlin clientMethodsMinimum Horizon OSDocumentation
AbuseReport
abuse-report-kotlin
AbuseReport()
reportRequestHandled(), reportButtonPressed() (flow)
v201
Application
application-kotlin
Application()
cancelAppDownload(), checkAppDownloadProgress(), getVersion(), installAppUpdateAndRelaunch(), launchOtherApp(), startAppDownload()
v79 for getVersion() and launchOtherApp(), v85 for the others
ApplicationLifecycle
application-lifecycle-kotlin
ApplicationLifecycle()
getLaunchDetails(), logDeeplinkResult(), launchIntentChanged() (flow)
v78 for getLaunchDetails() and launchIntentChanged(), v83 for logDeeplinkResult()
AssetFile
asset-file-kotlin
AssetFile()
deleteById(), deleteByName(), downloadById(), downloadByIdList(), downloadByName(), downloadByNameList(), downloadCancelById(), downloadCancelByName(), getList(), statusById(), statusByName(), downloadUpdate() (flow)
v201
DeviceApplicationIntegrity
device-application-integrity-kotlin
DeviceApplicationIntegrity()
getIntegrityToken()
v85
LanguagePack
language-pack-kotlin
LanguagePack()
getCurrent(), setCurrent()
v85
Notifications
notifications-kotlin
Notifications()
deviceNotification()
v83
Notifications.markAsRead() has no equivalent. See Features without an equivalent.

Rich presence

Rich Presence is deprecated in the VR Platform SDK in favor of Group Presence. If your app calls RichPresence.set() or RichPresence.clear(), move to GroupPresence().set() and GroupPresence().clear(), which are suspend calls. RichPresence.getDestinations() becomes GroupPresence().getDestinations(coroutineScope), which needs Horizon OS v201 and returns PagedResults, so handle it as Step 6 describes.

Features without an equivalent

VR Platform SDK 0.2.2 for Kotlin has no equivalent for these OVR Platform SDK features. The list covers every OVR Platform SDK feature class, such as Voip or Challenges, that has no VR Platform SDK 0.2.2 counterpart. Together, this list and Call mapping cover every method of the OVR classes that the Call mapping introduction names. For a class in Other packages, check the Methods column. If there is no match, the call has no equivalent.
  • Entitlement check: VR Platform SDK 0.2.2 for Kotlin has no entitlement check API.
  • Parties, VoIP, Media, and Cowatching: If your app uses any of these from the OVR Platform SDK, stay on the OVR Platform SDK until you have a replacement.
  • Friend requests: If your app calls Users.launchFriendRequestFlow(), stay on the OVR Platform SDK until you have a replacement.
  • Avatar, Challenges, and Push notifications: VR Platform SDK 0.2.2 for Kotlin has no API for the OVR Avatar, Challenges, and PushNotification classes. If your app uses them, stay on the OVR Platform SDK until you have a replacement.
  • Marking notifications as read: If your app calls Notifications.markAsRead(), stay on the OVR Platform SDK until you have a replacement.
  • Core lifecycle and message pump: Core.isInitialized(), Core.shutdown(), Core.popSDKMessage(), Core.httpGetWithMessageType(), PlatformInitializeOptions, and Request.runCallbacks() have no equivalent. suspend calls and flows replace the message pump. To end the connection, cancel the scope you pass to connect().
  • Paging details: PurchaseArray.getNextPage() has no equivalent. The 0.2.2 calls Iap().getViewerPurchases() and Iap().getViewerPurchasesDurableCache() return a List<Purchase> from a single response and cannot fetch more pages. The array methods LeaderboardEntryArray.getTotalCount(), getNextUrl(), and getPreviousUrl() also have no equivalent.

Troubleshooting

Creating a feature client throws HzPlatformNotInitializedException

Symptom: Your app crashes with HzPlatformNotInitializedException when it creates Users(), Iap(), or another feature client.
Solution: Call HorizonServiceConnection.connect() before you create any feature client. A property initializer in your activity runs before onCreate(). Create the client after the connect() call, for example with by lazy.

A catch block for the feature exception misses paged errors

Symptom: A catch for UsersException around getLoggedInUserFriends() never runs, and the app reports a PageFetchException.
Solution: Paged methods do not throw the feature exception directly. Catch PageFetchException around initialPage() and nextPage(), and read the feature exception from its cause.

Join intents never arrive

Symptom: Your app does not react when a user follows an invite.
Solution: joinIntentReceived() listens only while you collect it. Collect the flow in a scope that stays active while your app waits for join intents, and check that connect() uses a scope that lasts as long.

The build fails after you add the VR Platform SDK

Symptom: Gradle reports that the 0.2.2 libraries were compiled with a newer Kotlin version than your project uses.
Solution: The 0.2.2 libraries are built with Kotlin 2.1. Set the Kotlin Gradle plugin to version 2.1 or later. For the setup steps, see Set up for platform development with Kotlin.