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 に変更します。

JavaKotlin
Config config = session.getConfig();
config.setGeospatialMode(Config.GeospatialMode.ENABLED);
session.configure(config);
 
// 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 だけでも高い精度でポーズを生成できる場合があります。

次のステップ