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.

Cloud Anchors developer guide for Unity targeting iOS

Stay organized with collections Save and categorize content based on your preferences.

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. Apps that host and resolve Cloud Anchors with a TTL greater than 1 day must use token (signed JWT) authentication.

Token (signed JWT) authentication

The authentication token option can host a Cloud Anchor for up to 365 days. Cloud Anchors with a TTL greater than one day must use this method. 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.

Currently, the only supported token type is a signed JWT (that is, a JSON Web token signed by a Google Service account). See the official JWT website for an introduction to JWTs.

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 --jwt --json $KEYFILE $AUDIENCE --cache ""

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 because extra spaces or newline characters will cause ARCore 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. Must be set to https://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 a token into the ARCore session

When you obtain a token, pass it into your ARCore session using XPSession.SetAuthToken():

// Set 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.
XPSession.SetAuthToken(string authToken);

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

  • If you do not pass in a valid token before attempting to host or resolve an anchor, you will get authentication errors.
  • ARCore ignores tokens that contain spaces or special characters. ARCore also ignores all tokens if you create your session with a valid API key. 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.
  • Tokens typically expire after one hour. If there is a possibility that your token may expire while in use, obtain a new token and pass it to the API.

API key authentication

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

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

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.

  • 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