DaydreamApi

public class DaydreamApi

Entry point for Daydream-specific API calls. Create an instance of this class using the create(Context) method. When you no longer need it, you must clean it up with a call to the close() method. Once closed, this object cannot be reused. This object maintains a service connection to Google VR Services and dispatches calls to it asynchronously. Therefore, creating and closing this object is a somewhat heavy operation that involves binding to a service. It is advisable, therefore, to reuse a single instance (or a small number of instances) rather than create them frequently. A typical pattern is to create a DaydreamApi object on the Activity's onStart() method and close it on onStop(). This class is NOT thread-safe and must only be used from the main (UI) thread.

Public Methods

void
close()
Cleans up and finalizes this instance.
static DaydreamApi
create(Context context)
Create a DaydreamApi object.
static Intent
createVrIntent(ComponentName componentName)
Create an Intent to launch a VR activity with the given component name.
void
exitFromVr(Activity activity, int requestCode, Intent data)
Gracefully exits from the current VR Activity.
int
getCurrentViewerType()
Gets the type of the currently paired viewer, as defined by GvrApi.ViewerType.
static boolean
isDaydreamReadyPlatform(Context context)
Returns whether the current Android platform is considered "Daydream-ready".
void
launchInVr(PendingIntent pendingIntent)
Launches the VR Activity specified by the given PendingIntent.
void
launchInVr(ComponentName componentName)
Launches the VR Activity specified by the given ComponentName.
void
launchInVr(Intent intent)
Launches the VR Activity specified by the given Intent.
void
launchInVrForResult(Activity activity, PendingIntent pendingIntent, int requestCode)
Launches the VR Activity specified by the given PendingIntent that will return a result to the given Activity.
void
launchVrHomescreen()
Launch the stereoscopic, 3D VR launcher homescreen.
static void
setVrContentIntent(Bundle extras)
Marks a notification as safe to launch in VR.
static Intent
setupVrIntent(Intent intent)
Format an Intent to launch a VR activity.

Inherited Methods

Public Methods

public void close ()

Cleans up and finalizes this instance.

After calling this method, you must release all references to this object and must not call any other methods. Doing so will throw an exception.

Calling this on an object that is already closed is a no-op.

public static DaydreamApi create (Context context)

Create a DaydreamApi object.

The created object must be finalized by calling close() once it's no longer needed.

Please note that this method may return null if the device does not support Daydream features or if Google VR Services is out of date, so your code must be prepared to handle the null return value gracefully.

Parameters
context
Returns
  • The DaydreamApi object, if the device is Daydream-ready and the service is available and sufficiently up-to-date, null otherwise.

public static Intent createVrIntent (ComponentName componentName)

Create an Intent to launch a VR activity with the given component name.

It is recommended that applications use an Intent formatted in this way to launch VR activities.

Daydream-ready applications must not directly send intents created this way, but should instead use one of the launchInVr methods provided in this API.

Parameters
componentName for the VR activity to launch.
Returns
  • the properly formatted VR intent to launch.

public void exitFromVr (Activity activity, int requestCode, Intent data)

Gracefully exits from the current VR Activity.

Daydream-ready apps should use this when they need to transition from a Daydream Activity back to 2D content, e.g., to request a permission.

Calling this will trigger a transition from the current Activity to an intermediate VR Activity, where the user is prompted to remove their phone from the headset. After phone removal is detected, the target activity will be notified via onActivityResult(), using the provided requestCode and a result code of RESULT_OK. If the user cancels or interrupts the exit for any reason, or there is an error during the request flow, a result code of RESULT_CANCELED will be sent to the Activity result callback.

Parameters
activity The Activity to receive the result of the exit flow, via Activity.onActivityResult().
requestCode The private request code that will be used to indicate exit flow success or cancellation via Activity.onActivityResult().
data Optional Intent data to supply to the Activity result callback. May be null.

public int getCurrentViewerType ()

Gets the type of the currently paired viewer, as defined by GvrApi.ViewerType.

By default, the viewer type is Cardboard (*not* Daydream). Daydream viewers are supported only on Daydream-ready platforms (see also isDaydreamReadyPlatform(Context)).

Note: The viewer type can change at any time when a pairing event occurs. However, it will typically happen when the VR application is in the backround (paused).

Warning: This method will block on an expensive Binder call (potentially taking several milliseconds). Plan accordingly and minimize usage on critical paths.

Returns

public static boolean isDaydreamReadyPlatform (Context context)

Returns whether the current Android platform is considered "Daydream-ready".

Only Daydream-ready platforms support Daydream headsets, ensuring a consistent, smooth and low-latency VR experience.

Parameters
context The current Context.
Returns
  • Whether the current platform is Daydream-ready.

public void launchInVr (PendingIntent pendingIntent)

Launches the VR Activity specified by the given PendingIntent.

Calling this will cause the given PendingIntent to be launched after the appropriate Daydream-specific transition.

This is reserved for use with the Play Store VR In-App-Purchase (IAP) APIs.

Parameters
pendingIntent for the VR play store activity to launch.

public void launchInVr (ComponentName componentName)

Launches the VR Activity specified by the given ComponentName.

Calling this will cause the Activity identified by the given ComponentName to be launched after the appropriate Daydream-specific transition.

This is the recommended way for Daydream-ready apps to launch another VR Activity, be it from a 2D Activity (typically through an "enter VR" button), or from a VR Activity.

Parameters
componentName for the VR activity to launch.
Throws
ActivityNotFoundException if no activity to handle the given intent is present on this device.

public void launchInVr (Intent intent)

Launches the VR Activity specified by the given Intent.

Calling this will cause the given Intent to be launched after the appropriate Daydream-specific transition.

Daydream-ready apps may use this method to launch a VR Activity when specifying additional intent flags, extras, or data fields. Intents passed to this should generally be instantiated with createVrIntent(ComponentName) and modified with additional fields needed.

Parameters
intent for the VR activity to launch.
Throws
ActivityNotFoundException if no activity to handle the given intent is present on this device.

public void launchInVrForResult (Activity activity, PendingIntent pendingIntent, int requestCode)

Launches the VR Activity specified by the given PendingIntent that will return a result to the given Activity.

Calling this will cause the given PendingIntent to be launched after the appropriate Daydream-specific transition.

This is reserved for use with the Play Store VR In-App-Purchase (IAP) APIs.

Parameters
activity the activity to receive the result via onActivityResult().
pendingIntent for the VR play store activity to launch.
requestCode the requestCode to deliver in onActivityResult().

public void launchVrHomescreen ()

Launch the stereoscopic, 3D VR launcher homescreen.

Calling this will cause the VR homescreen to be launched after the appropriate Daydream-specific transition.

Daydream-ready apps must use this method whenever they launch the VR homescreen, be it from a 2D context, or from a VR context when one VR Activity wishes to return to the VR homescreen.

public static void setVrContentIntent (Bundle extras)

Marks a notification as safe to launch in VR.

This is meant to be called on a Notification.Builder's extras Bundle and signifies that the contentIntent set on the notification will resolve to a VR Activity if launched.

Expected usage: Notification.Builder builder; DaydreamApi.setVrContentIntent(builder.getExtras());

Parameters
extras The extras Bundle from the Notification.Builder.

public static Intent setupVrIntent (Intent intent)

Format an Intent to launch a VR activity.

It is recommended that applications use an Intent formatted in this way to launch VR activities.

Daydream-ready applications must not directly send intents created this way, but should instead use one of the launchInVr methods provided in this API.

Parameters
intent for a VR activity to launch.
Returns
  • the properly formatted VR intent to launch.