Enable the Geospatial API for your Android NDK app (C)

Stay organized with collections Save and categorize content based on your preferences.

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 Android for Java. The sample app in the Quickstart is written in Java. The code samples in this document are for the same functionality written in C.

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.

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

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. Keyless authorization is preferred, but API Key authorization is also supported.

Keyless authorization

Get the signing key SHA-1 fingerprint, then plug it into your Google Cloud Project, and create an OAuth client ID.

Note that you need to register separately for all the different combinations of package name and signing key that you use: debug, release, etc.

If you are using the signing key for a pre-release or debug version of your app, or if your app uploads an APK instead of an AAB, get the signing key SHA-1 fingerprint from Android Studio, as follows:

  1. In your Android Studio project, open the Gradle toolpane.

  2. Navigate to <project-name> > work > Tasks > android.

  3. Run the signingReport task.

  4. Copy the SHA-1 fingerprint; you will paste it in a later step.

    For sample apps, use the debug fingerprint.

If you are using Play App Signing, where Google manages and protects your app's signing key for you, and uses it to sign optimized distribution APKs that are generated from your app bundle (AAB), get the SHA-1 fingerprint as described in Step 3: Register your app signing key with API providers.

API key authorization

If you use API key authorization, make sure that the key is either unrestricted, or that it allows the ARCore API (if restricted by API), or that it allows your app (if restricted by app). The API Key can list a collection of fingerprints, and must include the fingerprint for the release version, if it is a restricted API key.

  1. In your Google Cloud Project, under APIs & Services, select Credentials.

  2. In the top bar, click Create Credentials, and select API Key.

    Note that if you are using a restricted API key, you must edit the key to add a debug certificate fingerprint or a release certificate fingerprint to the API key.

  3. Copy the API key that was created, as you will paste it in a later step.

  4. In your Android Studio project, open app > src > AndroidManifest.xml.

  5. In the AndroidManifest.xml file, in an <application> element, add a <meta-data> element with the API key as in the following example. You can paste the API key here, then copy the entire block.

     <meta-data
        android:name="com.google.android.ar.API_KEY"
        android:value="API_KEY"/>
    

    The value stored in com.google.android.ar.API_KEY authorizes this app.

Include required libraries

In your app's build.gradle file, setup Google Play services to include the Play Services Location library and the Google Sign-In for Android library.

dependencies {
  // Apps must declare play-services-location version >= 16.
  // In the following line, substitute `16 (or later)` with the latest version.
  implementation 'com.google.android.gms:play-services-location:16 (or later)'
  // Apps must declare play-services-auth version >= 16.
  // In the following line, substitute `16 (or later)` with the latest version.
  implementation 'com.google.android.gms:play-services-auth:16 (or later)'
}

Include required ProGuard rules

When minifying your app with Proguard, you should include the following ProGuard rules in the proguard-rules.pro configuration for your app.

Use the following rules when using keyless authorization:

# Keep classes required by the Geospatial API.
-keep class com.google.android.gms.auth.** { *; }
-keep class com.google.android.gms.location.** { *; }
-keep class com.google.android.gms.common.** { *; }
-keep class com.google.android.gms.tasks.** { *; }

Use the following rules when using API key authorization:

# Keep classes required by the Geospatial API.
-keep class com.google.android.gms.location.** { *; }
-keep class com.google.android.gms.common.** { *; }
-keep class com.google.android.gms.tasks.** { *; }

Enable Geospatial capabilities in the session configuration

Before creating the session, change the GeospatialMode in your session configuration to ENABLED:

// Create a session config.
ArConfig* ar_config = NULL;
ArConfig_create(ar_session, &ar_config);

// Enable Instant Placement mode.
ArConfig_setGeospatialMode(ar_session, ar_config, AR_GEOSPATIAL_MODE_ENABLED);
CHECK(ArSession_configure(ar_session, ar_config) == AR_SUCCESS);

// Release config resources.
ArConfig_destroy(ar_config);

While the Geospatial mode is set to ENABLED, the application is allowed to obtain geographical information from the Visual Positioning System (VPS).

Prompt user to allow usage of device data

Apps that use the ARCore Geospatial API must present the user with a prompt to acknowledge and allow the use of data from their device. See User privacy requirements for more information.

Check device compatibility

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

To check the user's device for compatibility, call ArSession_isGeospatialModeSupported(). If this returns false do not attempt to configure the session (below), as doing so will cause the ArStatus to report an AR_ERROR_UNSUPPORTED_CONFIGURATION.

Ask user for location permissions at runtime

Your app must request location permissions at runtime.

To use the ARCore Geospatial API, your app needs to register the following extra permissions:

  • ACCESS_FINE_LOCATION to accurately determine the user's location.

  • ACCESS_COARSE_LOCATION for non-accurate determination of the user's location and to comply with user privacy requirements. However, the Geospatial API cannot be configured to work with coarse location, and API requests will fail when the user has set this permission. See below for more information.

  • ACCESS_INTERNET to contact the ARCore Geospatial API service.

<manifest ... >
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
  <uses-permission android:name="android.permission.INTERNET" />
</manifest>

On devices that run Android version 12 or higher, users can request that your app have access to only approximate location information. To accommodate this request, your app must have the ACCESS_COARSE_LOCATION permission configured, along with ACCESS_FINE_LOCATION, as shown above. You must configure both location permissions.

However, when users specify coarse location, doing so prevents the Geospatial API from obtaining the precise location it requires. The Geospatial service will not allow itself to be configured if your app gives it only coarse location. Your app cannot use the Geospatial API with coarse location.

What's next