Menggunakan ARCore API di Google Cloud

Pilih platform: Android Unity (AR Foundation) iOS

Fitur ARCore seperti fitur Geospatial API dan Cloud Anchor menggunakan ARCore API yang dihosting di Google Cloud. Saat menggunakan fitur-fitur ini, aplikasi Anda menggunakan kredensial untuk mengakses layanan ARCore API.

Panduan memulai ini menjelaskan cara menyiapkan aplikasi agar dapat berkomunikasi dengan layanan ARCore API yang dihosting di Google Cloud.

Buat project Google Cloud baru atau gunakan project yang sudah ada

Jika Anda sudah memiliki project, pilih project tersebut.

Buka pemilih project

Jika Anda belum memiliki project Google Cloud, Anda bisa membuatnya.

Buat project baru

Mengaktifkan ARCore API

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

Mengaktifkan ARCore API

Menyiapkan metode otorisasi

Aplikasi Unity dapat berkomunikasi dengan ARCore API menggunakan dua jenis metode otorisasi: Otorisasi tanpa kunci, yang merupakan metode yang direkomendasikan, dan otorisasi Kunci API:

• Di Android, otorisasi Keyless menggunakan kombinasi nama paket aplikasi dan sidik jari kunci penandatanganan untuk memberi otorisasi pada aplikasi Anda.

  Di iOS, otorisasi Keyless menggunakan token yang ditandatangani untuk mengontrol akses ke API. Ini mengharuskan server milik Anda untuk menandatangani token dan mengontrol akses ke API.

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

Tanpa kunciTanpa kunciKunci API

Untuk memberi otorisasi aplikasi menggunakan Autentikasi tanpa kunci, buat klien OAuth 2.0 pelanggan.

Menentukan sidik jari kunci penandatanganan

Client ID OAuth 2.0 menggunakan sidik jari kunci penandatanganan aplikasi untuk mengidentifikasi .

Penting: Anda biasanya menandatangani aplikasi dengan kunci penandatanganan yang berbeda. Anda harus membuat Client ID untuk setiap kunci penandatanganan yang akan digunakan. Umumnya, ini adalah penandatanganan debug kunci dan kunci penandatanganan rilis.

Cara mendapatkan sidik jari penandatanganan debug

Saat menjalankan atau men-debug project Anda, fitur Android SDK akan otomatis menandatangani aplikasi Anda dengan sertifikat debug yang dihasilkan.

Gunakan perintah berikut untuk mendapatkan sidik jari sertifikat debug.

Mac/LinuxWindows

keytool -list -v -alias androiddebugkey -keystore ~/.android/debug.keystore

keytool -list -v -alias androiddebugkey -keystore %USERPROFILE%\.android\debug.keystore

Utilitas keytool akan meminta Anda memasukkan sandi untuk keystore. Tujuan sandi default untuk keystore debug adalah android. Kemudian, utilitas keytool mencetak sidik jari ke terminal. Contoh:

   Certificate fingerprint: SHA1: <strong>DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09

Cara mendapatkan sidik jari penandatanganan dari keystore

Jika Anda memiliki file keystore, gunakan utilitas keytool untuk menentukan sidik jari.

keytool -list -v -alias your-key-name -keystore path-to-production-keystore

Kemudian, utilitas keytool mencetak sidik jari ke terminal. Contoh:

   Certificate fingerprint: SHA1: DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09

Cara mendapatkan kunci penandatanganan aplikasi dari Penandatanganan Aplikasi Play

Saat menggunakan Penandatanganan Aplikasi Play, Google mengelola kunci penandatanganan aplikasi dan menggunakannya untuk menandatangani APK Anda. Kunci ini harus digunakan untuk sidik jari penandatanganan.

1. Di halaman Penandatanganan Aplikasi di Konsol Google Play, scroll ke Sertifikat kunci penandatanganan aplikasi.
2. Gunakan sidik jari sertifikat SHA-1.

Membuat client ID OAuth 2.0

Untuk setiap kunci penandatanganan yang berlaku dari langkah sebelumnya, buat client ID OAuth 2.0 di Kredensial project Google Cloud.

• Di Google Cloud, buka halaman Credentials.

  Kredensial

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

• Isi kolom wajib diisi sebagai berikut:

  • Jenis aplikasi: pilih Android.
  • Nama paket: gunakan nama paket seperti yang dinyatakan di AndroidManifest.xml.
  • Sidik jari sertifikat SHA-1: menggunakan sidik jari yang diperoleh di langkah sebelumnya.

• Tekan Buat.

Menyertakan library yang diperlukan

1. Sertakan com.google.android.gms:play-services-auth:16+ dalam dependensi aplikasi Anda.

2. Jika Anda menggunakan minifikasi kode, menambahkannya ke file build.gradle aplikasi Anda:

   buildTypes {
     release {
       ...
       proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
     }
   }
   

3. Tambahkan kode berikut ke file proguard-rules.pro aplikasi Anda:

   -keep class com.google.android.gms.common.** { *; }
   -keep class com.google.android.gms.location.** { *; }
   -keep class com.google.android.gms.auth.** { *; }
   -keep class com.google.android.gms.tasks.** { *; }
   

Aplikasi Anda kini telah dikonfigurasi untuk menggunakan autentikasi Keyless.

ARCore mendukung otorisasi panggilan API di iOS menggunakan (JSON Web token). Token harus ditandatangani oleh Akun layanan.

Agar dapat membuat token untuk iOS, Anda harus memiliki endpoint di server yang memenuhi persyaratan berikut:

