The ARCore Cloud Anchor API, or ARCore Cloud Anchor service, provides cloud anchor capabilities for your iOS apps, making it possible for users on both iOS and Android devices to share AR experiences.
This guide shows you how to:
- Set up your development environment to work with Cloud Anchors
- Try out hosting and resolving anchors in a sample app
- Xcode version 13.0 or later
- Cocoapods 1.4.0 or later if using Cocoapods
- An ARKit-compatible Apple device running iOS 11.0 or later (deployment target of iOS 10.0 or later required)
Using Cloud Anchors
The following steps use the Cloud Anchors sample app to show you the critical tasks for configuring and building an app that supports ARCore Cloud Anchors.
Get the Cloud Anchors sample app
Clone or download the ARCore SDK for iOS from GitHub to obtain the sample app code.
Open a Terminal or Finder window and navigate to the folder where you cloned or downloaded the SDK.
You can find the sample app code in
The persistent cloud anchors sample app code is in
The sample app performs the following important tasks as part of setting up the session:
- Creating a
- Setting a
GARSessionDelegateto get callbacks from hosting and resolving operations.
- Creating an
ARSessionand running it
- Setting an
ARFrames to the
Set up Cloud Anchor ID sharing
The Cloud Anchors sample app uses Firebase for sharing Cloud Anchor IDs between devices. You can use a different solution in your own apps.
To set up Firebase database in the sample app:
- Follow the Firebase instructions for adding Firebase to your app.
- Download the
GoogleService-Info.plistfile generated as part of adding Firebase to your app.
- Enable Firebase storage for the sample:
- Go to the Firebase console and select the project you set up for the sample app.
- Select the Database panel.
- On the Realtime Database option, click Get Started.
- The Security rules for Realtime Database menu opens.
- For purposes of running the sample, select Start in test mode.
- Note that if you are using Firebase for an app that you plan to publish, you should use more restrictive security rules.
- In Xcode, add the
GoogleService-Info.plistfile to your app, next to
Add an API Key
To use Cloud Anchors, you'll need to add an API key to the app.
Obtain an API key. See Setting up API keys in the Google Cloud Platform Console Help Center if you are new to working with API keys.
Enable the ARCore Cloud Anchor API for your Google Cloud Platform project.
In Xcode, add your API key to the app. To do this, add the key to the following code in
self.gSession = [GARSession sessionWithAPIKey:@"Replace me with your API key." bundleIdentifier:nil error:nil];
Run pod update
The CloudAnchorExample app ships with a
Podfile preconfigured with the
ARCore SDK and iOS versions that you'll need. To install these dependencies:
- Open a Terminal window and run
pod updatefrom the folder where the Xcode project exists.
This generates an
.xcworkspacefile that you'll use later to build and run the app.
See Add the ARCore SDK to your app
for details on configuring the
Podfile in your own apps.
.xcworkspacefile for the project in Xcode.
To avoid build errors, make sure you are building from the
.xcworkspacefile and not the
Change the app bundle ID
In Xcode, change the app's bundle ID so that you can sign the app with your team.
Build and run the app
Connect your device and launch the app in Xcode.
(Optional) If you are building and running the sample app, see the following section for details on using the app to host and resolve Cloud Anchors.
Try out the sample app
Build and run the sample app from the
.xcworkspacefile to launch it on your device.
If prompted, grant camera permissions to the app. ARKit then starts detecting planes in front of your camera.
Tap HOST to enter hosting mode. A room code for sharing hosted anchors is generated and appears on your screen.
Tap a plane to start hosting a cloud anchor there.
- The app places an Andy Android object on the plane and attaches an anchor to it.
- A host request is sent to the ARCore Cloud Anchor API. The host request includes data representing the anchor's position relative to the visual features near it.
- Once the anchor is hosted, it gets an ID that is used for resolving cloud anchors in this space.
Tap RESOLVE and enter a room code to access previously hosted Cloud Anchors for this room, using the same or a different device.
- A resolve request is sent to the ARCore Cloud Anchor API.
- The resolve request includes a cloud anchor ID. If the ID matches a hosted anchor and localization is successful, the server returns the transform of the anchor in your local coordinates.
- The sample app uses the transform to add the anchor to your scene and render virtual objects attached to it.
Add the ARCore SDK to your apps
In your own apps, you'll need to update your
Podfile to include the
ARCore SDK and supported iOS versioning. To do this:
Add the following
podto your project's
platform :ios, '11.0' pod 'ARCore/CloudAnchors', '~> 1.36.0'
- Open a Terminal window and run
pod updatefrom the folder where your Xcode project exists.
This generates an
.xcworkspacefile that you use to build and run the app.
Persistent cloud anchors
As described in Host a Cloud Anchor with persistence,
you can give the cloud anchor a time-to-live up to 365 days. Sample code for
using persistent cloud anchors is available in the
directory in the ARCore SDK for iOS from GitHub.
See the Cloud Anchors Developer Guide for iOS to explore the sample app code and learn more about working with Cloud Anchors in your own apps.
Review details in the ARCore iOS API Reference.