Cloud Anchors developer guide for Android NDK

Learn how to use the ARCore Cloud Anchor API, or ARCore Cloud Anchor service, 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 the ARCore Cloud Anchor API

Before using Cloud Anchors in your app, you must first enable the ARCore Cloud Anchor API, or ARCore Cloud Anchor service, 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 Cloud Anchor API:

// Create a new ARCore session.
ArSession* session = NULL;
CHECK(ArSession_create(env, context, &session) == AR_SUCCESS);

// Create a session config.
ArConfig* config = NULL;
ArConfig_create(session, &config);
ArSession_getConfig(session, config);

// Enable Cloud Anchor mode.
ArConfig_setCloudAnchorMode(session, config,
                                AR_CLOUD_ANCHOR_MODE_ENABLED);

// Configure the session.
ArSession_configure(session, config);
ArConfig_destroy(config);

Authenticate your app with the ARCore Cloud Anchor API

You must authenticate the ARCore Cloud Anchor 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 keyless authentication.

Keyless authentication

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

  1. Enable the ARCore Cloud Anchor API for a new or existing Google Cloud Platform project.
  2. Create an OAuth client ID for your Android app in the Google Cloud Console, using the app’s application ID and signing certificate SHA-1 fingerprint. This associates the Android app with your Google Cloud Platform project.

    To retrieve the debug signing certificate fingerprint:

    • Open the Gradle toolpane in your Android Studio project.
    • Navigate to <project-name> > Tasks > android.
    • Run the signingReport task.

    • Copy the SHA-1 fingerprint for the debug variant into the SHA-1 certificate fingerprint field in the Google Cloud Console.
  3. Include com.google.android.gms:play-services-auth:16+ in your app’s dependencies.

  4. If you are using ProGuard, add it to your app’s build.gradle file with

    buildTypes {
      release {
        ...
        proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
      }
    }
    

    Add the following to your app’s proguard-rules.pro file:

    -keep class com.google.android.gms.common.** { *; }
    -keep class com.google.android.gms.auth.** { *; }
    -keep class com.google.android.gms.tasks.** { *; }
    

API key authentication

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

  1. Enable the ARCore Cloud Anchor API for a new or existing Google Cloud Platform project.
  2. Obtain an API key for this project from the Google Cloud Console.
  3. In Android Studio, add the new API key to your project. Include the API key in a <meta-data> element in the <application> element in your app's app/manifests/AndroidManifest.xml:

    <meta-data
       android:name="com.google.android.ar.API_KEY"
       android:value="API_KEY"/>
    

Host a Cloud Anchor

Hosting starts with a call to ArSession_hostAndAcquireNewCloudAnchorWithTtl(). ARCore will upload visual data, device poses, and the anchor pose to the ARCore Cloud Anchor API. The API then processes this information to construct a 3D feature map, ultimately returning a unique Cloud Anchor ID for the anchor to the device.

You can also call ArSession_hostAndAcquireNewCloudAnchor() to host an anchor with a TTL up to 24 hours (1 day), or extend the lifetime of a hosted anchor using the ARCore Cloud Anchor Management API.

Check the mapping quality of feature points

ArAnchor.ArFeatureMapQuality 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. Use ArSession_estimateFeatureMapQualityForHosting() to obtain an estimation for the feature map quality for a given camera pose.

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.

Resolve a previously hosted anchor

Call ArSession_resolveAndAcquireNewCloudAnchor() to resolve a hosted Cloud Anchor. The ARCore Cloud Anchor API periodically compares visual features from the scene against the anchor’s 3D feature map to pinpoint the user's position and orientation relative to the anchor. When it finds a match, the API returns the pose of the hosted Cloud Anchor.

You can initiate resolves for multiple Cloud Anchors in sequence. Up to 20 Cloud Anchors can be resolved simultaneously.

Cancel or remove a Cloud Anchor

Call ArAnchor_detach() to stop tracking and forget a Cloud Anchor. References to the anchor must be released separately by calling ArAnchor_release().

Check the state of a Cloud Anchor

Use ArAnchor_getCloudAnchorState() to check the status of the hosted anchor or the resolve request, including errors.

Value Description
AR_CLOUD_ANCHOR_STATE_ERROR_CLOUD_ID_NOT_FOUND Resolving failed because the ARCore Cloud Anchor API could not find the provided Cloud Anchor ID.
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_DATASET_PROCESSING_FAILED Hosting failed because the server could not successfully process the dataset for the given anchor. Try again after the device has gathered more data from the environment.
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_SERVICE_UNAVAILABLE The ARCore Cloud Anchor API was unreachable. This can happen for a number of reasons. The device might be in airplane mode or may not have a working Internet connection. The request sent to the server might have timed out with no response. There might be a bad network connection, DNS unavailability, firewall issues, or anything else that might affect the device's ability to connect to the ARCore Cloud Anchor API.
AR_CLOUD_ANCHOR_STATE_ERROR_INTERNAL A hosting or resolving task for this anchor finished with an internal error. The app should not attempt to recover from this error.
AR_CLOUD_ANCHOR_STATE_ERROR_NOT_AUTHORIZED The authorization provided by the application is not valid.
  • The Google Cloud project may not have enabled the ARCore Cloud Anchor API, or the operation you are trying to perform is not allowed.
  • If using API key authentication: the API key in the manifest is invalid, unauthorized or missing. It may also fail if the API key is restricted to a set of apps not including the current one.
  • If using keyless authentication: you have failed to create an OAuth client.
  • Google Play Services isn't installed, is too old, or is malfunctioning for some reason (e.g. services killed due to memory pressure).
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_NEW The Cloud Anchor could not be resolved because the SDK version used to resolve the anchor is newer than, and thus incompatible with, the version used to host it.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_OLD The Cloud Anchor could not be resolved because the SDK version used to resolve the anchor is older than, and thus incompatible with, the version used to host it.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOURCE_EXHAUSTED The application has exhausted the request quota allotted to the given Google Cloud project. You should request additional quota for the ARCore Cloud Anchor API for your project from the Google Developers Console.
AR_CLOUD_ANCHOR_STATE_NONE The anchor is purely local. It has never been hosted using ArSession_hostAndAcquireNewCloudAnchor(), and has not been resolved using ArSession_resolveAndAcquireNewCloudAnchor().
AR_CLOUD_ANCHOR_STATE_SUCCESS A hosting or resolving task for this anchor completed successfully.
AR_CLOUD_ANCHOR_STATE_TASK_IN_PROGRESS A hosting or resolving task for the anchor is in progress. Once the task completes in the background, the anchor will get a new state after the next call to ArSession_update().

API quotas for host and resolve requests

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

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 Cloud Anchor API.

What's next