• Mekanisme otorisasi Anda sendiri harus melindungi endpoint.

• Endpoint harus selalu membuat token baru, sehingga:

  • Setiap pengguna mendapatkan token unik.
  • Masa berlaku token tidak langsung berakhir.

Membuat akun layanan dan kunci penandatanganan

Ikuti langkah-langkah berikut untuk membuat akun layanan Google dan kunci penandatanganan:

1. Di Google Cloud, buka halaman Credentials.
   Kredensial
2. Klik Create Credentials > Akun layanan.
3. Di bagian Detail akun layanan, ketik nama untuk akun baru, lalu klik Buat.
4. Di halaman izin Akun layanan, buka drop-down Pilih peran. Pilih Service Accounts > Service Account Token Creator, lalu klik Lanjutkan.
5. Di halaman Beri pengguna akses ke akun layanan ini, klik Selesai.
6. Di bagian Credentials temukan bagian Akun Layanan dan klik nama akun yang baru saja Anda buat.
7. Di halaman Service account details, scroll ke bawah ke bagian Keys dan pilih Add Key > Buat kunci baru.

8. Pilih JSON sebagai jenis kunci dan klik Create.

   Tindakan ini akan mendownload file JSON yang berisi kunci pribadi ke mesin Anda. Menyimpan file kunci JSON yang diunduh di lokasi yang aman.

   Catatan: File ini berisi kunci pribadi yang tidak boleh diekspos publik. Jangan meng-commit ke repositori kode sumber seperti GitHub.

Membuat token di server

Untuk membuat token baru (JWT) di server Anda, gunakan JWT standar library dan file JSON yang didownload dengan aman dari akun layanan baru Anda.

Membuat token di mesin pengembangan

Untuk menghasilkan JWT di mesin pengembangan Anda, gunakan perintah berikut Perintah oauth2l:

oauth2l fetch --cache "" --jwt --json $KEYFILE --audience "https://arcore.googleapis.com/"

Menentukan lokasi cache kosong menggunakan tanda --cache diperlukan untuk memastikan bahwa token yang berbeda dibuat setiap kalinya. Pastikan untuk memangkas {i>string<i} yang dihasilkan. Spasi ekstra atau karakter baris baru akan menyebabkan API menolak token.

Tanda tangani token

Anda harus menggunakan algoritma RS256 dan klaim berikut untuk menandatangani JWT:

• iss — Alamat email akun layanan.
• sub — Alamat email akun layanan.
• iat — Waktu Unix epoch saat token dibuat, dalam detik.
• exp — iat + 3600 (1 jam). Waktu Unix {i>epoch<i} ketika token kedaluwarsa, dalam hitungan detik.
• aud — Audiens. Harus ditetapkan ke https://arcore.googleapis.com/.

Klaim non-standar tidak diperlukan dalam payload JWT, meskipun Anda mungkin menemukan Klaim uid berguna untuk mengidentifikasi pengguna yang sesuai.

Jika Anda menggunakan pendekatan lain untuk menghasilkan JWT, seperti menggunakan ID API di lingkungan yang dikelola Google, pastikan Anda menandatangani JWT dengan klaim pada bagian ini. Yang terpenting, pastikan audiensnya benar.

Teruskan token dalam sesi ARCore

1. Pastikan Strategi Autentikasi iOS ditetapkan ke AuthenticationToken. Di Unity, buka Edit > Setelan Project > Pengelolaan Plugin XR > Ekstensi ARCore. Di drop-down iOS Authentication Strategy pada menu, pilih opsi Authentication Token.

2. Setelah mendapatkan token, teruskan token tersebut ke sesi ARCore menggunakan ARAnchorManager.SetAuthToken():

   // Designate the token to authorize ARCore API calls
   // on the iOS platform. This should be called each time the application's token is refreshed.
   ARAnchorManager.SetAuthToken(authToken);
   

Aplikasi Anda kini telah dikonfigurasi untuk menggunakan autentikasi Keyless.

Perhatikan hal-hal berikut saat Anda meneruskan token ke sesi:

• Jika Anda telah menggunakan kunci API untuk membuat sesi, ARCore akan mengabaikan token dan mencatat error.

  Jika Anda tidak lagi memerlukan kunci API, hapus di Google Developers Konsol Google Play, lalu hapus dari .

• ARCore mengabaikan token yang berisi spasi atau karakter khusus.

• Masa berlaku token biasanya berakhir setelah satu jam. Jika ada kemungkinan bahwa masa berlaku token mungkin habis saat digunakan, dapatkan token baru dan teruskan ke API.

1. Di Google Cloud, buka halaman Credentials.
   Kredensial
2. Klik Create credentials, lalu pilih API key dari menu.
   Dialog pembuatan kunci API menampilkan string untuk kunci yang baru dibuat.

3. Di Unity, buka Edit > Setelan Project > Pengelolaan Plugin XR > Ekstensi ARCore. Untuk setiap platform target (Android, iOS), dengan Menu drop-down Strategi Autentikasi, pilih opsi Kunci API. Lalu: masukkan kunci API Anda di kolom kunci API.

4. Tinjau dokumentasi tentang pembatasan kunci API untuk mengamankan kunci API.

Aplikasi Anda kini dikonfigurasi untuk menggunakan kunci API.

Langkah berikutnya

Dengan otorisasi terkonfigurasi, lihat fitur ARCore berikut yang menggunakan hal tersebut:

• Geospatial API
• Cloud Anchor API