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 に設定されている間、アプリケーションは Visual Positioning System（VPS）から地理情報を取得できます。

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

ARCore Geospatial API を使用するアプリは、デバイスのデータの使用を承認して許可するようユーザーにプロンプトを表示する必要があります。詳しくは、ユーザーのプライバシー要件をご覧ください。

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

クイックスタートで説明されているように、ARCore をサポートするすべてのデバイスが Geospatial API をサポートしているわけではありません。

お客様のデバイスの互換性を確認するには、Session.checkGeospatialModeSupported() を呼び出します。false が返された場合は、セッションを設定しようとしないでください（下記をご覧ください）。設定すると UnsupportedConfigurationException がスローされます。

実行時にユーザーに位置情報の利用許可をリクエストする

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

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

  • ACCESS_FINE_LOCATION を使用して、ユーザーの位置を正確に特定します。

  • ACCESS_COARSE_LOCATION ユーザーの位置情報を正確に特定できない場合や、ユーザーのプライバシー要件を遵守する場合。ただし、Geospatial 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 で高精度のポーズを生成できます。

次のステップ