ArCoreApk

Management of the ARCore service APK.

Summary

Enumerations

ArAvailability{
  AR_AVAILABILITY_UNKNOWN_ERROR = 0,
  AR_AVAILABILITY_UNKNOWN_CHECKING = 1,
  AR_AVAILABILITY_UNKNOWN_TIMED_OUT = 2,
  AR_AVAILABILITY_UNSUPPORTED_DEVICE_NOT_CAPABLE = 100,
  AR_AVAILABILITY_SUPPORTED_NOT_INSTALLED = 201,
  AR_AVAILABILITY_SUPPORTED_APK_TOO_OLD = 202,
  AR_AVAILABILITY_SUPPORTED_INSTALLED = 203
}
enum
Describes the current state of ARCore availability on the device.
ArInstallBehavior{
  AR_INSTALL_BEHAVIOR_REQUIRED = 0,
  AR_INSTALL_BEHAVIOR_OPTIONAL = 1
}
enum
Controls the behavior of the installation UI.
ArInstallStatus{
  AR_INSTALL_STATUS_INSTALLED = 0,
  AR_INSTALL_STATUS_INSTALL_REQUESTED = 1
}
enum
Indicates the outcome of a call to ArCoreApk_requestInstall().
ArInstallUserMessageType{
  AR_INSTALL_USER_MESSAGE_TYPE_APPLICATION = 0,
  AR_INSTALL_USER_MESSAGE_TYPE_FEATURE = 1,
  AR_INSTALL_USER_MESSAGE_TYPE_USER_ALREADY_INFORMED = 2
}
enum
Controls the message displayed by the installation UI.

Functions

ArCoreApk_checkAvailability(void *env, void *application_context, ArAvailability *out_availability)
void
Determines if ARCore is supported on this device.
ArCoreApk_requestInstall(void *env, void *application_activity, bool user_requested_install, ArInstallStatus *out_install_status)
Initiates installation of ARCore if needed.
ArCoreApk_requestInstallCustom(void *env, void *application_activity, int32_t user_requested_install, ArInstallBehavior install_behavior, ArInstallUserMessageType message_type, ArInstallStatus *out_install_status)
Initiates installation of ARCore if required, with configurable behavior.

Enumerations

ArAvailability

 ArAvailability

Describes the current state of ARCore availability on the device.

Properties
AR_AVAILABILITY_SUPPORTED_APK_TOO_OLD

The device and Android version are supported, and a version of the ARCore APK is installed, but that ARCore APK version is too old.

AR_AVAILABILITY_SUPPORTED_INSTALLED

ARCore is supported, installed, and available to use.

AR_AVAILABILITY_SUPPORTED_NOT_INSTALLED

The device and Android version are supported, but the ARCore APK is not installed.

AR_AVAILABILITY_UNKNOWN_CHECKING

ARCore is not installed, and a query has been issued to check if ARCore is is supported.

AR_AVAILABILITY_UNKNOWN_ERROR

An internal error occurred while determining ARCore availability.

AR_AVAILABILITY_UNKNOWN_TIMED_OUT

ARCore is not installed, and the query to check if ARCore is supported timed out.

This may be due to the device being offline.

AR_AVAILABILITY_UNSUPPORTED_DEVICE_NOT_CAPABLE

ARCore is not supported on this device.

ArInstallBehavior

 ArInstallBehavior

Controls the behavior of the installation UI.

Properties
AR_INSTALL_BEHAVIOR_OPTIONAL

Include Cancel button in initial prompt and allow easily backing out after installation has been initiated.

AR_INSTALL_BEHAVIOR_REQUIRED

Hide the Cancel button during initial prompt and prevent user from exiting via tap-outside.

Note: The BACK button or tapping outside of any marketplace-provided install dialog will still decline the installation.

ArInstallStatus

 ArInstallStatus

Indicates the outcome of a call to ArCoreApk_requestInstall().

Properties
AR_INSTALL_STATUS_INSTALLED

The requested resource is already installed.

AR_INSTALL_STATUS_INSTALL_REQUESTED

Installation of the resource was requested.

The current activity will be paused.

ArInstallUserMessageType

 ArInstallUserMessageType

Controls the message displayed by the installation UI.

