Cloud Anchors developer guide for Android

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 the ARCore SDK for Android sample app.

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 hostCloudAnchorWithTtl() 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.

 /**
  * Uses the pose and other data from {@code anchor} to create a new anchor with a
  * given lifetime in days that will be hosted. The returned {@code anchor} will
  * have the Cloud Anchor state {@link Anchor.CloudAnchorState#TASK_IN_PROGRESS}.
  *
  * @param anchor The anchor whose pose is to be hosted.
  * @param 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.
  * @return The new anchor with the same pose as {@code anchor} which will be
  *     hosted.
  */
 public Anchor hostCloudAnchorWithTtl(Anchor anchor, int ttlDays);

Authentication

Your app needs a form of authentication to use Cloud Anchors. To create a Cloud Anchor with a TTL longer than twenty-four hours, the API will need to use keyless authentication.

Follow these steps to configure keyless API access:

1. If your app’s AndroidManifest.xml file contains an API key, remove it.

   Note: We also 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 project.

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

   And 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.** { *; }
   

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 = session.estimateFeatureMapQualityForHosting(frame.getCamera().getPose());

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 they wish to host
    // can be 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

• Android reference documentation