Menyiapkan Geospatial API di aplikasi Anda

Perangkat XR yang kompatibel
Panduan ini membantu Anda membangun pengalaman untuk jenis perangkat XR ini.
Mempelajari jenis perangkat XR →
Kacamata XR Berkabel
Kacamata Pintar dengan Layar
& Audio
Mempelajari jenis perangkat XR →

Untuk menggunakan Geospatial API di aplikasi, aplikasi Anda harus disiapkan untuk mengakses ARCore API di Google Cloud. API ini berisi Layanan Pemosisian Visual yang memberikan pemosisian akurat menggunakan data dari Google Street View.

Panduan ini membantu Anda menyiapkan project Google Cloud yang telah mengaktifkan API dan metode otorisasi yang benar untuk mengakses API.

Menyiapkan project Google Cloud atau menggunakan project yang ada

Jika Anda sudah memiliki project Google Cloud, pilih project tersebut.

Buka pemilih project

Jika belum memiliki project, buatlah project.

Buat project baru

Mengaktifkan ARCore API

Untuk menggunakan ARCore API, Anda harus mengaktifkannya di project Anda.

Mengaktifkan ARCore API

Menyiapkan otorisasi untuk Google Cloud

Aplikasi Android dapat berkomunikasi dengan ARCore API menggunakan dua metode otorisasi yang berbeda: Otorisasi tanpa kunci (OAuth 2.0), yang merupakan metode yang direkomendasikan, dan otorisasi Kunci API:

  • Otorisasi tanpa kunci menggunakan kombinasi nama paket aplikasi dan sidik jari kunci penandatanganan untuk mengizinkan aplikasi Anda.

  • Kunci API adalah string yang mengidentifikasi project Google Cloud. Kunci API umumnya tidak dianggap aman karena biasanya dapat diakses oleh klien. Pertimbangkan untuk menggunakan otorisasi Tanpa Kunci untuk berkomunikasi dengan ARCore API.

Otorisasi tanpa kunci

Untuk mengizinkan aplikasi Anda menggunakan Autentikasi tanpa kunci, buat client ID OAuth 2.0.

  1. Di Google Cloud, buka halaman Credentials.

    Buka Kredensial

  2. Klik Create credentials, lalu pilih OAuth client ID dari menu.

  3. Isi kolom wajib diisi sebagai berikut:

    • Application type: pilih Android.
    • Nama paket: gunakan nama paket seperti yang dideklarasikan di AndroidManifest.xml.
    • Sidik jari sertifikat SHA-1: dapatkan sidik jari sertifikat SHA-1 menggunakan petunjuk di Autentikasi klien.

  4. Tekan Buat.

Kunci API

Buat kunci API dari Konsol Google Cloud dengan mengikuti langkah-langkah berikut:

  1. Di konsol Google Cloud, buka halaman Credentials.

    Buka Kredensial

  2. Klik Create credentials, lalu pilih kunci API dari menu.

  3. Tambahkan Pembatasan API untuk ARCore API. Untuk informasi selengkapnya, lihat Menerapkan pembatasan kunci API.

  4. Klik Buat. Dialog API key created akan menampilkan string untuk kunci yang baru dibuat.

Di Android Studio, tambahkan kunci API baru ke project Anda. Sertakan kunci API dalam elemen <meta-data> di elemen <application> dalam AndroidManifest.xml aplikasi Anda:

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

Meminta izin yang diperlukan

Untuk menggunakan Geospatial API di ARCore dengan Jetpack XR, aplikasi Anda perlu meminta izin runtime berikut:

Di perangkat seluler, Geospatial API juga memerlukan izin berikut:

Mengakses sesi

Akses informasi Geospasial melalui Session Jetpack XR Runtime, yang harus dibuat oleh aplikasi Anda.

Mengonfigurasi sesi

Geospatial API tidak diaktifkan secara default di sesi XR. Aplikasi Anda harus mengaktifkannya secara eksplisit dengan mengonfigurasi GeospatialMode di Session. Mode berikut tersedia:

  • GeospatialMode.SPATIAL: Geospatial API diaktifkan. Geospatial API menggunakan data Sistem Pemosisi Visual (VPS), Sistem Pemosisi Global (GPS), dan sensor gerakan perangkat untuk menentukan pose geospasial perangkat. Mode ini tidak tersedia di perangkat kacamata AI.
  • GeospatialMode.INERTIAL: Geospatial API diaktifkan dalam mode hemat daya. Geospatial API hanya menggunakan GPS dan sensor gerakan perangkat untuk menentukan pose geospasial perangkat. Mode ini hanya tersedia di perangkat kacamata AI.
  • GeospatialMode.DISABLED: Geospatial API dinonaktifkan; saat beralih dari mode lain ke mode ini, Geospatial API akan merilis semua resource yang diperoleh dan berhenti melacak.

Tidak semua perangkat mendukung semua mode Geospasial. Lihat GeospatialMode untuk mengetahui informasi selengkapnya. Gunakan XrDevice.isGeospatialSupported untuk mengetahui apakah GeospatialMode tertentu didukung.

Contoh kode berikut menunjukkan cara menetapkan GeospatialMode menggunakan Session.configure.

// 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.
}

Meminta pengguna untuk mengizinkan penggunaan data perangkat

Aplikasi yang menggunakan Geospatial API dengan ARCore untuk Jetpack XR harus menampilkan perintah kepada pengguna untuk mengonfirmasi dan mengizinkan penggunaan data dari perangkat mereka. Lihat persyaratan privasi pengguna untuk mengetahui informasi selengkapnya.

Menggunakan objek Geospasial

Setelah sesi dikonfigurasi, dapatkan objek Geospatial menggunakan Geospatial.getInstance. Hanya gunakan objek Geospatial saat statusnya GeospatialTrackingState.RUNNING.

Contoh kode berikut menunjukkan cara memantau status Geospasial menggunakan Geospatial.state.

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

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

Memahami nilai akurasi

Saat diaktifkan, Geospatial API memberikan tiga nilai akurasi: akurasi horizontal, vertikal, dan orientasi. Nilai akurasi ini diperbarui dari waktu ke waktu dan dapat dibuat lebih akurat seiring dengan diperolehnya lebih banyak data. Nilai yang lebih besar menunjukkan akurasi yang lebih rendah, dan didefinisikan sebagai radius tingkat keyakinan 68%. Dengan kata lain, ada probabilitas 68% bahwa nilai sebenarnya berada dalam radius yang diberikan dari nilai estimasi.

Gunakan Geospatial.State.horizontalAccuracy, verticalAccuracy, dan orientationYawAccuracy untuk mendapatkan nilai akurasi saat ini.

Aplikasi Anda mungkin memerlukan tingkat presisi tertentu agar dapat berfungsi dengan benar. Misalnya, aplikasi Anda mungkin ingin menunggu hingga akurasi horizontal kurang dari 5 meter sebelum merender konten virtual. Untuk meningkatkan kemungkinan mendapatkan data akurasi yang lebih tinggi, aplikasi Anda harus menginstruksikan pengguna untuk melihat sekeliling, sebaiknya ke bangunan atau fitur lain dengan detail visual tinggi yang ada di Google Street View. Gunakan Geospatial.checkVpsAvailability untuk menentukan apakah VPS tersedia di lokasi tertentu.

Langkah berikutnya

Jika Geospatial API disiapkan dengan benar di aplikasi, aplikasi Anda dapat melakukan hal berikut: