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.
Token (signed JWT) 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.
ARCore supports the authorization of API calls in iOS using a (JSON Web token). The token must be signed by a Google Service account.
In order to generate tokens for iOS, you must have an endpoint on your server that satisfies the following requirements:
Your own authorization mechanism must protect the endpoint.
The endpoint must generate a new token every time, such that:
- Each user gets a unique token.
- Tokens don’t immediately expire.
Create a service account and signing key
Follow these steps to create a Google service account and signing key:
In the navigation menu of the Google Cloud Platform Console, go to APIs & Services > Credentials.
Select the desired project, then click Create Credentials > Service account.
Under Service account details, type a name for the new account, then click Create.
On the Service account permissions page, go to the Select a role dropdown. Select Service Accounts > Service Account Token Creator, then click Continue.
On the Grant users access to this service account page, click Done.
This takes you back to APIs & Services > Credentials.
On the Credentials page, scroll down to the Service Accounts section and click the name of the account you just created.
On the Service account details page, scroll down to the Keys section and select Add Key > Create new key.
Select JSON as the key type and click Create.
This downloads a JSON file containing the private key to your machine. Store the downloaded JSON key file in a secure location.
Create tokens on your server
To create new tokens (JWTs) on your server, use the standard JWT libraries and the JSON file that you securely downloaded from your new service account.
Create tokens on your development machine
To generate JWTs on your development machine, use the following
oauth2l
command:
oauth2l fetch --cache "" --jwt --json $KEYFILE --audience "https://arcore.googleapis.com/"
Specifying an empty cache location using the --cache
flag is necessary to
ensure that a different token is produced each time. Be sure to trim the
resulting string. Extra spaces or newline characters will cause the API to
reject the token.
Sign the token
You must use the RS256
algorithm and the following claims to sign the JWT:
iss
— The service account email address.sub
— The service account email address.iat
— The Unix time when the token was generated, in seconds.exp
—iat
+3600
(1 hour). The Unix time when the token expires, in seconds.aud
— The audience. The audience must be set tohttps://arcore.googleapis.com/
.
Non-standard claims are not required in the JWT payload, though you may find the
uid
claim useful for identifying the corresponding user.
If you use a different approach to generate your JWTs, such as using a Google API in a Google-managed environment, make sure to sign your JWTs with the claims in this section. Above all, make sure that the audience is correct.
Pass the token in the ARCore session
Note the following when you pass a token into the session:
You must pass in a valid authorization token before attempting to host or resolve an anchor.
ARCore ignores authorization tokens that contain spaces or special characters.
ARCore ignores provided authorization tokens if the session is created with a valid API key.
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.
Tokens typically expire after one hour. If there is a possibility that your token may expire while in use, obtain a new token and call
ARAnchorManager.SetAuthToken(string authToken)
with the new token.
When you obtain a token, pass it into your ARCore session using
ARAnchorManager.SetAuthToken()
:
// Designate the token to authorize ARCore API calls
// on the iOS platform. This should be called each time the application's token is refreshed.
ARAnchorManager.SetAuthToken(string authToken);
Configure the project for JWT
In Unity, go to Edit > Project Settings > XR > ARCore Extensions.
Select the iOS Support Enabled checkbox.
In the iOS Authentication Strategy drop-down, select Authentication Token.
Under Optional Features, check the boxes for any of the APIs listed here that you are using in your project.
API key authorization
Follow these steps to obtain and add an API key to your project:
Get the key from Google Cloud Platform, as described in the Google Cloud Platform Console Help Center.
In Unity, go to Edit > Project Settings > XR > ARCore Extensions.
Select the iOS Support Enabled checkbox.
In the iOS Authentication Strategy drop-down, select API Key.
In the iOS API Key field, paste the API key you obtained from Google Cloud Platform.
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.
- Navigate to Edit > Project Settings > XR Plug-In Management > ARCore Extensions. Make sure that iOS Support Enabled is selected.
- 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:
- 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.
Select the ARCoreExtensionsConfig scriptable object in your Assets folder and set the Geospatial Mode to Enabled.
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
To enable Unity's location services in a script that triggers the runtime permission requests, do the following:
In Project Settings > iOS > Other Settings > Location Usage Description, enter the name of the app that is requesting permissions.
Enable Unity's location services to trigger the runtime permission request, as follows:
public void OnEnable() { Input.location.Start(); } public void OnDisable() { Input.location.Stop(); }
See Unity's
LocationService
documentation for more information.
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
- Obtain the device camera's Geospatial pose to determine the exact location of the user's device in the real world.
- Check VPS availability at a device's given location.