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. Follow steps for on Use the ARCore API on Google Cloud and use Keyless authorization for Persistent Cloud Anchors or API Key authorization for Cloud Anchors.

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.

If Google Cloud authorization fails, see Troubleshooting steps.

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 ARCore 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 ARCore 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