Cloud Anchors quickstart for Android

Try out hosting and resolving Cloud Anchors in the cloud_anchor_java and persistent_cloud_anchor_java sample apps.

Which sample app should you use?

Cloud Anchors are anchors that are hosted on the ARCore API cloud endpoint. This API enables users to share experiences in the same app. Persistent Cloud Anchors are Cloud Anchors that can be hosted for more than 24 hours.

  • persistent_cloud_anchor_java is an implementation of a collaborative project use case. It uses keyless authorization to authorize ARCore API calls. Because it doesn’t use a Firebase backend to share Cloud Anchor IDs between devices, it is much easier to get up and running.
  • cloud_anchor_java is an implementation of a multi-player use case. It uses an API key to authorize ARCore API calls.

Prerequisites

Requirements

Hardware

Software

  • Android Studio version 3.0 or later with Android SDK Platform version 7.0 (API level 24) or higher
  • The ARCore SDK for Android, which you can get in one of two ways:
    • Download it from GitHub and extract it on your machine
    • Clone the repository with the following command: 
      git clone https://github.com/google-ar/arcore-android-sdk.git

Open the sample app in Android Studio

The ARCore SDK provides the cloud_anchor_java and persistent_cloud_anchor_java sample apps to demonstrate Cloud Anchors functionality. Follow these steps to open the apps in Android Studio.

Persistent Cloud Anchors

  1. In Android Studio, click Open.

  2. Navigate to the place where the arcore-android-sdk directory is stored on your machine. Do not open the entire SDK folder. Instead, go to samples > persistent_cloud_anchor_java and click Open.

Cloud Anchors

  1. In Android Studio, click Open.

  2. Navigate to the place where the arcore-android-sdk directory is stored on your machine. Do not open the entire SDK folder. Instead, go to samples > cloud_anchor_java and click Open.

Set up Cloud Anchor ID sharing

Cloud Anchor IDs are strings that identify hosted Cloud Anchors. They are used to resolve, or render the 3D objects attached to, the hosted anchors.

Persistent Cloud Anchors

Cloud Anchor ID sharing is maintained locally in the app. You won’t need to do anything here.

Cloud Anchors

The cloud_anchor_java sample app uses Firebase's Realtime Databases to share Cloud Anchor IDs between devices. You can use a different solution in your own apps.

  1. Manually add Firebase to your app. The cloud_anchor_java package name is com.google.ar.core.examples.java.cloudanchor. You can find it in main/AndroidManifest.xml.
  2. Download the google-services.json file that you generated when you added Firebase to your app.
  3. Create a Realtime Database with Firebase.
  4. In Android Studio, add the google-services.json file to your project’s app directory.

Authorize ARCore API calls

Authorize calls to the ARCore API to host and resolve Cloud Anchors for your app.

Persistent Cloud Anchors

Use keyless authorization with the ARCore API in persistent_cloud_anchor_java to create a Cloud Anchor with a TTL longer than 24 hours.

  1. Enable the ARCore 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 persistent_cloud_anchor_java > 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.

Cloud Anchors

Use API key authorization with the ARCore API in cloud_anchor_java to host and resolve Cloud Anchors with TTLs up to 24 hours.

  1. Enable the ARCore 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 your new API key to the cloud_anchor_java 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"/>

Build and run the sample app

Persistent Cloud Anchors

Run the app

  1. Make sure that your device has enabled developer options and USB debugging.
  2. Connect your device via USB to your development machine.
  3. In Android Studio, select your device as the deployment target and click Run.

persistent_cloud_anchor_java should launch on your device, prompting ARCore to detect the planes in front of the device’s camera.

Error: ERROR_NOT_AUTHORIZED

If you encounter this error, confirm that the OAuth Client ID has been correctly made for the app:

Place an anchor

  1. Once the app begins to detect planes, tap your screen to place an anchor on one of the detected planes.
  2. Tap the HOST button to host the placed anchor. This sends a host request to the Google Cloud Anchor API, which includes data representing the anchor’s position relative to the visual features near it.

A successful host request establishes an anchor at the placed location and assigns it a Cloud Anchor ID. If the host request is successful, the app should display a room code. You can use this code to access previously hosted anchors for this room on any device.

Resolve an anchor

  1. Tap RESOLVE and enter a previously returned room code to access the anchors hosted in this room. This sends a resolve request to the ARCore API, which returns the IDs of all anchors currently hosted in the room. persistent_cloud_anchor_java will use these IDs to render 3D objects attached to the hosted anchors.

Cloud Anchors

Run the app

  1. Make sure that your device has enabled developer options and USB debugging.
  2. Connect your device via USB to your development machine.
  3. In Android Studio, select your device as the deployment target and click Run.

cloud_anchor_java should launch on your device, prompting ARCore to detect the planes in front of the device’s camera.

Error: com.google.firebase.database.DatabaseException: Failed to get FirebaseDatabase instance: Specify DatabaseURL within FirebaseApp or from your getInstance

If you encounter this error, ensure that the firebase_url property is present in google-services.json. You can obtain the correct value for this property by ensuring that the Realtime Database has been created and downloading google-services.json.

Place an anchor

  1. Once the app begins to detect planes, tap your screen to place an anchor on one of the detected planes.
  2. Tap the HOST button to host the placed anchor. This sends a host request to the Google Cloud Anchor API, which includes data representing the anchor’s position relative to the visual features near it.

A successful host request establishes an anchor at the placed location and assigns it a Cloud Anchors ID. If the host request is successful, the app should display a room code. You can use this code to access previously hosted anchors for this room on any device.

Resolve an anchor

  1. Tap RESOLVE and enter a previously returned room code to access the anchors hosted in this room. This sends a resolve request to the ARCore API, which returns the IDs of all anchors currently hosted in the room. cloud_anchor_java will use these IDs to render 3D objects attached to the hosted anchors.

What’s next