Enable the Geospatial API for your Unity (AR Foundation) app targeting Android

Configure your app's settings so that it can use the Geospatial API.

Prerequisites

Make sure that you understand fundamental AR concepts and how to configure an ARCore session before proceeding.

See the Introduction to the Geospatial API for more information about the Geospatial API.

If you're new to developing with ARCore, see Getting started for information about software and hardware requirements, prerequisities and other information specific to the platforms you are using.

To use the ARCore Geospatial API, your project must support AR Foundation and the ARCore Extensions for AR Foundation.

Enable the ARCore API

Before using the Visual Positioning System (VPS) in your app, you must first enable the ARCore API in a new or existing Google Cloud Platform project. This service is responsible for hosting, storing, and resolving Geospatial anchors.

Set up authorization

To make Geospatial API calls to the VPS, your app needs authorization. Keyless authorization is preferred, but API Key authorization is also supported.

The default authorization strategy for new Unity projects built with ARCore SDK 1.24.0 or later is DoNotUse. This is to prevent apps from being built with unnecessary libraries.

Keyless authorization

If you previously used an API key and no longer need it, delete it in the Google Cloud Platform Console and remove it from your app.

Note that you need to register separately for all of the different combinations of package name and signing key that you use: debug, release, etc.

Follow these steps to use keyless authorization your project:

  1. In Unity, go to Edit > Project Settings > XR > ARCore Extensions.

  2. In the Android Authentiation Strategy drop-down, select Keyless.

  3. Under Optional Features, check the boxes for any of the APIs listed here that you are using in your project.

  4. Generate the SHA-1 fingerprint signing key.

    1. From the Edit menu, select Project Settings > Player > Publishing Settings.

    2. Click the Keystore Manager and create a new key.

    3. Copy the SHA-1 fingerprint signing key (to be pasted in a later step).

  5. Create the OAuth client ID.

    1. In your Google Cloud Project, Create an OAuth client ID.

    2. In the SHA-1 fingerprint field, paste the SHA-1 fingerprint for the pertinent variant (from the previous step).

    3. Click CREATE to create the OAuth client ID.

API key authorization

Follow these steps to obtain and add an API key to your project:

  1. Get the key from Google Cloud Platform, as described in the Google Cloud Platform Console Help Center.

  2. In Unity, go to Edit > Project Settings > XR > ARCore Extensions.

  3. In the Android Authentiation Strategy drop-down, select API Key.

  4. In the Android API Key field, paste the API key you obtained from Google Cloud Platform.

  5. Under Optional Features, check the boxes for any of the APIs listed here that you are using in your project.

Enable Geospatial functionality in your app

After authorizing your app to call the ARCore API, you must enable Geospatial functionality in your app.

  1. Navigate to Edit > Project Settings > XR Plug-In Management > ARCore Extensions.
  2. Under Optional Features, select Geospatial.

Enable Geospatial capabilities in the session configuration

Once Geospatial functionality has been enabled in your app, enable Geospatial capabilities in your app’s AR session configuration so that it can communicate with the ARCore API:

  1. Ensure that the project Assets folder contains an ARCoreExtensionsConfig scriptable object. To create one, right-click in the Assets pane and select Create > XR > ARCore Extensions Config.

  2. Select the ARCoreExtensionsConfig scriptable object in your Assets folder and set the Geospatial Mode to Enabled.

  3. Configure the ARCore Extensions game object to use the ARCoreExtensionsConfig configuration. In the Hierarchy pane, locate the ARCore Extensions game object you created when you initially set up ARCore Extensions, and connect the ARCore Extensions Config field to the ARCoreExtensionsConfig scriptable object in your Assets folder.

Prompt user to allow usage of device data

Apps that use the ARCore Geospatial API must present the user with a prompt to acknowledge and allow the use of data from their device. See User privacy requirements for more information.

Check device compatibility

Not all devices that support ARCore also support the Geospatial API. To check the user's device for compatibility, call AREarthManager.IsGeospatialModeSupported(). If this returns FeatureSupported.Unsupported do not attempt to configure the session.

Ask user for location permissions at runtime

ARCore Extensions automatically requests the appropriate location permissions when Geospatial mode is enabled in ARCoreExtensions.Update(). If the user does not grant precise location permission, the session fails to resume, and a "permission not granted" error is produced. This is a terminate error, and requires a re-start to trigger the permission request again.

Check Geospatial availability at the device's current location

Because the Geospatial API uses a combination of VPS and GPS to determine a Geospatial pose, the API can be used as long as the device is able to determine its location. In areas with low GPS accuracy, such as indoor spaces and dense urban environments, the API will rely on VPS coverage to generate high accuracy poses. Under typical conditions, VPS can be expected to provide positional accuracy of approximately 5 meters, and rotational accuracy of 5 degrees. Use AREarthManager.CheckVpsAvailability() to determine if a given location has VPS coverage.

The Geospatial API can also be used in areas that do not have VPS coverage. In outdoor environments with few or no overhead obstructions, GPS may be sufficient to generate a pose with high accuracy.

What's next