Fitur ARCore seperti Geospatial API dan Cloud Anchors menggunakan ARCore API yang dihosting di Google Cloud. Saat menggunakan fitur ini, aplikasi Anda akan 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 sudah memiliki project, pilih project tersebut.
Jika Anda belum memiliki project Google Cloud, buat project.
Mengaktifkan ARCore API
Untuk menggunakan ARCore API, Anda harus mengaktifkannya di project Anda.
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 memberikan otorisasi ke 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 client ID OAuth 2.0.
Menentukan sidik jari kunci penandatanganan
Client ID OAuth 2.0 menggunakan sidik jari kunci penandatanganan aplikasi untuk mengidentifikasi aplikasi Anda.
Cara mendapatkan sidik jari penandatanganan debug
Saat menjalankan atau men-debug project, Android SDK Tools akan otomatis menandatangani aplikasi dengan sertifikat debug yang dihasilkan.
Gunakan perintah berikut untuk mendapatkan sidik jari sertifikat debug.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. Sandi
default untuk keystore debug adalah android
. Kemudian, utilitas keytool
akan
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
akan 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 dan menggunakannya untuk menandatangani APK. Kunci ini harus digunakan untuk sidik jari penandatanganan.
- Di halaman Penandatanganan Aplikasi di Konsol Google Play, scroll ke Sertifikat kunci penandatanganan aplikasi.
- 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 Anda.
Di Google Cloud, buka halaman Credentials.
Klik Create credentials, lalu pilih OAuth client ID dari menu.
Isi kolom yang wajib diisi sebagai berikut:
- Jenis aplikasi: pilih Android.
- Nama paket: gunakan nama paket seperti yang dinyatakan dalam AndroidManifest.xml.
- Sidik jari sertifikat SHA-1: gunakan sidik jari yang diperoleh pada langkah sebelumnya.
Tekan Buat.
Menyertakan library yang diperlukan
- Sertakan
com.google.android.gms:play-services-auth:16+
dalam dependensi aplikasi Anda. Jika Anda menggunakan minifikasi kode, tambahkan kode tersebut ke file
build.gradle
aplikasi Anda:buildTypes { release { ... proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro' } }
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 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.
Agar dapat menghasilkan token untuk iOS, Anda harus memiliki endpoint di server yang memenuhi persyaratan berikut:
Mekanisme otorisasi Anda sendiri harus melindungi endpoint.
Endpoint harus membuat token baru setiap saat, 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:
- Di Google Cloud, buka halaman Credentials.
Kredensial - Klik Create Credentials > Service account.
- Di bagian Detail akun layanan, ketik nama untuk akun baru, lalu klik Buat.
- Di halaman izin Akun layanan, buka drop-down Pilih peran. Pilih Service Accounts > Service Account Token Creator, lalu klik Lanjutkan.
- Di halaman Berikan pengguna akses ke akun layanan ini, klik Selesai.
- Pada halaman Credentials, temukan bagian Service Accounts lalu klik nama akun yang baru saja Anda buat.
- Pada halaman Service account details, scroll ke bawah ke bagian Keys, lalu pilih Add Key > Create new key.
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
Untuk membuat token baru (JWT) di server Anda, gunakan library JWT standar dan file JSON yang didownload dengan aman dari akun layanan baru.
Membuat token di mesin pengembangan
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 bahwa token yang berbeda dibuat setiap waktu. Pastikan untuk memangkas
string yang dihasilkan. Spasi tambahan atau karakter baris baru akan menyebabkan API menolak token.
Menandatangani token
Anda harus menggunakan algoritme 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 epoch saat token berakhir, dalam hitungan detik.aud
— Audiens. Nilainya harus ditetapkan kehttps://arcore.googleapis.com/
.
Klaim non-standar tidak diperlukan dalam payload JWT, meskipun Anda mungkin merasa klaim uid
berguna untuk mengidentifikasi pengguna yang sesuai.
Jika Anda menggunakan pendekatan yang berbeda untuk menghasilkan JWT, seperti menggunakan Google API di lingkungan yang dikelola Google, pastikan untuk menandatangani JWT dengan klaim di bagian ini. Yang terpenting, pastikan audiens benar.
Meneruskan token dalam sesi ARCore
- Pastikan Strategi Autentikasi iOS 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.
Setelah 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 kunci API di Konsol Google Developers 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 masa berlaku token Anda habis saat digunakan, dapatkan token baru dan teruskan ke API.
Kunci API
- Di Google Cloud, buka halaman Credentials.
Kredensial - Klik Create credentials, lalu pilih API key dari menu.
Dialog kunci API yang dibuat akan menampilkan string untuk kunci yang baru dibuat. 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. Selanjutnya, masukkan kunci API Anda di kolom kunci API.
- Tinjau dokumentasi tentang pembatasan kunci API untuk mengamankan kunci API Anda.
Aplikasi Anda sekarang dikonfigurasi untuk menggunakan kunci API.
Langkah selanjutnya
Setelah otorisasi dikonfigurasi, lihat fitur ARCore berikut yang menggunakannya: