Thanks for tuning in to Google I/O. Check out the sessions.

Enable the Geospatial API for your iOS app

Configure your app's settings so that it can use the Geospatial API.

Prerequisites

Make sure that you understand fundamental AR concepts and how to configure an ARCore session before proceeding.

If you want to run a sample app that demonstrates the functionality described here, see the ARCore Geospatial quickstart for iOS.

See the Introduction to the Geospatial API for more information about the Geospatial API.

If you're new to developing with ARCore, see Getting started for information about software and hardware requirements, prerequisities and other information specific to the platforms you are using.

Add the ARCore SDK to your app

Update the Podfile for your app to include the ARCore SDK and supported iOS versioning. To do this:

  1. Add the following platform and pod to your project's Podfile:

    platform :ios, '11.0'
pod 'ARCore/Geospatial', '~> 1.37.0'

    You may also specify platform :ios, '10.0', if you want to support iOS 10, but note that the Geospatial API will only function at runtime on iOS >= 11.

  2. Open a Terminal window and run pod install from the folder where your Xcode project exists.

    This generates an .xcworkspace file that you use to build and run the app.

Be sure your development environment satisfies the ARCore SDK requirements, as described in the Quickstart.

Enable the ARCore API

Before using the Visual Positioning System (VPS) in your app, you must first enable the ARCore API in a new or existing Google Cloud Platform project. This service is responsible for hosting, storing, and resolving Geospatial anchors.

Set up authorization

To make Geospatial API calls to the VPS, your app needs authorization. You may use signed JSON Web Token (JWT) or API key authorization.

Token (signed JWT) authorization

If you previously used an API key and no longer need it, delete it in the Google Cloud Platform Console and remove it from your app.

ARCore supports the authorization of API calls in iOS using a (JSON Web token). The token must be signed by a Google Service account.

In order to generate tokens for iOS, you must have an endpoint on your server that satisfies the following requirements:

  • Your own authorization mechanism must protect the endpoint.

  • The endpoint must generate a new token every time, such that:

    • Each user gets a unique token.
    • Tokens don’t immediately expire.

Create a service account and signing key

Follow these steps to create a Google service account and signing key:

  1. In the navigation menu of the Google Cloud Platform Console, go to APIs & Services > Credentials.

  2. Select the desired project, then click Create Credentials > Service account.

  3. Under Service account details, type a name for the new account, then click Create.

  4. On the Service account permissions page, go to the Select a role dropdown. Select Service Accounts > Service Account Token Creator, then click Continue.

  5. On the Grant users access to this service account page, click Done.

    This takes you back to APIs & Services > Credentials.

  6. On the Credentials page, scroll down to the Service Accounts section and click the name of the account you just created.

  7. On the Service account details page, scroll down to the Keys section and select Add Key > Create new key.

  8. Select JSON as the key type and click Create.

    This downloads a JSON file containing the private key to your machine. Store the downloaded JSON key file in a secure location.

Create tokens on your server

To create new tokens (JWTs) on your server, use the standard JWT libraries and the JSON file that you securely downloaded from your new service account.

Create tokens on your development machine

To generate JWTs on your development machine, use the following oauth2l command:

oauth2l fetch --cache "" --jwt --json $KEYFILE --audience "https://arcore.googleapis.com/"

Specifying an empty cache location using the --cache flag is necessary to ensure that a different token is produced each time. Be sure to trim the resulting string. Extra spaces or newline characters will cause the API to reject the token.

Sign the token

You must use the RS256 algorithm and the following claims to sign the JWT:

  • iss — The service account email address.
  • sub — The service account email address.
  • iat — The Unix time when the token was generated, in seconds.
  • exp — iat + 3600 (1 hour). The Unix time when the token expires, in seconds.
  • aud — The audience. The audience must be set to https://arcore.googleapis.com/.

Non-standard claims are not required in the JWT payload, though you may find the uid claim useful for identifying the corresponding user.

If you use a different approach to generate your JWTs, such as using a Google API in a Google-managed environment, make sure to sign your JWTs with the claims in this section. Above all, make sure that the audience is correct.

Pass the token in the ARCore session

The ARCore session is the main entry point to the ARCore Geospatial API. To use the Geospatial API, you have to create a GARSessionConfiguration and set the geospatialMode property for it, as described in Configure an ARCore session in iOS.

  1. Construct a session using sessionWithError: and pass in the token:

    NSError *error = nil;
GARSession *session = [GARSession sessionWithError:&error];

    When authorizing with the ARCore SDK, the token must be a nonempty ASCII string with no spaces or control characters. ARCore will use this until you pass in another token.

    When you obtain a token, pass it into the session using setAuthToken:. Otherwise, the session will use the most recent valid authorization token that you passed in. Call this method each time you refresh your token:

    - (void)setAuthToken:(NSString *)authToken;

  2. Create a GARSessionConfiguration and set the geospatialMode property for it.

  3. Use setConfiguration:error: (GARSession) to set the configuration.

Note the following when you pass a token into the session:

  • If you have used an API key to create the session, ARCore will ignore the token and log an error.

    If you no longer need the API key, delete it in the Google Developers Console and remove it from your app.

  • ARCore ignores tokens that contain spaces or special characters.

  • Tokens typically expire after one hour. If there is a possibility that your token may expire while in use, obtain a new token and pass it to the API.

API key authorization

Get the API key

  1. In your Google Cloud Project, obtain an API key as described in Creating an API key.

  2. Copy the API key, as you will paste it, in a later step.

  3. If you are creating an API key for your app's release version, edit the API key, and add restrictions, as described in Applying API key restrictions.

    You must also specify the bundle ID for restricted API keys.

Create the ARCore session with the API key

The ARCore session is the main entry point to the ARCore Geospatial API. To use the Geospatial API, you have to create a GARSessionConfiguration with the geospatialMode property, as described in Configure an ARCore session in iOS:

In Xcode, in your app, add your API key to the GARSession. Paste the API key you copied from your Google Cloud Project, as in the following example:

self.garSession = [GARSession sessionWithAPIKey:@"your-api-key"
                               bundleIdentifier:nil
                                          error:&error];

Enable Geospatial capabilities in the session configuration

Check device compatibility

Not all devices that support ARCore also support the Geospatial API, as described in the quickstart.

Use GARSession.isGeospatialModeSupported: to check the device, as in the following:

if (![self.garSession isGeospatialModeSupported:GARGeospatialModeEnabled]) {
  [self setErrorStatus:@"GARGeospatialModeEnabled is not supported on this device."];
  return;
}

GARSessionConfiguration *configuration = [[GARSessionConfiguration alloc] init];
configuration.geospatialMode = GARGeospatialModeEnabled;
[self.garSession setConfiguration:configuration error:&error];
if (error) {
  [self setErrorStatus:[NSString stringWithFormat:@"Failed to configure GARSession: %d",
                                                  (int)error.code]];
  return;
}

Ask user for location permissions at runtime

Your app must request the following location permissions at runtime, before configuring the session:

Check Geospatial availability at the device's current location

Because the Geospatial API uses a combination of VPS and GPS to determine a Geospatial transform, the API can be used as long as the device is able to determine its location. In areas with low GPS accuracy, such as indoor spaces and dense urban environments, the API will rely on VPS coverage to generate high accuracy transforms. Under typical conditions, VPS can be expected to provide positional accuracy of approximately 5 meters, and rotational accuracy of 5 degrees. Use GARSession.checkVPSAvailabilityAtCoordinate:completionHandler: to determine if a given location has VPS coverage.

The Geospatial API can also be used in areas that do not have VPS coverage. In outdoor environments with few or no overhead obstructions, GPS may be sufficient to generate a transform with high accuracy.

What's next