ArCoreApk

Functions for installing and updating "Google Play Services for AR" (ARCore) and determining whether the current device is an ARCore supported device.

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.

Typedefs
ArAvailabilityCallback)(void *callback_context, ArAvailability availability) typedef
void(*
Callback definition for ArCoreApk_checkAvailabilityAsync.

Functions
ArCoreApk_checkAvailability(void *env, void *context, ArAvailability *out_availability)
void
Determines if ARCore is supported on this device.
ArCoreApk_checkAvailabilityAsync(void *env, void *application_context, void *callback_context, ArAvailabilityCallback callback)
void
Asynchronously determines if ARCore is supported on this device.
ArCoreApk_requestInstall(void *env, void *application_activity, int32_t user_requested_install, ArInstallStatus *out_install_status)
On supported devices initiates download and installation of Google Play Services for AR (ARCore) and ARCore device profile data, see https://developers.google.com/ar/develop/c/enable-arcore.
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 Google Play Services for AR (ARCore) and required device profile data, 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.

Typedefs

ArAvailabilityCallback

void(* ArAvailabilityCallback)(void *callback_context, ArAvailability availability)

Callback definition for ArCoreApk_checkAvailabilityAsync.

The callback_context argument will be the same as that passed to ArCoreApk_checkAvailabilityAsync.

It is a best practice to free callback_context memory provided to ArCoreApk_checkAvailabilityAsync at the end of the callback implementation.

Functions

ArCoreApk_checkAvailability

void ArCoreApk_checkAvailability(
  void *env,
  void *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.

For ARCore-required apps (as indicated by the manifest meta-data) this function will assume device compatibility and will always immediately return one of AR_AVAILABILITY_SUPPORTED_INSTALLED, AR_AVAILABILITY_SUPPORTED_APK_TOO_OLD, or AR_AVAILABILITY_SUPPORTED_NOT_INSTALLED.

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 side-loaded onto an unsupported device.

May be called prior to ArSession_create.

Details
Parameters
env
The application's JNIEnv object
context
A JOBject for an Android Context.
out_availability
A pointer to an ArAvailability to receive the result.

ArCoreApk_checkAvailabilityAsync

void ArCoreApk_checkAvailabilityAsync(
  void *env,
  void *application_context,
  void *callback_context,
  ArAvailabilityCallback callback
)

Asynchronously determines if ARCore is supported on this device.

This may initiate a query with a remote service to determine if the device is compatible.

The callback will be invoked asynchronously on the Main thread. Unlike the synchronous function ArCoreApk_checkAvailability, the result will never be AR_AVAILABILITY_UNKNOWN_CHECKING.

For ARCore-required apps (as indicated by the manifest meta-data) this function will assume device compatibility and the callback will be asynchronously invoked on the Main thread with one of AR_AVAILABILITY_SUPPORTED_INSTALLED, AR_AVAILABILITY_SUPPORTED_APK_TOO_OLD, or AR_AVAILABILITY_SUPPORTED_NOT_INSTALLED.

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 side-loaded onto an unsupported device.

May be called prior to ArSession_create.

Details
Parameters
env
The current thread's JNIEnv object
application_context
A JOBject for an Android Context.
callback_context
An arbitrary pointer which will be passed as the first argument to the callback.
callback
The callback to invoke with the result on the Main thread. Must not be NULL.

ArCoreApk_requestInstall

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

On supported devices initiates download and installation of Google Play Services for AR (ARCore) and ARCore device profile data, see https://developers.google.com/ar/develop/c/enable-arcore.

Do not call this function unless ArCoreApk_checkAvailability has returned either AR_AVAILABILITY_SUPPORTED_APK_TOO_OLD or AR_AVAILABILITY_SUPPORTED_NOT_INSTALLED.

When your application launches or wishes to enter AR mode, call this function with user_requested_install = 1.

If Google Play Services for AR and device profile data are fully installed and up to date, this function will set out_install_status to AR_INSTALL_STATUS_INSTALLED.

If Google Play Services for AR or device profile data is not installed or not up to date, the function will set out_install_status to AR_INSTALL_STATUS_INSTALL_REQUESTED and return immediately. The current activity will then pause while the user is prompted to install Google Play Services for AR (market://details?id=com.google.ar.core) and/or ARCore downloads required device profile data.

When your activity resumes, call this function 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.

Once this function returns with out_install_status set to AR_INSTALL_STATUS_INSTALLED, it is safe to call ArSession_create.

Side-loading Google Play Services for AR (ARCore) on unsupported devices will not work. Although ArCoreApk_checkAvailability may return AR_AVAILABILITY_SUPPORTED_APK_TOO_OLD or AR_AVAILABILITY_SUPPORTED_INSTALLED after side-loading the ARCore APK, the device will still fail to create an AR session, because it is unable to locate the required ARCore device profile data.

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

Caution: The value of *out_install_status is only valid 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. Value is only valid when 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 Google Play Services for AR (ARCore) and required device profile data, 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.

Refer to ArCoreApk_requestInstall for correct use and expected runtime behavior.

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. Value is only valid when the return value is AR_SUCCESS.
Returns
AR_SUCCESS, or any of: