Skip to main content
Version: 20 Mar 2024

Android Manifest

This guide explains the essential elements and attributes that you need to include in your Android Manifest file to deploy an OpenXR application to the Magic Leap 2 device. The Android Manifest file is an XML file that describes the basic characteristics of your application, such as its name, icon, permissions, features, and activities. It is located in the root directory of your project and has the name AndroidManifest.xml. For more information about the general syntax and structure of the Android Manifest file, you can refer to the Android Developer Guide.

Permissions

For OpenXR applications to run properly the org.khronos.openxr.permission.OPENXR_SYSTEM permission must be listed in your manifest. This permission signifies that your application has access to the OpenXR runtime.

<uses-permission android:name="org.khronos.openxr.permission.OPENXR_SYSTEM" />

Android Permission Overview

Permissions are declarations that request access to the device features and resources that your application needs to function properly. There are two types of permissions: normal and dangerous.

  • Normal permissions are granted automatically by the system after being included in the application's AndroidManifest.xml.
  • Dangerous permissions are not granted automatically and require the application to use Android's Permission API to get the user’s explicit approval at runtime.

You need to declare both types of permissions in your manifest file using the <uses-permission> element. For example, to request access to hand tracking, you need to include the following line in your manifest file:

<uses-permission android:name="com.magicleap.permission.HAND_TRACKING" />
info

For more information about how to use permissions on Android, refer to the Android Developer Guide.

Enabling AR Mode

For an application to be launched in AR mode, the application's manifest needs to inform the system that the application is an OpenXR application that targets an HMD form factor. This is done using the OpenXR standard HMD category tag.

<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
<!-- This category is defined by the OpenXR specification and is required for all OpenXR applications that run on HMD devices -->
<category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" />
</intent-filter>

API Level Enforcement

When creating applications that use both OpenXR and Magic Leap SDK, it is important to know that the target OS supports all the features that are used in the application. Magic Leap 2 provides a custom API level that corresponds to a device's OS and the API's that are supported. Developers can specify the minimum version of the Magic Leap OS that an application can run on. For example, MLSDK v1.0.0 had the API Level of 20. The developer API documentation lists which API Level is required for each function call. To indicate that your application uses features marked with Magic Leap API Level 20 and below, you can use the <uses-feature> to enforce the minimum API level by including the following line in your manifest file:

<uses-feature android:name="com.magicleap.api_level" android:version="20">

The line above indicates that the APK uses features marked with Magic Leap API Level 20 and below, this means it will not install on an OS with a lower Magic Leap API level than 20 (not to be confused with the Android API Level). It is strongly recommended that developers include this tag in their AndroidManifest to ensure the best possible experience for end-users.

Complete Android Manifest Example

This example shows the manifest file from the Magic Leap OpenXR Hand Tracking sample application.

<?xml version="1.0" encoding="utf-8"?>

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
android:versionCode="1" android:versionName="1.0">
<application
android:allowBackup="false"
android:fullBackupContent="false"
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"
android:hasCode="false">

<!-- Our activity is the built-in NativeActivity framework class.
This will take care of integrating with our NDK code. -->
<activity android:name="android.app.NativeActivity"
android:label="@string/app_name"
android:configChanges="orientation|keyboardHidden"
android:launchMode="singleTask">

<!-- Tell NativeActivity the name of our .so -->
<meta-data android:name="android.app.lib_name"
android:value="hand_tracking" />
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<!-- Display the application on the home launcher -->
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.LAUNCHER" />
<!-- This category is defined by the OpenXR specification and is required for all OpenXR applications that run on HMD devices -->
<category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" />
</intent-filter>
</activity>
</application>
<!-- Request the OPENXR_SYSTEM and Hand_Tracking permissions -->
<uses-permission android:name="com.magicleap.permission.HAND_TRACKING" />
<uses-permission android:name="org.khronos.openxr.permission.OPENXR_SYSTEM" />
<!-- Specify the requested API Level -->
<uses-feature android:name="com.magicleap.api_level" android:version="20" />
</manifest>