Menyiapkan Google Cloud dan OAuth

Akses ke Google Health API disediakan melalui Google Cloud. Untuk mengaktifkan API dan memberi otorisasi Akun Google, Anda memerlukan project Google Cloud.

Baik Anda adalah developer Fitbit API yang sudah ada, atau baru menggunakan Google Health API, Anda harus menyelesaikan langkah ini untuk melakukan panggilan ke API.

Membuat project dan klien OAuth

Gunakan tombol Aktifkan API dan dapatkan ID Klien OAuth 2.0 untuk mengaktifkan Google Health API dan mendapatkan ID Klien OAuth 2.0:

  1. Jika Anda memiliki project Google Cloud yang sudah ada dan ingin digunakan untuk Google Health API, pastikan Anda login ke akun administrator untuk project tersebut terlebih dahulu. Kemudian, pilih project yang ada dari daftar project yang tersedia setelah mengklik tombol. Jika tidak, buat project baru.
  2. Pilih Web Server saat ditanya "Where are you calling from?".
  3. Masukkan https://www.google.com sebagai nilai untuk URI pengalihan yang diizinkan. URI pengalihan diperlukan untuk mendapatkan Kode Otorisasi menggunakan OAuth 2.0.
  4. Setelah penyiapan selesai, salin nilai Client ID dan Client Secret OAuth 2.0, lalu download JSON Kredensial ke mesin lokal Anda.
Aktifkan API dan dapatkan Client ID OAuth 2.0

Jika Anda ingin menyiapkan project Google Cloud secara manual, atau memverifikasi penyiapan dan mengambil kredensial Anda lagi:

  1. Aktifkan Google Health API di halaman Pengaktifan API.
  2. Dapatkan Client ID OAuth 2.0 di halaman Credentials.

Untuk mengetahui informasi selengkapnya tentang cara menyiapkan OAuth 2.0 menggunakan konsol Google, lihat Menggunakan OAuth 2.0 untuk Mengakses Google API.

Gunakan project terpisah untuk staging dan produksi

Google Health API tidak menyediakan lingkungan sandbox atau penyiapan terpisah. Semua lingkungan Anda memanggil Google Health API produksi, sehingga Anda mengelola pemisahan lingkungan di tingkat project Google Cloud.

Saat menyiapkan lingkungan untuk aplikasi Anda, ikuti praktik terbaik berikut:

  • Buat project Google Cloud terpisah untuk lingkungan pengembangan, staging, dan produksi Anda. Setiap project mengelola klien OAuth 2.0, layar izin, dan pelanggan webhook-nya sendiri.
  • Jangan gunakan project Google Cloud produksi atau klien OAuth 2.0-nya untuk pengujian, karena perubahan pada project tersebut akan langsung memengaruhi aplikasi produksi Anda.
  • Kembangkan dan uji di project non-produksi terlebih dahulu, lalu terapkan perubahan ke project produksi Anda jika sudah siap.
  • Gunakan tag di Konsol Google Cloud untuk membedakan project Anda secara visual menurut lingkungan. Untuk mengetahui petunjuknya, lihat Menetapkan lingkungan project dengan tag.

Menambahkan pengguna pengujian

Secara default, klien OAuth yang baru dibuat berada dalam status belum terverifikasi dengan batas 100 pengguna untuk tujuan pengujian dan produksi. Untuk mengaktifkan otorisasi selama periode ini, Anda harus menambahkan alamat email setiap pengguna secara manual ke daftar Pengguna pengujian dalam konfigurasi project Anda.

Perbarui daftar pengguna pengujian di halaman Audiens:

  1. Di halaman ini, Anda akan melihat "Status publikasi" disetel ke Pengujian, dan "Jenis pengguna" disetel ke Eksternal.
  2. Di bagian "Pengguna pengujian", klik + Tambahkan pengguna. Masukkan alamat email untuk setiap pengguna pengujian yang harus diizinkan untuk memberikan izin aplikasi Anda mengakses data kesehatan mereka.
  3. Klik Simpan.

Untuk mendukung lebih dari 100 pengguna dengan Google Health API, Anda harus menyelesaikan peninjauan keamanan pihak ketiga. Informasi tambahan dapat ditemukan di Pusat Bantuan Verifikasi Aplikasi OAuth.

Menambahkan cakupan

Anda harus menentukan cakupan yang diizinkan untuk dipanggil oleh klien Anda di halaman Akses Data:

  1. Di halaman ini, klik Tambahkan atau hapus cakupan.
  2. Di kolom API, telusuri "Google Health API". Pilih cakupan yang Anda perlukan untuk aplikasi Anda.
  3. Setelah memilih semua cakupan yang Anda butuhkan, klik Perbarui untuk kembali ke halaman Akses Data.
  4. Klik Simpan.

Sebelum memilih cakupan, tinjau penerapan cakupan.

Anda telah selesai menyiapkan client ID dan sekarang dapat melakukan panggilan ke Google Health API.

Mengupdate cakupan

