Cloud Anchors developer guide for Unity targeting Android

Caution: This page documents the ARCore SDK for Unity, which is deprecated, and no longer supported in Unity 2020 and later. This SDK should only be used by developers working on existing projects which are unable to migrate to Unity's AR Foundation.

Key Point: Developers starting new projects should instead use the ARCore Extensions for AR Foundation and refer to the latest documentation.

Learn how to use the Cloud Anchor API 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 the process used to host and resolve a Cloud Anchor.

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

• Check out one of the Cloud Anchor samples

Enable ARCore Cloud Anchor API

Before using Cloud Anchors in your app, you must first enable the ARCore Cloud Anchor API in a new or existing Google Cloud Platform project.

Enable Cloud Anchors in your app

Cloud Anchors are disabled by default in the AR session config. To enable Cloud Anchor capabilities in your app:

1. Enable Cloud Anchor capabilities in your AR session config.

2. Resume the AR session.

Host a Cloud Anchor with persistence

Prior to ARCore SDK 1.20.0, 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 1 and 365 days.

You can also extend the lifetime of the anchor after it is 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

Key Point: Cloud Anchors with a TTL greater than 1 day must use Keyless authentication.

Your app needs a form of authentication to use Cloud Anchors. When targeting Android, Unity offers the Keyless and API Key options.

The default authentication 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.

If your app uses Cloud Anchors and is built using ARCore SDK 1.24.0 or later, you must manually enable authentication in Project Settings > XR > ARCore Extensions.

Keyless authentication

The Keyless authentication option can host a Cloud Anchor for up to 365 days.

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 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

The API Key authentication option can host a Cloud Anchor for up to 1 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 increase due to higher network usage and CPU utilization.

Next steps

• ARCore Unity reference documentation