Menggunakan ARCore API di Google Cloud

Pilih platform:

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

Panduan memulai ini menjelaskan cara menyiapkan aplikasi Anda 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 memiliki project yang sudah ada, pilih project tersebut.

Buka pemilih project

Jika Anda belum memiliki project Google Cloud, buat project.

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 metode otorisasi yang berbeda: Otorisasi tanpa kunci, yang merupakan metode yang direkomendasikan, dan otorisasi Kunci API:

  • Di Android, otorisasi Tanpa kunci menggunakan kombinasi nama paket aplikasi dan sidik jari kunci penandatanganan untuk mengotorisasi aplikasi Anda.

    Di iOS, otorisasi Tanpa kunci menggunakan token yang ditandatangani untuk mengontrol akses ke API. Metode ini memerlukan server milik Anda untuk menandatangani token dan mengontrol akses ke API.

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

Tanpa Kunci

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

Menentukan sidik jari kunci penandatanganan

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

.

Cara mendapatkan sidik jari penandatanganan debug Anda

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

Gunakan perintah berikut untuk mendapatkan sidik jari sertifikat debug.

Mac/Linux
keytool -list -v -alias androiddebugkey -keystore ~/.android/debug.keystore
Windows
keytool -list -v -alias androiddebugkey -keystore %USERPROFILE%\.android\debug.keystore

Utilitas keytool akan meminta Anda memasukkan sandi untuk keystore. Sandi default untuk keystore debug adalah android. Utilitas keytool kemudian 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

Utilitas keytool kemudian 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 akan mengelola kunci penandatanganan aplikasi Anda 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 ID klien OAuth 2.0 di kredensial project Google Cloud Anda.

  • Di Google Cloud, buka halaman Credentials.

    Kredensial

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

  • Isi kolom yang wajib diisi sebagai berikut:

    • Application type: pilih Android.
    • Nama paket: gunakan nama paket seperti yang dideklarasikan di AndroidManifest.xml Anda.
    • SHA-1 certificate fingerprint: gunakan sidik jari yang diperoleh pada langkah-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 penyusutan kode, tambahkan ke file build.gradle aplikasi Anda:

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

  3. Tambahkan hal 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 dikonfigurasi untuk menggunakan autentikasi Tanpa kunci.

Tanpa Kunci

ARCore mendukung otorisasi panggilan API di iOS menggunakan (token Web JSON). Token harus ditandatangani oleh akun Layanan Google.

Untuk membuat token bagi iOS, Anda harus memiliki endpoint di server yang memenuhi persyaratan berikut:

  • Mekanisme otorisasi Anda sendiri harus melindungi endpoint.

  • Endpoint harus membuat token baru setiap kali, sehingga:

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

Membuat kunci penandatanganan dan akun layanan

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

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

  8. Pilih JSON sebagai jenis kunci dan klik Create.

    Tindakan ini akan mendownload file JSON yang berisi kunci pribadi ke komputer Anda. Simpan file kunci JSON yang didownload di lokasi yang aman.

Membuat token di server Anda

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

Membuat token di mesin pengembangan Anda

Untuk membuat JWT di mesin pengembangan, gunakan perintah oauth2l berikut:

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

Menentukan lokasi cache kosong menggunakan tanda --cache diperlukan untuk memastikan token yang berbeda dihasilkan setiap kali. Pastikan untuk memangkas string yang dihasilkan. Spasi tambahan atau karakter baris baru akan menyebabkan API menolak token.

Menandatangani token

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

  • iss — Alamat email akun layanan.
  • sub — Alamat email akun layanan.
  • iat — Waktu epoch Unix saat token dibuat, dalam detik.
  • exp — iat + 3600 (1 jam). Waktu epoch Unix saat masa berlaku token berakhir, dalam detik.
  • aud — Audiens. Harus disetel 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 yang berbeda untuk membuat JWT, seperti menggunakan Google API di lingkungan yang dikelola Google, pastikan untuk menandatangani JWT Anda dengan klaim di bagian ini. Yang terpenting, pastikan audiensnya sudah benar.

Teruskan token dalam sesi ARCore

  1. Pastikan iOS Authentication Strategy disetel ke AuthenticationToken. Di Unity, buka Edit > Project Settings > XR Plug-in Management > ARCore Extensions. Di menu drop-down iOS Authentication Strategy, pilih opsi Authentication Token.

  2. Saat Anda mendapatkan token, teruskan token tersebut ke sesi ARCore Anda 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 dikonfigurasi untuk menggunakan autentikasi Tanpa kunci.

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 Konsol Google Developer dan hapus dari aplikasi Anda.

  • ARCore mengabaikan token yang berisi spasi atau karakter khusus.

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

Kunci API

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

  3. Di Unity, buka Edit > Project Settings > XR Plug-in Management > ARCore Extensions. Untuk setiap platform target (Android, iOS), di menu drop-down Authentication Strategy, pilih opsi API Key. Kemudian, masukkan kunci API Anda di kolom kunci API.

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

Aplikasi Anda kini dikonfigurasi untuk menggunakan kunci API.

Langkah berikutnya

Setelah otorisasi dikonfigurasi, lihat fitur ARCore berikut yang menggunakannya: