Mengaktifkan Geospatial API untuk aplikasi Android NDK (C)

Konfigurasikan setelan aplikasi Anda agar dapat menggunakan Geospatial API.

Prasyarat

Pastikan Anda memahami konsep AR dasar dan cara mengonfigurasi sesi ARCore sebelum melanjutkan.

Jika Anda ingin menjalankan aplikasi contoh yang menunjukkan fungsi yang dijelaskan di sini, lihat Panduan Memulai Geospasial ARCore untuk Android untuk Java. Aplikasi contoh di Panduan Memulai ditulis dalam Java. Contoh kode dalam dokumen ini adalah untuk fungsi yang sama dengan yang ditulis dalam C.

Lihat Pengantar Geospatial API untuk mengetahui informasi selengkapnya tentang Geospatial API.

Jika Anda baru mengenal pengembangan dengan ARCore, lihat Memulai untuk mengetahui informasi tentang persyaratan software dan hardware, prasyarat, dan informasi lain khusus untuk platform yang Anda gunakan.

Pastikan lingkungan pengembangan Anda memenuhi persyaratan ARCore SDK, seperti yang dijelaskan dalam Panduan Memulai untuk Java.

Mengaktifkan ARCore API

Sebelum menggunakan Sistem Pemosisi Visual (VPS) di aplikasi, Anda harus mengaktifkan ARCore API terlebih dahulu di project Google Cloud yang baru atau yang sudah ada. Layanan ini bertanggung jawab untuk menghosting, menyimpan, dan menyelesaikan anchor Geospasial.

Otorisasi tanpa kunci lebih diutamakan, tetapi otorisasi Kunci API juga didukung.

Menambahkan library yang diperlukan ke aplikasi

Setelah memberi aplikasi otorisasi untuk memanggil ARCore API, Anda harus menambahkan library untuk mengaktifkan fitur Geospatial di aplikasi.

Di file build.gradle aplikasi Anda, siapkan layanan Google Play untuk menyertakan library Lokasi Layanan 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)'
}

Mengaktifkan kemampuan Geospasial di konfigurasi sesi

Sebelum membuat sesi, ubah GeospatialMode di konfigurasi sesi Anda menjadi ENABLED:

// Create a session config.
ArConfig* ar_config = NULL;
ArConfig_create(ar_session, &ar_config);

// Enable the Geospatial API.
ArConfig_setGeospatialMode(ar_session, ar_config, AR_GEOSPATIAL_MODE_ENABLED);
CHECK(ArSession_configure(ar_session, ar_config) == AR_SUCCESS);

// Release config resources.
ArConfig_destroy(ar_config);

Saat mode Geospasial disetel ke ENABLED, aplikasi diizinkan untuk mendapatkan informasi geografis dari Visual Positioning System (VPS).

Meminta pengguna untuk mengizinkan penggunaan data perangkat

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

Periksa kompatibilitas perangkat

Tidak semua perangkat yang mendukung ARCore juga mendukung Geospatial API, seperti yang dijelaskan dalam quickstart untuk Java.

Untuk memeriksa kompatibilitas perangkat pengguna, panggil ArSession_isGeospatialModeSupported(). Jika nilai ini menampilkan nilai salah (false), jangan mencoba mengonfigurasi sesi (di bawah), karena hal itu akan menyebabkan ArStatus melaporkan AR_ERROR_UNSUPPORTED_CONFIGURATION.

Meminta izin akses lokasi kepada pengguna saat runtime

Aplikasi Anda harus meminta izin akses lokasi saat runtime.

Untuk menggunakan ARCore Geospatial API, aplikasi Anda harus mendaftarkan izin tambahan berikut:

  • ACCESS_FINE_LOCATION untuk menentukan lokasi pengguna secara akurat.

  • ACCESS_COARSE_LOCATION untuk penentuan lokasi pengguna yang tidak akurat dan untuk mematuhi persyaratan privasi pengguna. Namun, Geospatial API tidak dapat dikonfigurasi untuk berfungsi dengan lokasi sementara, dan permintaan API akan gagal jika pengguna telah menetapkan izin ini. Lihat di bawah untuk informasi lebih lanjut.

  • ACCESS_INTERNET untuk menghubungi layanan 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>

Pada perangkat yang menjalankan Android versi 12 atau yang lebih tinggi, pengguna dapat meminta agar aplikasi Anda memiliki akses hanya ke informasi perkiraan lokasi. Untuk mengakomodasi permintaan ini, aplikasi Anda harus mengonfigurasi izin ACCESS_COARSE_LOCATION, beserta ACCESS_FINE_LOCATION, seperti yang ditunjukkan di atas. Anda harus mengonfigurasi kedua izin akses lokasi.

Namun, saat pengguna menentukan lokasi sementara, tindakan tersebut akan mencegah Geospatial API mendapatkan lokasi akurat yang diperlukan. Layanan Geospasial tidak akan mengizinkan konfigurasinya sendiri jika aplikasi Anda hanya memberikan lokasi sementara. Aplikasi Anda tidak dapat menggunakan Geospatial API dengan lokasi sementara.

Memeriksa ketersediaan Geospasial di lokasi perangkat saat ini

Karena Geospatial API menggunakan kombinasi VPS dan GPS untuk menentukan pose Geospasial, API dapat digunakan selama perangkat dapat menentukan lokasinya. Di area dengan akurasi GPS yang rendah, seperti ruang dalam ruangan dan lingkungan perkotaan yang padat, API akan bergantung pada cakupan VPS untuk menghasilkan pose akurasi tinggi. Dalam kondisi umum, VPS dapat diharapkan untuk memberikan akurasi posisi sekitar 5 meter, dan akurasi rotasi 5 derajat. Gunakan ArSession_checkVpsAvailabilityAsync() untuk menentukan apakah lokasi tertentu memiliki cakupan VPS.

Geospatial API juga dapat digunakan di area yang tidak memiliki cakupan VPS. Di lingkungan luar ruangan dengan sedikit atau tanpa penghalang di atas kepala, GPS mungkin cukup untuk menghasilkan pose dengan akurasi tinggi.

Langkah selanjutnya