Anda dapat meminta pengguna untuk mengizinkan ulang aplikasi Anda dengan menyetel parameter perintah ke izin dalam permintaan autentikasi Anda. Jika prompt=consent disertakan, layar izin ditampilkan setiap kali aplikasi Anda meminta otorisasi cakupan akses, meskipun semua cakupan sebelumnya diberikan ke project Google API Anda.

Untuk menambahkan atau mengubah cakupan menggunakan parameter prompt=consent, ikuti langkah-langkah berikut:

  1. Identifikasi daftar lengkap Cakupan yang dibutuhkan aplikasi Anda. Hal ini harus mencakup cakupan yang ada dan cakupan baru yang perlu Anda tambahkan.

  2. Ubah parameter cakupan di URL otorisasi untuk menyertakan daftar nilai cakupan yang diperbarui dan dipisahkan dengan spasi.

  3. Tambahkan prompt=consent ke parameter URI autentikasi Anda. Hal ini memaksa server otorisasi untuk meminta izin pengguna sebelum menampilkan informasi ke klien Anda.

    Contoh berikut menunjukkan permintaan GET HTTPS ke endpoint otorisasi OAuth 2.0 Google yang meminta beberapa cakupan dengan prompt=consent ditambahkan:

    https://accounts.google.com/o/oauth2/v2/auth?client_id=client-id&redirect_uri=redirect-uri&response_type=code&access_type=offline&scope=https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly%20https://www.googleapis.com/auth/googlehealth.sleep.readonly&prompt=consent

  4. Saat pengguna mengikuti link yang diperbarui, mereka akan melihat halaman izin yang mencantumkan semua cakupan yang diminta. Setelah pengguna mengklik "Lanjutkan" atau "Izinkan", Anda akan menerima kode otorisasi baru yang dapat ditukarkan dengan token yang mencakup seluruh set cakupan.

    Sertakan prompt=consent hanya jika diperlukan, seperti saat Anda perlu mendapatkan token refresh baru atau saat cakupan yang diminta telah berubah.

Library klien OAuth2

Daftar library klien OAuth2 yang tersedia dan digunakan untuk berintegrasi dengan framework populer dapat ditemukan di Menggunakan OAuth 2.0 untuk Mengakses Google API.

Saat menerapkan Google OAuth di aplikasi seluler atau desktop, selalu gunakan browser sistem (seperti Tab Khusus Chrome di Android atau ASWebAuthenticationSession di iOS) dan jangan pernah menggunakan WebView sematan, yang memblokir kunci sandi dan merusak alur Google OAuth. Tinjau praktik terbaik Login dengan Google untuk mendapatkan panduan.

Sebelum pengguna melalui alur pemberian izin OAuth 2.0 Google di aplikasi Anda, mereka harus login ke aplikasi seluler Google Health untuk menautkan Google Health ke Akun Google mereka. Google OAuth 2.0 mengautentikasi Akun Google yang valid dan tidak dapat memeriksa apakah akun memiliki profil Google Health yang aktif selama layar izin.

Minta pengguna untuk menyelesaikan langkah-langkah berikut di aplikasi seluler Google Health sebelum memulai alur izin OAuth di aplikasi Anda:

  1. Download dan buka aplikasi seluler Google Health dari Google Play Store atau Apple App Store.
  2. Ketuk Login dengan Google, lalu pilih Akun Google yang ingin mereka hubungkan ke aplikasi Anda.
  3. Ikuti perintah dalam aplikasi untuk membuat profil Google Health baru, atau ikuti langkah-langkah migrasi akun Fitbit untuk memindahkan akun Fitbit yang ada ke Akun Google mereka.

