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

Cloud Anchors developer guide for ARCore Extensions for iOS

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:

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

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. Ensure that the project Assets folder contains an ARCoreExtensionsConfig scriptable object. To create one, right-click in the Assets pane and select Create > ARCore Extensions > ARCore Extensions Config.

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

  3. Configure the ARCore Extensions game object to use the ARCoreExtensionsConfig configuration:

    1. In Hierarchy pane locate the ARCore Extensions game object you created when you initially set up ARCore Extensions.

    2. Connect the ARCore Extensions Config field to the ARCoreExtensionsConfig scriptable object in your Assets folder.

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 ARAnchorManager.HostCloudAnchor(ARAnchor, int) to host 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 lifetime of the anchor in days. Must be positive. The
// maximum allowed value is 1 if using an API Key to authenticate with the
// ARCore Cloud Anchor Service, otherwise the maximum allowed value is 365.
ARCloudAnchor ARAnchorManager.HostCloudAnchor(ARAnchor anchor, int ttlDays)

Authentication

Your app needs a form of authentication to use Cloud Anchors. When targeting iOS, ARCore Extensions for Unity offers the Authentication token and API Key options for authentication.

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.

  1. Check iOS Support Enabled
  2. Select the desired iOS Authentication Strategy:
    • Authentication Token (recommended) - required for Cloud Anchors with a TTL (time to live) longer than 1 day (24 hours)
    • API Key - Cloud Anchors will have a maximum TTL of 1 day (24 hours)

Token authentication (signed JWT)

The Authentication Token option can host a Cloud Anchor for up to 365 days.

Currently, the only supported token type is a signed JWT (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 authentication 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:

  1. In the navigation menu of the Google Cloud Platform Console, go to APIs & Services > Credentials.

  2. Select the desired project, then click Create Credentials > Service account.

  3. Under Service account details, type a name for the new account, then click Create.

  4. On the Service account permissions page, go to the Select a role dropdown. Select Service Accounts > Service Account Token Creator, then click Continue.

  5. On the Grant users access to this service account page, click Done. This takes you back to APIs & Services > Credentials.

  6. On the Credentials page, scroll down to the Service Accounts section and click the name of the account you just created.

  7. On the Service account details page, scroll down to the Keys section and select Add Key > Create new key.

  8. 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://arcorecloudanchor.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.
  • expiat + 3600 (1 hour). The Unix time when the token expires, in seconds.
  • aud — The audience. The audience must be set to https://arcorecloudanchor.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 a token into the ARCore session

Note the following when you pass a token into the session:

  1. You must pass in a valid authentication token before attempting to host or resolve an anchor.

  2. ARCore ignores authentication tokens that contain spaces or special characters.

  3. ARCore ignores provided authentication tokens if the session is created with a valid API key.

    If you previously used an API key and no longer need it, we recommend:

  • 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 use when authenticating with the ARCore Cloud Anchor service
// on the iOS platform. This should be called each time the application's token is refreshed.
ARAnchorManager.SetAuthToken(string authToken);

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 > XR > ARCore Extensions.
  • 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, EstimateFeatureMapQualityForHosting 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 = ARAnchorManager.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