Set Up for Platform Development with Android Apps

Updated: Dec 18, 2024

This guide will walk you through the basics of setting up your Android development environment and initializing the platform.

Prerequisites

Before you can integrate the Android Platform SDK, you’ll need to create an app, get the associated App ID, and use the App ID when configuring your development environment. To create an app, see the information on the Creating and Managing Apps page.

Get your App ID from the Developer Dashboard

In your browser, go to the Meta Horizon Developer Dashboard.

From the left-side navigation, click My Apps.

Choose your app from the list of apps.

From the left-side navigation, click Development > API.

You’ll find your App ID in the middle of the API page. You’ll need your App ID to call the initialization APIs described in the next few sections.

Import Android Platform SDK

Android Platform SDK is deployed to Maven Central so it can be added to your app. In this step, you will add it to your project by editing app/build.gradle.kts to include the correct dependencies.

If your app uses Groovy (build.gradle instead of build.gradle.kts), read the build dependencies page for Groovy syntax.

In app/build.gradle.kts, create a variable for the Android Platform SDK version above the dependencies block:

 val androidPlatformSdkVersion = "71"

At the end of the dependencies block, add the following package:

 implementation("com.meta.horizon.platform.ovr:android-platform-sdk:$androidPlatformSdkVersion")

The variable declaration and dependencies block should now look like this:

 val androidPlatformSdkVersion = "71"

 dependencies {
 ...

 implementation("com.meta.horizon.platform.ovr:android-platform-sdk:$androidPlatformSdkVersion")
 }

Sync your project with Gradle to download the packages.

Location of the Gradle sync button in Android Studio toolbar

Initialize the SDK

The first step to integrating platform features is implementing the initialization function. There are two initialization functions you can call with your App Id. One is synchronous and runs on the thread you initialize on, the other is asynchronous and allows you to perform other functions, including calls to the Platform SDK, while the SDK is initializing. You should use the asynchronous method for better app performance and less state management.

Synchronous - Core.initialize()

Asynchronous - Core.asyncInitialize()

For example:

import com.meta.horizon.platform.ovr.Core;

Core.asyncInitialize(appID, context);

When using the asynchronous call, the SDK is placed in an intermediate initializing state before full initialization. In this initializing state you’re able to run other processes, including making calls to asynchronous Platform SDK methods. Requests made to the Platform SDK in the initializing state will be queued and run after the SDK finishes initializing.

Initialization Best Practices

In order to properly initialize the Platform SDK, follow these recommendations:

Use asyncInitialize() rather than initialize() for Android apps. This is important because asyncInitialize() does not block the initialization code, which allows your application to load faster. In addition, asyncInitialize() does not throw an exception on Android if the initialization failed.

Surround the platform API initialization code with a try/catch block, and treat any exceptions that are caught as if the entitlement check failed.

Set the App Id in the AndroidManifest.xml by adding a <meta-data> with the key com.meta.horizon.platform.ovr.OCULUS_APP_ID, or call asyncInitialize() with an explicit appId argument. If an initialization method is called without an explicit appId argument, the Platform will try to initialize using the com.meta.horizon.platform.ovr.OCULUS_APP_ID stored in your

Example <meta-data> in your AndroidManifest.xml

<meta-data
   android:name="com.meta.horizon.platform.ovr.OCULUS_APP_ID"
   android:value="MY_OCULUS_APP_ID"
/>

Initialize the SDK and Perform the Entitlement Check

The first step to integrating the SDK is implementing the initialization function, and next you should perform the entitlement check. For instructions on how to do this, see Entitlement Check.

Did you find this page helpful?