# ArCoreApk

Functions for installing and updating "Google Play Services for AR" (ARCore) and determining whether the current device is an [ARCore supported device](https://developers.google.com/ar/devices).

## Summary

| ### Enumerations ||
|---|---|
| `https://developers.google.com/ar/reference/c/group/ar-core-apk#aravailability{ https://developers.google.com/ar/reference/c/group/ar-core-apk#ar_availability_unknown_error = 0, https://developers.google.com/ar/reference/c/group/ar-core-apk#ar_availability_unknown_checking = 1, https://developers.google.com/ar/reference/c/group/ar-core-apk#ar_availability_unknown_timed_out = 2, https://developers.google.com/ar/reference/c/group/ar-core-apk#ar_availability_unsupported_device_not_capable = 100, https://developers.google.com/ar/reference/c/group/ar-core-apk#ar_availability_supported_not_installed = 201, https://developers.google.com/ar/reference/c/group/ar-core-apk#ar_availability_supported_apk_too_old = 202, https://developers.google.com/ar/reference/c/group/ar-core-apk#ar_availability_supported_installed = 203 }` | enumDescribes the current state of ARCore availability on the device. |
| `https://developers.google.com/ar/reference/c/group/ar-core-apk#arinstallbehavior{ https://developers.google.com/ar/reference/c/group/ar-core-apk#ar_install_behavior_required = 0, https://developers.google.com/ar/reference/c/group/ar-core-apk#ar_install_behavior_optional = 1 }` | enumControls the behavior of the installation UI. |
| `https://developers.google.com/ar/reference/c/group/ar-core-apk#arinstallstatus{ https://developers.google.com/ar/reference/c/group/ar-core-apk#ar_install_status_installed = 0, https://developers.google.com/ar/reference/c/group/ar-core-apk#ar_install_status_install_requested = 1 }` | enumIndicates the outcome of a call to `https://developers.google.com/ar/reference/c/group/ar-core-apk#arcoreapk_requestinstall`. |
| `https://developers.google.com/ar/reference/c/group/ar-core-apk#arinstallusermessagetype{ https://developers.google.com/ar/reference/c/group/ar-core-apk#ar_install_user_message_type_application = 0, https://developers.google.com/ar/reference/c/group/ar-core-apk#ar_install_user_message_type_feature = 1, https://developers.google.com/ar/reference/c/group/ar-core-apk#ar_install_user_message_type_user_already_informed = 2 }` | enumControls the message displayed by the installation UI. |

| ### Typedefs ||
|---|---|
| `https://developers.google.com/ar/reference/c/group/ar-core-apk#aravailabilitycallback)(void *callback_context, ArAvailability availability)` | typedef `void(*` Callback definition for `https://developers.google.com/ar/reference/c/group/ar-core-apk#arcoreapk_checkavailabilityasync`. |

| ### Functions ||
|---|---|
| `https://developers.google.com/ar/reference/c/group/ar-core-apk#arcoreapk_checkavailability(void *env, void *context, https://developers.google.com/ar/reference/c/group/ar-core-apk#aravailability *out_availability)` | `void` Determines if ARCore is supported on this device. |
| `https://developers.google.com/ar/reference/c/group/ar-core-apk#arcoreapk_checkavailabilityasync(void *env, void *application_context, void *callback_context, https://developers.google.com/ar/reference/c/group/ar-core-apk#aravailabilitycallback callback)` | `void` Asynchronously determines if ARCore is supported on this device. |
| `https://developers.google.com/ar/reference/c/group/ar-core-apk#arcoreapk_requestinstall(void *env, void *application_activity, int32_t user_requested_install, https://developers.google.com/ar/reference/c/group/ar-core-apk#arinstallstatus *out_install_status)` | `https://developers.google.com/ar/reference/c/group/shared-types#arstatus` 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>. |
| `https://developers.google.com/ar/reference/c/group/ar-core-apk#arcoreapk_requestinstallcustom(void *env, void *application_activity, int32_t user_requested_install, https://developers.google.com/ar/reference/c/group/ar-core-apk#arinstallbehavior install_behavior, https://developers.google.com/ar/reference/c/group/ar-core-apk#arinstallusermessagetype message_type, https://developers.google.com/ar/reference/c/group/ar-core-apk#arinstallstatus *out_install_status)` | `https://developers.google.com/ar/reference/c/group/shared-types#arstatus` 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 `https://developers.google.com/ar/reference/c/group/ar-core-apk#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 `https://developers.google.com/ar/reference/c/group/ar-core-apk#arcoreapk_requestinstall`, skip user education dialog. |

## Typedefs

### ArAvailabilityCallback

```
void(* ArAvailabilityCallback)(void *callback_context, ArAvailability availability)
```
Callback definition for `https://developers.google.com/ar/reference/c/group/ar-core-apk#arcoreapk_checkavailabilityasync`.

The `callback_context` argument will be the same as that passed to `https://developers.google.com/ar/reference/c/group/ar-core-apk#arcoreapk_checkavailabilityasync`.

It is a best practice to free `callback_context` memory provided to `https://developers.google.com/ar/reference/c/group/ar-core-apk#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 `https://developers.google.com/ar/reference/c/group/ar-core-apk#ar_availability_unknown_checking`.

For ARCore-required apps (as indicated by the [manifest `meta-data`](https://developers.google.com/ar/develop/c/enable-arcore#ar_required)) this function will assume device compatibility and will always immediately return one of `https://developers.google.com/ar/reference/c/group/ar-core-apk#ar_availability_supported_installed`, `https://developers.google.com/ar/reference/c/group/ar-core-apk#ar_availability_supported_apk_too_old`, or `https://developers.google.com/ar/reference/c/group/ar-core-apk#ar_availability_supported_not_installed`.

Note: A result `https://developers.google.com/ar/reference/c/group/ar-core-apk#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 `https://developers.google.com/ar/reference/c/group/ar-session#arsession_create`.


| Details ||
|---|---|
| Parameters | |---|---| | `env` | The application's `JNIEnv` object | | `context` | A `JOBject` for an Android `Context`. | | `out_availability` | A pointer to an `https://developers.google.com/ar/reference/c/group/ar-core-apk#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 `https://developers.google.com/ar/reference/c/group/ar-core-apk#arcoreapk_checkavailability`, the result will never be `https://developers.google.com/ar/reference/c/group/ar-core-apk#ar_availability_unknown_checking`.

For ARCore-required apps (as indicated by the [manifest `meta-data`](https://developers.google.com/ar/develop/c/enable-arcore#ar_required)) this function will assume device compatibility and the callback will be asynchronously invoked on the Main thread with one of `https://developers.google.com/ar/reference/c/group/ar-core-apk#ar_availability_supported_installed`, `https://developers.google.com/ar/reference/c/group/ar-core-apk#ar_availability_supported_apk_too_old`, or `https://developers.google.com/ar/reference/c/group/ar-core-apk#ar_availability_supported_not_installed`.

Note: A result `https://developers.google.com/ar/reference/c/group/ar-core-apk#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 `https://developers.google.com/ar/reference/c/group/ar-session#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 `https://developers.google.com/ar/reference/c/group/ar-core-apk#arcoreapk_checkavailability` has returned either `https://developers.google.com/ar/reference/c/group/ar-core-apk#ar_availability_supported_apk_too_old` or `https://developers.google.com/ar/reference/c/group/ar-core-apk#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 `https://developers.google.com/ar/reference/c/group/ar-core-apk#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 `https://developers.google.com/ar/reference/c/group/ar-core-apk#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 `https://developers.google.com/ar/reference/c/group/ar-core-apk#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 `https://developers.google.com/ar/reference/c/group/ar-core-apk#ar_install_status_installed`, it is safe to call `https://developers.google.com/ar/reference/c/group/ar-session#arsession_create`.

Side-loading Google Play Services for AR (ARCore) on unsupported devices will not work. Although `https://developers.google.com/ar/reference/c/group/ar-core-apk#arcoreapk_checkavailability` may return `https://developers.google.com/ar/reference/c/group/ar-core-apk#ar_availability_supported_apk_too_old` or `https://developers.google.com/ar/reference/c/group/ar-core-apk#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 `https://developers.google.com/ar/reference/c/group/ar-core-apk#arcoreapk_requestinstallcustom`.

**Caution:** The value of `*out_install_status` is only valid when `https://developers.google.com/ar/reference/c/group/shared-types#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 `https://developers.google.com/ar/reference/c/group/ar-core-apk#arinstallstatus` to receive the resulting install status, if successful. Value is only valid when the return value is `https://developers.google.com/ar/reference/c/group/shared-types#ar_success`. | |
| **Returns** | `https://developers.google.com/ar/reference/c/group/shared-types#ar_success`, or any of: - `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_fatal` if an error occurs while checking for or requesting installation - `https://developers.google.com/ar/reference/c/group/shared-types#ar_unavailable_device_not_compatible` if ARCore is not supported on this device. - `https://developers.google.com/ar/reference/c/group/shared-types#ar_unavailable_user_declined_installation` if the user previously declined installation. |

### 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 `https://developers.google.com/ar/reference/c/group/ar-core-apk#arcoreapk_requestinstall`, allowing the application control over the initial informational dialog and ease of exiting or cancelling the installation.

Refer to `https://developers.google.com/ar/reference/c/group/ar-core-apk#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 `https://developers.google.com/ar/reference/c/group/ar-core-apk#arinstallstatus` to receive the resulting install status, if successful. Value is only valid when the return value is `https://developers.google.com/ar/reference/c/group/shared-types#ar_success`. | |
| **Returns** | `https://developers.google.com/ar/reference/c/group/shared-types#ar_success`, or any of: - `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_fatal` if an error occurs while checking for or requesting installation - `https://developers.google.com/ar/reference/c/group/shared-types#ar_unavailable_device_not_compatible` if ARCore is not supported on this device. - `https://developers.google.com/ar/reference/c/group/shared-types#ar_unavailable_user_declined_installation` if the user previously declined installation. |