Properties
AR_INSTALL_USER_MESSAGE_TYPE_APPLICATION

Display a localized message like "This application requires ARCore...".

AR_INSTALL_USER_MESSAGE_TYPE_FEATURE

Display a localized message like "This feature requires ARCore...".

AR_INSTALL_USER_MESSAGE_TYPE_USER_ALREADY_INFORMED

Application has explained why ARCore is required prior to calling ArCoreApk_requestInstall(), skip user education dialog.

Functions

ArCoreApk_checkAvailability

void ArCoreApk_checkAvailability(
  void *env,
  void *application_context,
  ArAvailability *out_availability
)

Determines if ARCore is supported on this device.

This may initiate a query with a remote service to determine if the device is compatible, in which case it will return immediately with out_availability set to AR_AVAILABILITY_UNKNOWN_CHECKING.

Note: A result AR_AVAILABILITY_SUPPORTED_INSTALLED only indicates presence of a suitably versioned ARCore APK. Session creation may still fail if the ARCore APK has been sideloaded onto an incompatible device.

May be called prior to ArSession_create().

Details
Parameters
env
The application's JNIEnv object
application_context
A jobject referencing the application's Android Context.
out_availability
A pointer to an ArAvailability to receive the result.

ArCoreApk_requestInstall

ArStatus ArCoreApk_requestInstall(
  void *env,
  void *application_activity,
  bool user_requested_install,
  ArInstallStatus *out_install_status
)

Initiates installation of ARCore if needed.

When your apllication launches or enters an AR mode, it should call this method with user_requested_install = 1.

If ARCore is installed and compatible, this function will set out_install_status to AR_INSTALL_STATUS_INSTALLED.

If ARCore is not currently installed or the installed version not compatible, the function will set out_install_status to AR_INSTALL_STATUS_INSTALL_REQUESTED and return immediately. Your current activity will then pause while the user is informed about the requierment of ARCore and offered the opportunity to install it.

When your activity resumes, you should call this method again, this time with user_requested_install = 0. This will either set out_install_status to AR_INSTALL_STATUS_INSTALLED or return an error code indicating the reason that installation could not be completed.

ARCore-optional applications must ensure that ArCoreApk_checkAvailability() returns one of the AR_AVAILABILITY_SUPPORTED_... values before calling this method.

See our sample code for an example of how an ARCore-required application should use this function.

May be called prior to ArSession_create().

For more control over the message displayed and ease of exiting the process, see ArCoreApk_requestInstallCustom().

Caution: The value of *out_install_status should only be considered when AR_SUCCESS is returned. Otherwise this value must be ignored.

Details
Parameters
env
The application's JNIEnv object
application_activity
A jobject referencing the application's current Android Activity.
user_requested_install
if set, override the previous installation failure message and always show the installation interface.
out_install_status
A pointer to an ArInstallStatus to receive the resulting install status, if successful. Note: this value is only valid with the return value is AR_SUCCESS.
Returns
AR_SUCCESS, or any of:

ArCoreApk_requestInstallCustom

ArStatus ArCoreApk_requestInstallCustom(
  void *env,
  void *application_activity,
  int32_t user_requested_install,
  ArInstallBehavior install_behavior,
  ArInstallUserMessageType message_type,
  ArInstallStatus *out_install_status
)

Initiates installation of ARCore if required, with configurable behavior.

This is a more flexible version of ArCoreApk_requestInstall() allowing the application control over the initial informational dialog and ease of exiting or cancelling the installation.

See ArCoreApk_requestInstall() for details of use and behavior.

May be called prior to ArSession_create().

Details
Parameters
env
The application's JNIEnv object
application_activity
A jobject referencing the application's current Android Activity.
user_requested_install
if set, override the previous installation failure message and always show the installation interface.
install_behavior
controls the presence of the cancel button at the user education screen and if tapping outside the education screen or install-in-progress screen causes them to dismiss.
message_type
controls the text of the of message displayed before showing the install prompt, or disables display of this message.
out_install_status
A pointer to an ArInstallStatus to receive the resulting install status, if successful. Note: this value is only valid with the return value is AR_SUCCESS.
Returns
AR_SUCCESS, or any of:

Send feedback about...