Setelah menukar kode otorisasi dengan token OAuth, panggil endpoint users.getIdentity (GET https://health.googleapis.com/v4/users/me/identity) untuk memverifikasi bahwa Akun Google pengguna ditautkan ke Google Health sebelum menandai akun sebagai terhubung di aplikasi Anda. Untuk mengetahui detail tentang cara menangani akun yang tidak ditautkan (400 ACCOUNT_NOT_LINKED), lihat Menangani Akun Google yang tidak ditautkan.

Token refresh

Untuk mempertahankan akses jangka panjang ke Google API tanpa memerlukan autentikasi ulang pengguna yang terus-menerus, aplikasi Anda harus menggunakan token refresh. Untuk detail penerapan yang komprehensif, termasuk permintaan dan parameter HTTP tertentu yang diperlukan, lihat dokumentasi platform identitas Google.

Untuk menukarkan token refresh dengan token akses, lakukan panggilan POST HTTPS ke endpoint token OAuth 2.0 Google. Cuplikan berikut menunjukkan contoh permintaan dan respons:

Permintaan

curl -L -X POST 'https://oauth2.googleapis.com/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'client_id=client-id&client_secret=client-secret&refresh_token=refresh-token&grant_type=refresh_token'

Respons

{
  "access_token": "access-token",
  "expires_in": 3599,
  "scope": "scope-list",
  "token_type": "Bearer",
  "refresh_token": "refresh-token",
  "refresh_token_expires_in": 112154
}

Kapan harus memperbarui token

Memperbarui token akses sesuai permintaan sebagai bagian dari progres alami sesi aktif pengguna saat token akses telah habis masa berlakunya atau akan segera habis masa berlakunya. Hindari memperbarui token dalam batch (misalnya, menggunakan tugas atau layanan cron terjadwal untuk memperbarui token bagi semua pengguna pada waktu yang tetap).

Memperbarui token dalam batch tidak direkomendasikan karena alasan berikut:

  • Penyegaran batch mencegah penyelarasan update token dengan pola sinkronisasi pengguna aktif. Meskipun Anda dapat menggunakan panggilan Get Devices untuk melihat waktu sinkronisasi terakhir pengguna, hal ini memerlukan cakupan OAuth tambahan yang tidak wajib disetujui pengguna.
  • Pemrosesan batch memperbarui token yang tidak perlu di-refresh, sehingga menyebabkan overhead pemrosesan yang berlebihan untuk sistem Anda dan server Google.
  • Jika masalah jaringan atau pemadaman server terjadi selama refresh batch, semua token pengguna yang terpengaruh akan terpengaruh sekaligus. Memperbarui token satu per satu selama progres alami sinkronisasi pengguna mengisolasi dampak kegagalan sementara pada satu pengguna.
  • Mendiagnosis masalah lebih sulit dilakukan dengan tugas batch. Karena permintaan batch lebih jarang terjadi dan menghasilkan banyak entri log sekaligus, akan lebih sulit untuk menentukan titik awal insiden.
  • Lonjakan konkurensi tinggi dalam permintaan token selama batch berjalan meningkatkan kemungkinan tercapainya batas kecepatan atau terjadinya error autentikasi yang terputus-putus.

Perilaku token selama pengujian

Perhatikan perilaku token refresh, bergantung pada status publikasi project Google Cloud Anda:

  • Mode Pengujian: Jika layar izin OAuth Anda dikonfigurasi dengan status publikasi "Pengujian", token refresh yang dikeluarkan berbasis waktu dan akan habis masa berlakunya setelah 7 hari. Selama periode ini, Anda akan menerima satu token refresh yang tetap valid dan dapat digunakan untuk mendapatkan token akses baru hingga mencapai tanggal habis masa berlakunya.
  • Mode Dipublikasikan: Setelah aplikasi Anda dipindahkan ke status "Dalam Produksi", token refresh umumnya tidak akan habis masa berlakunya kecuali jika dicabut atau tidak digunakan dalam jangka waktu yang lama (biasanya enam bulan).

Untuk pengalaman pengguna yang lancar, pastikan Anda memublikasikan aplikasi sebelum dipindahkan ke lingkungan produksi untuk menghindari masa berlaku token 7 hari.

Membuat data sampel

Google tidak menyediakan data kesehatan contoh atau tiruan yang sudah diisi sebelumnya. Untuk menguji integrasi, Anda harus membuat data pengujian sendiri. Gunakan salah satu metode berikut untuk membuat data sampel bagi pengguna pengujian Anda:

  • Memakai pelacak: Pakai pelacak Fitbit, Pixel Watch, atau smartwatch lain yang kompatibel dengan aplikasi Google Health dan berjalan-jalan untuk menghasilkan data langkah, detak jantung, dan latihan fisik.
  • Aktifkan pelacakan seluler: Aktifkan MobileTrack di aplikasi Google Kesehatan dan berjalan-jalanlah dengan perangkat seluler Anda.
  • Mencatat data secara manual: Masukkan metrik kesehatan secara manual (seperti tidur, berat badan, asupan air, atau makanan) melalui aplikasi Google Health.
  • Menulis data menggunakan API: Kirim permintaan penulisan (seperti POST atau PATCH) langsung ke endpoint REST API untuk mengisi data secara terprogram. Untuk mengetahui detail selengkapnya tentang cara membuat dan memperbarui titik data, lihat dokumentasi referensi REST.

Perlindungan Lintas Akun (RISC API)

Aktifkan Berbagi dan Koordinasi Risiko dan Insiden (RISC) jika Anda ingin diberi tahu tentang perubahan pada token acara atau penautan akun, seperti akun yang dibatalkan tautannya atau token yang dicabut, untuk membersihkan token yang disimpan dan memperbarui status koneksi UI. Mengaktifkan RISC API bersifat opsional.

Untuk mengaktifkan RISC API untuk project Google Cloud Anda:

  1. Buka halaman RISC API di konsol Google Cloud. Pastikan project yang Anda gunakan untuk Google Health API dipilih.
  2. Baca Persyaratan RISC dan pastikan Anda memahami persyaratannya.
  3. Klik Aktifkan jika Anda menyetujui persyaratan tersebut.

Setelah mengaktifkan API, Anda harus membuat dan mendaftarkan endpoint HTTPS untuk menerima dan memvalidasi token peristiwa yang dikirim oleh Google.

Untuk mengetahui informasi selengkapnya tentang Perlindungan Lintas Akun dan RISC, lihat Melindungi akun pengguna dengan Perlindungan Lintas Akun.