Try out hosting and resolving [Cloud Anchors](https://developers.google.com/ar/develop/java/cloud-anchors/introduction) in the `cloud_anchor_java` and `persistent_cloud_anchor_java` sample apps. ## Which sample app should you use? Cloud Anchors are [anchors](https://developers.google.com/ar/develop/java/anchors) that are hosted on the [**ARCore API**](https://console.cloud.google.com/apis/library/arcore) 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](https://developers.google.com/ar/develop/java/anchors) and [Cloud Anchors](https://developers.google.com/ar/develop/java/cloud-anchors/introduction) work. - [Install and configure](https://developers.google.com/ar/develop/java/quickstart) the ARCore SDK for Android. ## Requirements ### Hardware - An [ARCore supported device](https://developers.google.com/ar/devices) with the latest version of [Google Play Services for AR](https://play.google.com/store/apps/details?id=com.google.ar.core) installed - A USB cable to connect the device to your development machine ### Software - [Android Studio](https://developer.android.com/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](https://github.com/google-ar/arcore-android-sdk) 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.](https://firebase.google.com/docs/android/setup#manually_add_firebase) 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.](https://firebase.google.com/docs/database/android/start#create_a_database) 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](https://developers.google.com/ar/develop/authorization?platform=android) 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](https://developer.android.com/studio/debug/dev-options). 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](https://developers.google.com/ar/develop/authorization/troubleshooting?platform=android). ### 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](https://developer.android.com/studio/debug/dev-options). 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 - Create a Cloud Anchors app with the [ARCore Cloud Anchors with persistent Cloud Anchors codelab](https://codelabs.developers.google.com/codelabs/arcore-cloud-anchors#0). - Learn how to incorporate Cloud Anchors in your app with the [Cloud Anchors developer guide](https://developers.google.com/ar/develop/java/cloud-anchors/developer-guide). - Manage Cloud Anchors outside of your ARCore app using the [Cloud Anchors Management API](https://developers.google.com/ar/develop/java/cloud-anchors/management-api).