アプリで Geospatial API を設定する

対象となる XR デバイス

このガイダンスは、次のようなタイプの XR デバイス向けのエクスペリエンスを構築する際に役立ちます。

XR デバイスのタイプについて →

有線 XR グラス

オーディオ＆
ディスプレイ グラス

XR デバイスのタイプについて →

アプリで Geospatial API を使用するには、Google Cloud の ARCore API にアクセスするようにアプリを設定する必要があります。この API には、Google ストリートビューのデータを使用して正確な位置情報を提供する Visual Positioning Service が含まれています。

このガイドでは、API にアクセスするための適切な API と認可方法を有効にした Google Cloud プロジェクトを設定する方法について説明します。

Google Cloud プロジェクトを設定するか、既存のプロジェクトを使用する

既存の Google Cloud プロジェクトがある場合は、それを選択します。

プロジェクト セレクタに移動

既存のプロジェクトがない場合は、プロジェクトを作成します。

新しいプロジェクトを作成

ARCore API を有効にする

ARCore API を使用するには、プロジェクトで有効にする必要があります。

ARCore API を有効にする

Google Cloud の認可を設定する

Android アプリケーションは、2 つの異なる認可方法を使用して ARCore API と通信できます。推奨される方法は、キーレス認可（OAuth 2.0）と API キー認可です。

• キーレス認可では、アプリケーションのパッケージ名と署名鍵のフィンガープリントを組み合わせてアプリケーションを認可します。

• API キーは、Google Cloud プロジェクトを識別する文字列です。API キーは通常、クライアントがアクセスできるため、一般的に安全とは見なされません。ARCore API との通信には、キーレス認証の使用を検討してください。

キーレス認可

キーレス認証を使用してアプリを認可するには、OAuth 2.0 クライアント ID を作成します。

1. Google Cloud で、[認証情報] ページに移動します。

   [認証情報] に移動

2. [認証情報を作成] をクリックし、メニューから [OAuth クライアント ID] を選択します。

3. 必須フィールドに次のように入力します。

   • アプリケーションの種類: [Android] を選択します。
   • パッケージ名: AndroidManifest.xml で宣言されているパッケージ名を使用します。
   • SHA-1 証明書フィンガープリント: クライアント認証の手順に沿って、SHA-1 証明書フィンガープリントを取得します。

4. [作成] をクリックします。

重要: アプリに異なる署名鍵で署名することは一般的です。使用する署名鍵ごとにクライアント ID を作成する必要があります。通常、これはデバッグ用の署名鍵とリリース用の署名鍵です。承認に失敗した場合は、トラブルシューティング ガイドをご覧ください。

API キー

Google Cloud コンソールから API キーを作成する手順は次のとおりです。

1. Google Cloud コンソールで、[認証情報] ページに移動します。

   [認証情報] に移動

2. [認証情報を作成] をクリックし、メニューから [API キー] を選択します。

3. ARCore API の API 制限を追加します。詳細については、API キーの制限を適用するをご覧ください。

4. [作成] をクリックします。[API キーを作成しました] ダイアログに、新しく作成されたキーの文字列が表示されます。

Android Studio で、新しい API キーをプロジェクトに追加します。アプリの AndroidManifest.xml の <application> 要素の <meta-data> 要素に API キーを追加します。

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

必要な権限をリクエストする

Jetpack XR で ARCore の Geospatial API を使用するには、アプリで次の実行時の権限をリクエストする必要があります。

• ACCESS_FINE_LOCATION: ユーザーの正確な位置情報を特定するために必要です。

モバイル デバイスでは、Geospatial API に次の権限も必要です。

• android.permission.CAMERA: デバイスのカメラにアクセスするために必要です。
• android.permission.INTERNET: Google Cloud サービスとの通信に必要です。

セッションにアクセスする

Jetpack XR ランタイム Session を介して Geospatial 情報にアクセスします。このランタイムは、アプリが作成する必要があります。

セッションを構成する

Geospatial API は、XR セッションではデフォルトで有効になっていません。アプリで Session に GeospatialMode を構成して、明示的に有効にする必要があります。次のモードを使用できます。

