Android アプリで Geospatial API を有効にする（Kotlin/Java）

Geospatial API を使用できるように、アプリの設定を構成します。

前提条件

続行する前に、AR の基本コンセプトと ARCore セッションを構成する方法を理解してください。

サンプルアプリと Codelab

この動画では、Geospatial API を使用して地理空間データを表示し、現実世界の場所にコンテンツを配置するアプリを作成する手順について説明します。

ジオ空間 Codelab のドキュメントで同じ手順を確認することもできます。動画で作成したサンプルアプリを実行するには、ARCore Geospatial のクイックスタートをご覧ください。

Geospatial API の詳細については、Geospatial API の概要をご覧ください。

ARCore を使った開発を初めて行う場合は、スタートガイドをご覧ください。でソフトウェアとハードウェアの要件、前提条件、使用しているプラットフォームに固有のその他の情報

クイックスタートで説明されているように、開発環境が ARCore SDK の要件を満たしていることを確認します。

ARCore API を有効にする

アプリで Visual Positioning System（VPS）を使用する前に、新しい Google Cloud プロジェクトまたは既存の Google Cloud プロジェクトで ARCore API を有効にする必要があります。このサービスは、地理空間アンカーのホスティング、保存、解決を行います。

キーレス認証が推奨されますが、API キー認証もサポートされています。

必要なライブラリをアプリに追加する

アプリでの ARCore API の呼び出しを承認したら、次にライブラリをアプリで地理空間機能を有効にします。

アプリの build.gradle ファイルで、Google Play 開発者サービスを設定して、Play 開発者サービス位置情報ライブラリを含めます。

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)'
}

セッション構成でジオ空間機能を有効にする

セッションを作成する前に、セッション構成の GeospatialMode を ENABLED に変更します。

Java

Config config = session.getConfig();
config.setGeospatialMode(Config.GeospatialMode.ENABLED);
session.configure(config);

Kotlin

// Enable the Geospatial API.
session.configure(session.config.apply { geospatialMode = Config.GeospatialMode.ENABLED })

地理空間モードが ENABLED に設定されている場合、アプリケーションは次のデータを取得できます。地理情報を取得できます。

デバイスデータの使用を許可するようユーザーに求める

ARCore Geospatial API を使用するアプリは、ユーザーに以下のプロンプトを表示する必要があります。デバイスのデータの使用を承認し、許可します。詳しくは、ユーザーのプライバシー要件情報です。

デバイスの互換性を確認する

ARCore をサポートするデバイスがすべて Geospatial API をサポートしているわけではありません。クイックスタートをご覧ください。

お客様のデバイスの互換性を確認するには、Session.checkGeospatialModeSupported() を呼び出します。false が返された場合は、次に示すように、セッションの構成を試行しないでください。このメソッドは、 UnsupportedConfigurationException。

実行時に位置情報の利用許可をユーザーに求める

アプリは実行時に位置情報の利用許可をリクエストする必要があります。

ARCore Geospatial API を使用するには、アプリで次の追加の権限を登録する必要があります。

ACCESS_FINE_LOCATION を使用して、ユーザーの位置を正確に特定します。
ACCESS_COARSE_LOCATION ユーザーの現在地を正確に特定できない場合や、ユーザープライバシー要件。ただし、Geospatial API を API リクエストはおおよその位置情報で動作します。また、ユーザーが位置情報を取得した場合、API リクエストは失敗します。権限を設定します。詳しくは以下をご確認ください。
ACCESS_INTERNET ARCore Geospatial API サービスに接続する必要があります。

<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>

Android バージョン 12 以降を搭載したデバイスの場合、ユーザーはアプリがおおよその位置情報のみにアクセスするようリクエストできます。このリクエストに対応するには、アプリに ACCESS_COARSE_LOCATION 設定済みの権限とともに ACCESS_FINE_LOCATION, 渡されます。両方の位置情報の権限を構成する必要があります。

ただし、ユーザーがおおまかな位置情報を指定すると、Geospatial API は必要な正確な位置情報を取得できなくなります。アプリが地理空間サービスに提供するのはおおよその位置情報のみの場合、地理空間サービスは設定されません。このアプリでは、おおよその位置情報で Geospatial API を使用できません。

デバイスの現在地での地理空間の利用状況を確認する

Geospatial API は VPS と GPS を組み合わせてジオ空間ポーズを決定するため、デバイスが位置情報を特定できる限り、この API を使用できます。屋内や密集した都市環境など、GPS 精度の低い地域では、API は VPS カバレッジに基づいて高精度のポーズを生成します。一般的な条件下では、VPS は位置精度が約 5 メートル、回転精度が 5 度と見込まれます。Session.checkVpsAvailabilityAsync() を使用して、特定の場所が VPS の対象かどうかを判断します。

Geospatial API は、VPS がカバーされていない地域でも使用できます。オーバーヘッド障害物がほとんどない、またはまったくない屋外環境では、GPS で高精度のポーズを生成できます。

次のステップ

デバイスカメラの地理空間ポーズを取得して、現実世界におけるユーザーのデバイスの正確な位置を特定します。
デバイスの特定の場所で VPS の可用性を確認します。