VR Entry Flow

The VR Entry flow is the set of screens seen by the user when entering VR on a Daydream headset. These screens are:

  1. Pairing the controller, if it is not already paired.
  2. Performing firmware updates on the controller, if necessary.
  3. Granting any necessary permissions to Google VR Services, if needed.
  4. Enabling bluetooth, NFC and other device features.
  5. Pairing the Daydream headset, if not yet done.
  6. Instructing the user to insert the phone in the headset.
  7. Connecting and recalibrating the controller and headset orientation.

Google VR Services automatically triggers the VR Entry screens when necessary, so your application does not need special logic to handle the entry flow. After the flow is complete, your application starts (or resumes), and you can assume that at that point the headset and controller are ready to use. The coordinate systems used by the controller and headset will be in sync and set up such that their forward direction (Z axis) is the direction the user is initially facing. Therefore, your application does not need to explicitly recenter the controller or headset on startup.

When is the VR Entry flow shown?

The VR Entry flow is enabled based on two factors:

  • The type of VR Activity being launched (Cardboard-only, Daydream/Cardboard, or Daydream-only).

  • The type of headset paired (Cardboard or Daydream).

The Activity type is determined by the categories declared in the intent filters section of the AndroidManifest.xml file, as described in the VR Android Manifest section.

The behavior of the VR Entry flow in each of these cases is described below.

App type Headset type VR Entry flow
Daydream only Daydream Shown.
Daydream only Cardboard Shown. Requires switching headset(*).
Daydream/Cardboard Daydream Shown.
Daydream/Cardboard Cardboard Not shown.
Cardboard only Daydream Shown. Displays error(**).
Cardboard only Cardboard Not shown.

(*) In this case, the VR Entry flow will require the user to switch headsets and pair a Daydream headset in order to continue.

(**) In this case, the VR Entry flow will inform the user that the application is incompatible with their headset and they will be unable to proceed.

The VR Entry flow happens when the user is transitioning from 2D into VR; that is, when they are about to start a VR session. This can happen as a result of the following:

  1. A VR Activity is launched from the Android 2D launcher, or resumed from the recents menu. This is called a direct launch.
  2. A VR Activity launch is requested indirectly through the DaydreamApi.launchInVr method call. This is called an indirect launch.

The VR Entry screens affect your application lifecycle in a few important ways, described below.

Effects on the Activity lifecycle

The effect of the VR Entry flow depends on how your Activity was launched.

For a direct launch (as defined above), your Activity will start and will then be interrupted by the VR Entry flow, and will later be resumed when the VR Entry flow ends.

In other words, the sequence of events is:

  1. Your Activity launches.
  2. Your Activity receives onCreate() (if your Activity is being created).
  3. Your Activity receives onStart().
  4. Your Activity receives onResume().
  5. Google VR Services now interrupts your Activity in order to show the VR Entry flow. At this point, your Activity goes to the background.
  6. Your Activity receives onPause().
  7. Your Activity receives onStop().
  8. The VR Entry flow proceeds and eventually finishes.
  9. Your Activity is brought back to the foreground.
  10. Your Activity receives onStart().
  11. Your Activity receives onResume().

On the other hand, if you are performing an indirect launch via the DaydreamApi.launchInVr method, your Activity is not launched until the end of the VR Entry flow. In this case, the sequence of events is much simpler:

  1. Google VR Services shows the VR Entry flow.
  2. The VR Entry flow proceeds and eventually finishes.
  3. Your Activity is now launched.
  4. Your Activity receives onCreate() (if your Activity is being created).
  5. Your Activity receives onStart().
  6. Your Activity receives onResume().

Preemption by System UIs

At any time during the execution of your VR Activity, Google VR Services may send it to the background in order to show one of its system UIs, or to switch to a different application. For example, the user might click the controller's home button to be taken back to the Daydream app. Or, as another example, a problem with the controller can occur, in which case the user might be taken back to the recalibration screen, prompting them to reconnect the controller. In either case, your Activity will get paused and will receive onPause() and onStop(), and may later be resumed with onStart() and onResume().

As is the case with Android apps in general, note that there is no guarantee that the user will return to your Activity after it has been paused. For example, the user might decide to end their VR session instead of reconnecting their controller. Or the system might decide to kill your Activity in order to reclaim memory.

Therefore, your application should always save any important state when it is paused. For example, a game might wish to save the user's progress at that point so the user can return to the same point in the game on a future session.