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
- Understand how anchors and Cloud Anchors work.
- Install and configure the ARCore SDK for Android.
Requirements
Hardware
- An ARCore supported device with the latest version of Google Play Services for AR installed
- A USB cable to connect the device to your development machine
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
In Android Studio, click Open.
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
In Android Studio, click Open.
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.
- Manually add Firebase to your app. The
cloud_anchor_java
package name iscom.google.ar.core.examples.java.cloudanchor
. You can find it inmain/AndroidManifest.xml
. - Download the
google-services.json
file that you generated when you added Firebase to your app. - Create a Realtime Database with Firebase.
- In Android Studio, add the
google-services.json
file to your project’sapp
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.
- Enable the ARCore API for a new or existing Google Cloud Platform project.
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.
- Open the Gradle toolpane in your Android Studio project.
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.
- Enable the ARCore API for a new or existing Google Cloud Platform project.
- Obtain an API key for this project from the Google Cloud Console.
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'sapp/manifests/AndroidManifest.xml
:
<meta-data android:name="com.google.android.ar.API_KEY" android:value="API_KEY"/>
- Include the API key in a
Build and run the sample app
Persistent Cloud Anchors
Run the app
- Make sure that your device has enabled developer options and USB debugging.
- Connect your device via USB to your development machine.
- 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:
- Locate
apksigner
in your Android SDKbuild-tools
directory. Runapksigner verify --print-certs your-app.apk
to verify that your app's application ID and SHA-1 signature match those for the OAuth 2.0 Client ID in the Google Cloud Platform project. - Locate
aapt
in your Android SDKbuild-tools
directory. Runaapt dump badging your-app.apk | grep package:
to confirm that the package name of the app’s built APK is the same as the Google Cloud Platform package name. - Make sure that you have enabled the ARCore API in Google Cloud Platform.
Place an anchor
- Once the app begins to detect planes, tap your screen to place an anchor on one of the detected planes.
- 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
- 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
- Make sure that your device has enabled developer options and USB debugging.
- Connect your device via USB to your development machine.
- 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
- Once the app begins to detect planes, tap your screen to place an anchor on one of the detected planes.
- 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
- 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
- Create a Cloud Anchors app with the ARCore Cloud Anchors with persistent Cloud Anchors codelab.
- Learn how to incorporate Cloud Anchors in your app with the Cloud Anchors developer guide.
- Manage Cloud Anchors outside of your ARCore app using the Cloud Anchors Management API.