Develop

Add a splash screen

Updated: Oct 9, 2026

Overview

The operating system can show your image as a splash screen while your app loads. This page shows how to add a system splash screen, show a different image to each eye (stereo), and size the image.

Prerequisites

  • A native Android app that you can build into an APK and run on a Meta VR device.
  • Access to the app’s AndroidManifest.xml file and its assets folder.
  • A PNG image for the splash screen.
If you build with Unity or Unreal, use the engine’s splash screen settings instead. See Unity splash screen or Unreal splash screen.

Steps

1. Add the splash screen image

Create a PNG file named vr_splash.png and add it to your app’s assets folder. In a Gradle project, this folder is src/main/assets/. The build packages the file into the APK as assets/vr_splash.png. The file name is case-sensitive.
To choose the image dimensions, see Size the splash screen image.

2. Enable the splash screen in the manifest

Add a com.oculus.ossplash meta-data element inside the <application> element of your AndroidManifest.xml file. The ... and <!-- ... --> placeholders stand for your existing manifest content.
<manifest ...>
  <application ...>
    <!-- ... -->
    <meta-data android:name="com.oculus.ossplash" android:value="true"/>
  </application>
</manifest>
Build and run your app on your device. The system shows your image as the splash screen while the app loads.

3. (Optional) Make the splash screen stereo

By default, the system shows the same image to both eyes. To show a different view to each eye, replace vr_splash.png with one side-by-side image:
  • The left eye sees the left half of the image.
  • The right eye sees the right half.
  • Both halves have the same width, so split the image exactly down the middle.
For example, a 2048 by 1024 image has two 1024 by 1024 halves.
Keep each half within the shape limit in Size the splash screen image.
Then add a com.oculus.ossplash.type meta-data element to the same <application> element. The following block shows the complete set of splash meta-data elements in that element: the com.oculus.ossplash element from step 2 stays, and you add the com.oculus.ossplash.type element.
<application ...>
  <!-- ... -->
  <meta-data android:name="com.oculus.ossplash" android:value="true"/>
  <meta-data android:name="com.oculus.ossplash.type" android:value="stereo"/>
</application>
The value must be lowercase stereo. If you omit this element, the default is mono. The system reads com.oculus.ossplash.type only when com.oculus.ossplash is true.
Build and run your app. Each eye now sees its own half of the image.

Size the splash screen image

The system scales the splash screen to fit a fixed area in front of the user. The aspect ratio of your image, not its resolution, determines the displayed size. A higher-resolution image does not appear larger. It looks sharper up to the display’s pixel density. Past that density, extra resolution adds no sharpness and can cause aliasing. The system keeps the image’s proportions and does not crop or stretch it.
For a stereo splash screen, each eye sees one half of the image, so the system sizes the splash screen by the shape of one half. For example, a 2048 by 1024 stereo image and a 1024 by 1024 mono image appear at the same size, because each eye sees a square image. Keep each half no more than 2.3 times as wide as it is tall. Wider stereo images can display smaller than one half of the image would as a mono splash screen.

Splash screen behavior

The splash screen stays where it first appeared in front of the user and does not follow head movement. If the user recenters the view, the splash screen moves in front of the user again. It fades out once your app starts.
You can combine a system splash screen with an animated splash screen that your app draws.

Manifest keys

Each key is the android:name of a <meta-data> element inside the <application> element. The value goes in android:value.
KeyValuesDefaultEffect
com.oculus.ossplash
true, false
false
true shows assets/vr_splash.png as the system splash screen. false turns it off.
com.oculus.ossplash.type
mono, stereo
mono
mono shows one image to both eyes. stereo shows each eye its own half: the left half for the left eye and the right half for the right eye.
com.oculus.ossplash.background
black, passthrough-contextual
black
Sets the background shown while your app loads. The system reads this key even when com.oculus.ossplash is not true. For details, see Passthrough loading screen.

Troubleshooting

The splash screen does not appear

Symptom: Your app loads without a splash screen.
Solution: Check these items:
  • The com.oculus.ossplash meta-data element is inside the <application> element, and its value is true.
  • The image is named exactly vr_splash.png. The file name is case-sensitive.
  • The APK contains the image. To check, run unzip -l your-app.apk and look for assets/vr_splash.png.

Each eye shows the whole side-by-side image

Symptom: Both eyes see the full image, with the left and right halves next to each other.
Solution: Add the com.oculus.ossplash.type meta-data element with the value stereo, in lowercase. Keep com.oculus.ossplash set to true.

The stereo splash screen looks smaller than expected

Symptom: A stereo splash screen displays smaller than one half of the image shown as a mono splash screen.
Solution: Check the shape of one half of your image. When one half is more than 2.3 times as wide as it is tall, the splash screen can display smaller. Change the image so each half is no more than 2.3 times as wide as it is tall.

The splash screen looks blurry

Symptom: The splash screen appears soft or pixelated.
Solution: Increase the resolution of vr_splash.png. For a stereo image, increase it for both halves. Keep the same aspect ratio. A higher-resolution image looks sharper up to the display’s pixel density, and the displayed size does not change. Past that density, extra resolution adds no sharpness and can cause aliasing.
Meta
English (US)
© 2026 Meta