Enable Focus Awareness

Starting with the v19 SDK release, if an app does not support focus awareness, Oculus will flag it with a warning at the time of submission to Oculus Store. We highly recommend that you enable the focus awareness feature early in your development process to test how your app handles the loss of input and let the system UI appear as an overlay.

Focus awareness is a system feature that allows the Oculus system UI to appear as an overlay on top of an app without requiring it to be paused. The purpose of this feature is to let the app take appropriate action when the system UI appears. For example, when a system UI appears on top, the app pauses the gameplay. It uses the concept of input focus, which is a system for tracking whether the user is focused on app or elsewhere, to correctly handle the time when the app is running but the user’s focus is elsewhere.

This feature can be useful for many apps. For example, multiplayer apps can use this feature to continue to process network messages while the system UI overlay is active.

Understand Changes in System UI Rendering

When you enable focus awareness, there is a change in how system UI, such as the universal menu or a system keyboard, is rendered. For example, when the user presses the Oculus button on the controller, the universal menu is overlaid and the runtime renders the tracked controllers to interact with the menu. Similarly, when you set up the system keyboard to appear as an overlay, it automatically appears when an editable UI text element receives the input focus.

Overlay capabilities vastly expand users’ ability to accomplish secondary tasks and the potential for deeper, uninterrupted engagement with your apps. To let users stay engaged with the experience, we strongly recommend to update the app logic by incorporating the following user experience guidelines.

User Experience Guidelines

To ensure the app works seamlessly with overlay, consider the following guidelines:

  • Application Experience Continuity: When a system UI appears, the app will continue running, so users will expect the experience to continue seamlessly. Ensure the app experience proceeds intuitively when overlay is enabled. For example, if the player is climbing a ladder when the universal menu appears, they’ll probably expect to maintain their grip rather than falling.

  • Prevent loss of progress: Depending on your app’s experience, users may expect the app to react to the appearance of overlay UI to prevent the loss of progress. For example, pause fast-paced single player gameplay so that players don’t lose a level due to the overlay appearing and their input being routed to the system and not the app. For multiplayer gameplay, proceed as normal when overlay UI appears so that other players’ gameplay isn’t disrupted.

    Media consumption experiences should likely continue since users are bringing up the universal menu to multitask and expect playback to proceed while they accomplish secondary tasks.

  • Hide input affordances and near-field objects: The system renders overlay UI in the user’s personal space of approximately two meters. Consider hiding any input affordances or objects that are displayed closer than two meters such as in-app menus to avoid unexpected visual disparities.

  • Adjust audio volume: Consider lowering the volume or muting audio playback during gameplay to make it more clear to users that they’re interacting with system UI.

  • Indicating presence to remote users: For multi-user experiences, consider providing an indication to nearby users when a specific user is interacting with the system UI. The indication will help them understand why the user appears unresponsive.

Focus Awareness and System UI Rendering

When focus awareness is enabled in an app, there is a change in how the system UI is rendered when the Oculus button is pressed on the controller. When the user presses the Oculus button, depending on whether the app supports focus awareness, the Universal menu is displayed in one of the following ways:

  • If the app supports focus awareness, the system UI is displayed directly on top of the app without pausing.
  • If the app does not support focus awareness, the app is paused by the runtime, and the user is presented with the system UI in the Oculus Home environment.

Whenever the system UI is active, the runtime renders tracked controllers in the scene for interaction.

Enable Focus Awareness for Native Apps

To implement focus awareness support on a native Android app, add the following to the app’s manifest file under the <activity> tag:

<meta-data android:name="com.oculus.vr.focusaware" android:value="true" />

Including focus awareness support to your app requires correctly handling when your app is running, but the user’s focus is elsewhere. When a system UI overlay appears, such as when the user presses the Oculus button, it can be appropriately handled with the following code:

ovrEventDataBuffer eventDataBuffer = {};

// Poll for VrApi events at regular frequency
for (;;) {
     ovrEventHeader* eventHeader = (ovrEventHeader*)(&eventDataBuffer);
     ovrResult res = vrapi_PollEvent(eventHeader);
     if (res != ovrSuccess)

     switch (eventHeader->EventType)
               // FOCUS_GAINED is sent when the application is in the foreground and has
               // input focus. This may be due to a system overlay relinquishing focus
               // back to the application.
          case VRAPI_EVENT_FOCUS_LOST:
                // FOCUS_LOST is sent when the application is no longer in the foreground and
                // therefore does not have input focus. This may be due to a system overlay taking
                // focus from the application. The application should take appropriate action when
                // this occurs.

Previewing Overlays

To preview an overlay, you must first enable the new Universal Menu. From Oculus Home, go to Settings > Experiments, and then enable New Universal Menu.

Pressing the Oculus button while your app is running will bring up the Universal Menu as an overlay when the feature is enabled.

We recommend testing your apps with this feature enabled so you are prepared when the feature turns into a default system behavior.