Cloud Anchors developer guide for Unity targeting Android

Caution: The older ARCore Cloud Anchor API has been deprecated and will not be supported after August 31, 2023. If your app is using this API, you must update it to use the new ARCore API endpoint as soon as possible.

Learn how to use Cloud Anchors in your own apps.

Prerequisites

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

If you are new to Cloud Anchors, make sure that you understand how anchors and Cloud Anchors work.

Enable Cloud Anchors in your app

Cloud Anchors are disabled by default in ARCore. The sample app ships with Cloud Anchors enabled for demo purposes only. Before using Cloud Anchors 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 Cloud Anchors.

You’ll also need to enable Cloud Anchor capabilities in your app’s AR session configuration so that it can communicate with the ARCore API:

1. Enable Cloud Anchor capabilities in your AR session config.
2. Resume the AR session.

Authenticate your app with the ARCore API

You must authenticate the ARCore API in your app for it to host and resolve Cloud Anchors. When targeting Android, Unity offers the Keyless and API Key options for authentication. Apps that host and resolve Cloud Anchors with a TTL greater than 1 day must use keyless authentication.

The default authentication strategy for new Unity projects built with ARCore v1.24 or later is DoNotUse. This is to prevent apps from being built with unnecessary libraries. If your app uses Cloud Anchors and is built using ARCore v1.24 or later, you must manually enable authentication in the Unity project settings.

Keyless authentication

Use keyless authentication to host and resolve Cloud Anchors with TTLs between 1 and 365 days.

1. Select Keyless to clear any API key stored from the previous Cloud Anchors setting and to add necessary dependencies and Proguard exceptions. If you previously used an API key and no longer need it, we recommend deleting it in the Google Cloud Platform Console and removing it from your app after migrating users to the newest version.
2. Create an OAuth client for your Android app in the Google Developers Console, using the app's application ID and signing certificate fingerprint. This associates the Android application ID with your Google Cloud Platform project.

API key authentication

Use API key authentication to host and resolve Cloud Anchors with TTLs up to 24 hours (1 day).

1. See the Google Cloud Platform Console Help Center to obtain an API key.
2. Go to Edit > Project Settings > ARCore Project Settings and add your API key to the Cloud Anchor API Keys field to add the new API key to your project.

Check the mapping quality of feature points

FeatureMapQuality indicates the quality of feature points seen by ARCore in the preceding few seconds from a given camera pose. Cloud Anchors hosted using higher quality features are generally more accurately resolved.

Value	Description
Insufficient	The quality of feature points identified from the pose in the preceding few seconds is low. This state indicates that ARCore will likely have more difficulty resolving the Cloud Anchor. Encourage the user to move the device so that the desired position of the Cloud Anchor that they wish to host can be viewed from different angles.
Sufficient	The quality of feature points identified from the pose in the preceding few seconds is likely sufficient for ARCore to successfully resolve a Cloud Anchor, although the accuracy of the resolved pose will likely be reduced. Encourage the user to move the device so that the desired position of the Cloud Anchor that they wish to host can be viewed from different angles.
Good	The quality of feature points identified from the pose in the preceding few seconds is likely sufficient for ARCore to successfully resolve a Cloud Anchor with a high degree of accuracy.

API quotas for host and resolve requests

The ARCore API has the following quotas for request bandwidth:

Quota type	Maximum	Duration	Applies to
Number of anchors	unlimited	N/A	project
Anchor host requests	30	minute	IP address and project
Anchor resolve requests	300	minute	IP address and project

Best practices for a good user experience

Instruct users to do the following to ensure a good user experience on your app:

• Wait a few seconds after the session starts before attempting to host an anchor. This gives the tracking some time to stabilize.
• When selecting a location to host the anchor, try to find an area with visual features that are easily distinguishable from one another. For best results, avoid reflective surfaces or surfaces that lack visual features, such as blank white walls.

• Keep the camera trained on the center of interest and move the device around to map the environment from different angles, maintaining roughly the same physical distance throughout. Do this for up to 30 seconds. This will help capture more visual data and make resolving more robust.

  Note: Moving around the center of interest is not the same as standing in one place and rotating, as someone might do when taking a panorama shot. Users should physically move around the environment.

• Make sure that there is sufficient lighting in the real-life environment while hosting and resolving Cloud Anchors.

Deprecation policy

• Apps built with ARCore SDK 1.12.0 or higher are covered by the Cloud Anchor API deprecation policy.
• Apps built with ARCore SDK 1.11.0 or lower are unable to host or resolve Cloud Anchors due to the SDK's use of an older, deprecated ARCore API.

What’s next

• Check out the ARCore for Unity reference documentation for more ways to use ARCore in your app.