Enabling Focus Awareness for System Overlays

Focus awareness allows many forms of Oculus system user interfaces (UI), such as universal menu or system keyboard, to appear as an overlay on top of an app without pausing the immersive experience. This allows users to access the system UI without context switching away from the app, keeping users engaged in the experience. Focus awareness uses the concept of input focus, a system for tracking whether the user is focused on the app or elsewhere, to correctly handle times when the app is running but the user is interacting with system UI. Based on input focus, apps can take appropriate action when an overlay appears. For example, when the universal menu appears on top of an app, the app continues to run but may pause the gameplay as the input focus is lost.

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.

Integrate Overlay Support

To integrate overlay support, enable focus awareness from the OVR Manager and then check input focus events. Do the following:

Enable Focus Awareness

  1. Select the OVRCameraRig prefab to open settings in the Inspector window.
  2. Under OVR Manager (script), in the Quest Features section, select the Focus Aware check box. When you enable focus awareness, Oculus automatically sets the com.oculus.vr.focusaware value to true in the Android manifest file.

Check Input Focus Events

With focus awareness enabled, you can add event handlers for every event that is raised when an app gains or loses focus.

When system UI overlays the app, the app loses the input focus and the OVRManager.InputFocusLost event is triggered. For example, when the user presses the Oculus button on the controller while the app is running, the app loses input focus. When the system UI is dismissed, the app gains the input focus and the OVRManager.InputFocusAcquired event is triggered.

Depending on the input focus event, you can perform several actions. For example, when the OVRManager.InputFocusLost event is triggered, you can pause a gameplay, hide the user’s input affordance such as arms or indicate to other online users that the specific user is currently not focused on the app. Similary, when the OVRManager.InputFocusAcquired event is triggered, you can resume gameplay or show the user’s input affordance.

Preview Overlays

To preview an overlay, enable the universal menu from the headset:

  • From Oculus Home, go to Settings > Experiments, and then enable New Universal Menu.

Pressing the Oculus button while your app is running lets the universal menu display as an overlay. We highly recommend testing your apps with focus aware enabled so that you are prepared when the feature turns into a default system behavior.