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.

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)
                {
          break;
     }

     switch (eventHeader->EventType)
                 {
          case VRAPI_EVENT_FOCUS_GAINED:
               // 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.
               break;
          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.
                break;
          default:
                break;
      }
}

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.