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.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.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.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")
}
users-kotlinachievements-kotlinleaderboards-kotlingroup-presence-kotliniap-kotlinuser-age-category-kotlincore-kotlin. To declare the artifacts in a version catalog instead, see Set up for platform development with Kotlin.com.meta.horizon.platform.ovr imports.Core:import com.meta.horizon.platform.ovr.Core; Core.asyncInitialize(appID, context);
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.asyncInitialize() success handler to your first feature call, because feature calls wait until the connection is ready.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.connect() again reuses the existing connection. The app ID from the first call stays in effect.connect() ends. Use a scope that does not end when your app moves to the background, such as lifecycleScope in onCreate() or a viewModelScope.connect() before it creates any feature client.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}")
}
}
android.util.Log, androidx.lifecycle.lifecycleScope, and kotlinx.coroutines.launch imports, and imports that an earlier sample shows.UsersException, AchievementsException, LeaderboardsException, GroupPresenceException, IapException, or UserAgeCategoryException. Each class is in its feature package, for example horizon.platform.users.UsersException.horizon.core.android.common.HzPlatformSdkException. Read code, requestName, and displayableMessage where you read getCode() and getDisplayableMessage() on the OVR Error object.code rather than on the message text.suspend call inside a coroutine, with a catch for its feature exception.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}")
}
}
collect as a GroupPresenceException. Catch it around collect, or use the catch operator.collect on the matching flow, with a catch for the feature exception.For a complete working implementation, see the Group Presence sample overview.
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.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().nextPage() from a coroutine. It returns false when there is no next page, and pages emits the new page.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.PageFetchException from initialPage() and nextPage(), not the feature exception. The feature exception is its cause.initialPage() inside a try/catch for PageFetchException before it collects pages. For more patterns, see Pagination.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.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)
}
}
Long to use String. Your code now holds every user ID as a String.com.meta.horizon.platform.ovr imports left.Users().getLoggedInUser() returns a user and that a paged call, such as getLoggedInUserFriends(), returns a first page.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.| 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. |
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. |
| 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>. |
| 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. |
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>. |
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. |
| OVR Platform SDK (Java) | VR Platform SDK (Kotlin) | Notes |
|---|---|---|
UserAgeCategory.get() | UserAgeCategory().get() | Returns UserAccountAgeCategory. Read ageCategory, an AccountAgeCategory: Unknown, Ch, Tn, or Ad. |
suspend calls and flows. The Methods column lists each client’s methods in 0.2.2.| OVR class | VR Platform SDK artifact | Kotlin client | Methods | Minimum Horizon OS | Documentation |
|---|---|---|---|---|---|
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.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.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.Users.launchFriendRequestFlow(), stay on the OVR Platform SDK until you have a replacement.Avatar, Challenges, and PushNotification classes. If your app uses them, stay on the OVR Platform SDK until you have a replacement.Notifications.markAsRead(), stay on the OVR Platform SDK until you have a replacement.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().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.HzPlatformNotInitializedException when it creates Users(), Iap(), or another feature client.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.catch for UsersException around getLoggedInUserFriends() never runs, and the app reports a PageFetchException.PageFetchException around initialPage() and nextPage(), and read the feature exception from its cause.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.