Google is committed to advancing racial equity for Black communities. See how.

Cloud Anchors developer guide for Unity targeting Android

Learn how to use the Cloud Anchor API in your own apps. If you are new to Cloud Anchors:

  • Read through the quickstart for system requirements, setup, and installation instructions.

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. You can enable Cloud Anchor capabilities in your session configuration, and enable the ARCore Cloud Anchor API for your Google Cloud Platform project.

Host a Cloud Anchor with persistence

Prior to ARCore v1.20, Cloud Anchors could only be resolved for up to 24 hours after they were first hosted. With persistent Cloud Anchors, you can now use XPSession.CreateCloudAnchor() to create a Cloud Anchor with a time to live (TTL) between one and 365 days. You can also extend the lifetime of the anchor after it is already hosted using the Cloud Anchor Management API.

// ttlDays: The anchor’s lifetime in days. Must be a positive number. The maximum
// allowed value is 1 if you are using an API key to authenticate the Cloud Anchor.
// Otherwise, the maximum allowed value is 365.

AsyncTask<CloudAnchorResult> GoogleARCore.CrossPlatform.XPSession.CreateCloudAnchor(
  UnityARUserAnchorComponent anchor, int ttlDays
)

Authentication

Your app needs a form of authentication to use Cloud Anchors. When targeting Android, Unity offers the Keyless and API Key options for authentication. Cloud Anchors with a TTL greater than one day must use Keyless authentication.

Keyless authentication

The Keyless authentication option can host a Cloud Anchor for up to 365 days. Cloud Anchors with a TTL greater than one day must use this method.

Follow these steps to configure authentication without using an API key:

  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 Developers 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 Android package name and signing certificate fingerprint. This associates the Android package name with your GCP project.

API key authentication

The API key authentication option can host a Cloud Anchor for up to one day.

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

  1. See the Google Cloud Platform Console Help Center to obtain an API key.

  2. Add the new API key to your project:

  • In Unity, go to Edit > Project Settings > ARCore Project Settings.
  • Add your API key to the Cloud Anchor API Keys field.

Mapping quality

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 generally result in more accurately resolved poses. If feature map quality cannot be estimated for a given pose, ARCore logs a warning message and returns FeatureMapQuality.Insufficient. 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 to be hosted is viewed from different angles.

FeatureMapQuality quality = GoogleARCore.CrossPlatform.XPSession.EstimateFeatureMapQualityForHosting(pose)

public enum FeatureMapQuality
{
    /// 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 to be hosted is
    /// viewed from different angles.
    Insufficient = 0,

    /// 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 they wish to host can be viewed from different angles.
    Sufficient = 1,

    /// 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.
    Good = 2,
}

API quotas

The ARCore Cloud Anchor 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

Performance considerations

Memory usage increases when you enable the Cloud Anchor API. Expect the device’s battery usage to rise due to higher network usage and CPU utilization.

Next steps