• GeospatialMode.SPATIAL: Geospatial API が有効になっています。Geospatial API は、Visual Positioning System（VPS）、グローバル ポジショニング システム（GPS）データ、デバイスのモーション センサーを使用して、デバイスの地理空間ポーズを特定します。このモードは、スマートグラス デバイスでは使用できません。
• GeospatialMode.INERTIAL: Geospatial API が低電力モードで有効になります。Geospatial API は、GPS とデバイスのモーション センサーのみを使用して、デバイスの地理空間ポーズを特定します。このモードは、スマートグラス デバイスでのみ利用できます。
• GeospatialMode.DISABLED: Geospatial API が無効になります。別のモードからこのモードに移行すると、Geospatial API は取得したすべてのリソースを解放し、トラッキングを停止します。

すべてのデバイスがすべての Geospatial モードに対応しているわけではありません。詳しくは、GeospatialMode をご覧ください。XrDevice.isGeospatialSupported を使用して、特定の GeospatialMode がサポートされているかどうかを確認します。

次のコードサンプルは、Session.configure を使用して GeospatialMode を設定する方法を示しています。

// Define the configuration object to enable Geospatial features.
val newConfig = Config.Builder(session.config)
    .setGeospatial(GeospatialMode.SPATIAL)
    .build()
// Apply the configuration to the session.
try {
    when (val configResult = session.configure(newConfig)) {
        is SessionConfigureSuccess -> {
            // The session is now configured to use the Geospatial API.
        }

        else -> {
            // Handle other configuration errors (e.g., missing library dependencies).
        }
    }
} catch (e: UnsupportedOperationException) {
    // Handle configuration failure if the mode is not supported.
}
Setup.kt

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

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

Geospatial オブジェクトを使用する

セッションを構成したら、Geospatial.getInstance を使用して Geospatial オブジェクトを取得します。Geospatial オブジェクトは、状態が GeospatialTrackingState.RUNNING の場合にのみ使用します。

次のコードサンプルは、Geospatial.state を使用して Geospatial の状態をモニタリングする方法を示しています。

Compose XR

val geospatial = remember { Geospatial.getInstance(session) }
val geospatialState by geospatial.state.collectAsStateWithLifecycle()
if (geospatialState.geospatialTrackingState == Geospatial.GeospatialTrackingState.RUNNING) {
    // Queries to the Geospatial API are only valid when the state is RUNNING.
}
Setup.kt

SceneCore

val geospatial = Geospatial.getInstance(session)
lifecycleScope.launch {
    geospatial.state.collect { geospatialState ->
        if (geospatialState == Geospatial.GeospatialTrackingState.RUNNING) {
            // Queries to the Geospatial API are only valid when the state is RUNNING.
        }
    }
}
Setup.kt

注: GeospatialTrackingState オブジェクトが GeospatialTrackingState.RUNNING にならない場合は、トラブルシューティング ガイドで考えられる解決策をご覧ください。

精度値を理解する

Geospatial API が有効になっている間、水平精度、垂直精度、向きの精度の 3 つの精度値が提供されます。これらの精度値は時間の経過とともに更新され、より多くのデータが取得されるにつれて精度が向上します。値が大きいほど精度が低くなり、68% の信頼度の半径として定義されます。つまり、真の値が推定値の指定された半径内にある確率は 68% です。

Geospatial.State.horizontalAccuracy、verticalAccuracy、orientationYawAccuracy を使用して、現在の精度値を取得します。

アプリが正常に機能するために、特定のレベルの精度が必要になる場合があります。たとえば、アプリは、水平精度が 5 メートル未満になるまで待ってから、仮想コンテンツをレンダリングすることがあります。より精度の高いデータを取得できるようにするには、アプリでユーザーに周囲を見回すよう指示する必要があります。できれば、Google ストリートビューに表示されている建物や、視覚的に詳細な特徴を持つその他の場所を見回すように指示します。Geospatial.checkVpsAvailability を使用して、指定された場所で VPS が利用可能かどうかを判断します。

次のステップ

Geospatial API がアプリで正しく設定されている場合、アプリは次のことができます。

• デバイスローカルのポーズと Geospatial のポーズを相互に変換する
• Geospatial ポーズでコンテンツをレンダリングする