Migrasi Google Fit ke Health Connect di Capacitor

Migrasi Google Fit ke Health Connect berarti mengganti setiap panggilan API Fit di aplikasi Capacitor Anda dengan Health Connect di Android, dan dengan HealthKit di iOS jika Anda juga merilis di sana. Google menghentikan pendaftaran baru Google Fit pada 1 Mei 2024, dan hanya mendukung API Fit sampai akhir 2026. Panduan ini memetakan tipe data dan panggilan Fit ke Health Connect, menunjukkan penggantian code dengan @capgo/capacitor-health, serta membahas review Play Console yang menyertai izin kesehatan.

Timeline penghentian Google Fit

FAQ migrasi Google menyatakan tidak ada alternatif untuk Fit REST API dengan struktur yang sama: aplikasi on-device beralih ke Health Connect, dan integrasi cloud beralih ke Google Health API berbasis akun. Jika Anda melihat tanggal penghentian spesifik disebutkan di suatu tempat, cocokkan dengan FAQ Google sendiri sebelum merencanakan berdasarkan itu.

Apa yang berubah saat pindah ke Health Connect

Perubahan produk terbesar adalah model berbasis perangkat. Data Health Connect di satu ponsel tidak terlihat di ponsel lain. Jika aplikasi Anda menampilkan riwayat lintas perangkat, sinkronkan data pembacaan ke backend Anda sendiri.

Mapping tipe data Fit ke Health Connect

Tipe Fit tanpa padanan langsung

• Poin Jantung (com.google.heart_minutes) dan Pindahkan Menit (com.google.active_minutes) adalah skor Google Fit. Health Connect menyimpan data mentah, bukan skor ini. Hitung ulang metrik Anda sendiri dari detak jantung dan sesi latihan.
• Sampel aktivitas dengan tipe aktivitas per detik digantikan oleh sesi latihan dengan segmen.
• Sampel lokasi di dalam workout menjadi ExerciseRoute data di Health Connect, yang membutuhkan izin terpisah dan tidak diekspos oleh plugin.
• Cadence, kecepatan, dan daya ada di Health Connect (StepsCadenceRecord, SpeedRecord, PowerRecord) tetapi tidak tercakup oleh tipe plugin. Jika Anda bergantung pada data tersebut, metode native kustom kecil adalah jalur tercepat.

Audit sebelum menulis code: daftar setiap DataType dan setiap API yang Anda panggil (History, Recording, Sessions, Sensors, Config, REST), lalu tandai masing-masing sebagai mapped, recomputed, atau dropped.

Langkah 1: Hapus Google Fit

Hapus integrasi Fit dari proyek Android dan JavaScript Anda:

• Hapus com.google.android.gms:play-services-fitness dan, jika hanya dipakai untuk Fit, play-services-auth dari build.gradle.
• Hapus OAuth client Fit dari Google Cloud dan fitness scope dari consent screen Anda.
• Uninstall plugin Capacitor Google Fit komunitas lama yang Anda pakai, lalu jalankan bunx cap sync.

Simpan code Fit di branch sampai versi baru live, supaya Anda bisa export data historis kalau ada user yang minta.

Langkah 2: Install plugin health

bun add @capgo/capacitor-health
bunx cap sync

@capgo/capacitor-health mendukung Capacitor 8, menggunakan Health Connect di Android dan HealthKit di iOS, serta memerlukan Android minSdk 26.

Setup Android

Plugin ini menggabungkan izin baca dan tulis Health Connect untuk tipe yang didukung ke dalam manifest Anda, plus <queries> entri untuk paket Health Connect dan activity rationale izinnya. Anda perlu:

1. Sediakan kebijakan privasi. Health Connect membukanya dari lembar izin. Tambahkan android/app/src/main/assets/public/privacypolicy.html, atau atur URL di android/app/src/main/res/values/strings.xml:

<string name="health_connect_privacy_policy_url">https://example.com/privacy</string>

2. Pangkas izin. Google Play meninjau setiap izin Health Connect yang Anda deklarasikan. Jika Anda hanya membaca langkah dan detak jantung, hapus sisanya dengan tools:node="remove":

<uses-permission
    android:name="android.permission.health.WRITE_BLOOD_GLUCOSE"
    tools:node="remove" />

3. Tambahkan akses riwayat jika Anda membutuhkannya. Health Connect membatasi pembacaan pada sekitar 30 hari terakhir kecuali pengguna memberikan READ_HEALTH_DATA_HISTORY:

<uses-permission android:name="android.permission.health.READ_HEALTH_DATA_HISTORY" />

Setup iOS

Aktifkan capability HealthKit di Xcode dan tambahkan usage strings ke Info.plist:

<key>NSHealthShareUsageDescription</key>
<string>Show your steps and workouts in the app.</string>
<key>NSHealthUpdateUsageDescription</key>
<string>Save the workouts you record in the app.</string>

Langkah 3: Cek ketersediaan

Google Fit berfungsi di mana pun Play services tersedia. Health Connect mungkin tidak ada di Android 13 atau lebih lama, atau memerlukan pembaruan.

import { Health } from '@capgo/capacitor-health';

export async function ensureHealthAvailable() {
  const result = await Health.isAvailable();
  if (result.available) return true;

  // On Android, send the user to install or update Health Connect
  if (result.platform === 'android') {
    await Health.openHealthConnectSettings();
  }
  console.warn('Health store unavailable:', result.reason);
  return false;
}

Tampilkan layar penjelasan singkat sebelum mengalihkan. Pengguna yang belum pernah mendengar Health Connect akan bingung ketika Play Store terbuka tanpa peringatan.

Langkah 4: Ganti OAuth dengan permission

Alur Fit sebelumnya: Google Sign-In, minta scope kebugaran, lalu panggil API. Alur barunya adalah satu sheet izin:

const status = await Health.requestAuthorization({
  read: ['steps', 'distance', 'calories', 'heartRate', 'sleep', 'workouts'],
  write: ['weight'],
  requestHistoryAccess: true, // Android only
});

if (status.readDenied.length > 0) {
  // explain what will not work and offer openHealthConnectSettings()
}
if (status.historyAccessAvailable === false) {
  // provider too old: only the last 30 days are readable
}

Izin diberikan per tipe data dan pengguna bisa mengizinkan subset mana pun. Gunakan checkAuthorization dengan opsi yang sama setiap kali aplikasi dimulai, karena pengguna bisa mencabut akses di pengaturan Health Connect kapan saja. Di iOS, HealthKit menyembunyikan penolakan baca demi privasi, jadi hasil kosong bisa berarti “tidak ada data” atau “tidak ada akses”.

Langkah 5: Ganti pembacaan History API

Fit readData panggilan untuk sampel mentah menjadi readSamples:

const end = new Date();
const start = new Date(end.getTime() - 24 * 60 * 60 * 1000);

const { samples } = await Health.readSamples({
  dataType: 'heartRate',
  startDate: start.toISOString(),
  endDate: end.toISOString(),
  limit: 500,
  ascending: true,
});

for (const s of samples) {
  console.log(s.startDate, s.value, s.unit, s.sourceName, s.deviceType);
}

sourceName dan, di Android, deviceType (watch, phone, chestStrap, dan seterusnya) menggantikan objek sumber data Fit. Gunakan untuk memprioritaskan data jam tangan di atas data ponsel jika keduanya ada.

Langkah 6: Ganti read bucketed dan aggregate

Fit bucketByTime plus aggregate menjadi queryAggregated:

const { samples: daily } = await Health.queryAggregated({
  dataType: 'steps',
  startDate: new Date(Date.now() - 7 * 86_400_000).toISOString(),
  endDate: new Date().toISOString(),
  bucket: 'day',          // 'hour' | 'day' | 'week' | 'month'
  aggregation: 'sum',
});

const { samples: hr } = await Health.queryAggregated({
  dataType: 'heartRate',
  bucket: 'hour',
  aggregation: ['min', 'average', 'max'],
  startDate: new Date(Date.now() - 86_400_000).toISOString(),
  endDate: new Date().toISOString(),
});
// hr[i].values.min, hr[i].values.average, hr[i].values.max

Selalu agregasikan langkah alih-alih menjumlahkan sampel mentah. Health Connect melakukan deduplikasi data yang tumpang tindih dari beberapa aplikasi saat agregasi, dan penjumlahan mentah sering terhitung ganda saat jam tangan dan ponsel sama-sama mencatat langkah.

Langkah 7: Ganti Sessions API

Sesi Fit dipetakan ke sesi latihan:

const { workouts, anchor } = await Health.queryWorkouts({
  workoutType: 'running',
  startDate: new Date(Date.now() - 30 * 86_400_000).toISOString(),
  endDate: new Date().toISOString(),
  limit: 50,
});

for (const w of workouts) {
  console.log(w.workoutType, w.duration, w.totalDistance, w.totalEnergyBurned);
}
// pass `anchor` back to fetch the next page

Permintaan workouts di read izin terlebih dahulu. Plugin ini membaca workout tetapi tidak menulis sesi latihan, jadi jika aplikasi Anda mencatat workout, tulis sampel dasarnya (jarak, kalori, detak jantung) dan simpan sesinya di backend Anda, atau tambahkan metode native untuk ExerciseSessionRecord.

Langkah 8: Ganti inserts

Fit’s insertData menjadi saveSample:

await Health.saveSample({
  dataType: 'weight',
  value: 72.4, // kilograms
  startDate: new Date().toISOString(),
});

await Health.saveSample({
  dataType: 'bloodPressure',
  value: 120,
  systolic: 120,
  diastolic: 80,
  startDate: new Date().toISOString(),
});

Values harus menggunakan unit default dari setiap tipe (kilogram, meter, kilokalori, bpm). metadata option diabaikan oleh Health Connect.

Langkah 9: Lolos review Google Play

Izin kesehatan memicu review tambahan:

1. Di Play Console, buka Konten aplikasi dan lengkapi Aplikasi kesehatan deklarasi dan formulir izin Health Connect. Jelaskan alasan setiap izin yang Anda minta.
2. Pastikan kebijakan privasi yang ditautkan di Play Console dan yang ditampilkan di sheet Health Connect menjelaskan penggunaan data kesehatan.
3. Perbarui Keamanan data form: data kesehatan dan kebugaran, dikumpulkan atau tidak, dibagikan atau tidak.
4. Kirim build yang hanya mendeklarasikan izin yang Anda justifikasi. Izin tambahan yang dideklarasikan adalah penyebab penolakan paling umum.

Siapkan diri jika proses review memakan waktu lebih lama dari update biasa. Rilis migrasi ini secara terpisah, jangan dicampur dengan fitur lain.

Langkah 10: Sesuaikan ekspektasi pengguna

• Beri tahu pengguna bahwa riwayat mereka kini berasal dari Health Connect, dan data lama mungkin dibatasi 30 hari sampai mereka memberikan akses riwayat.
• Jika aplikasi Anda menggunakan Fit untuk sinkronisasi cloud, pindahkan tanggung jawab tersebut ke backend Anda sekarang.
• Hapus tombol “Connect Google Fit” dan ganti namanya menjadi “Connect Health Connect” di Android serta “Connect Apple Health” di iOS.

Pemecahan Masalah

isAvailable() mengembalikan false pada Android 13: Health Connect belum terinstal atau versinya lama. Panggil openHealthConnectSettings().

Sheet izin tidak pernah muncul: izin tidak dideklarasikan dalam merged manifest, atau telah dihapus dengan tools:node="remove". Periksa android/app/build/intermediates/merged_manifests.

Pembacaan hanya mengembalikan 30 hari: minta requestHistoryAccess: true dan deklarasikan READ_HEALTH_DATA_HISTORY.

Total langkah lebih tinggi dari Google Fit: Anda menjumlahkan raw samples. Gunakan queryAggregated.

Hasil kosong di iOS: tidak ada data atau izin baca ditolak. HealthKit tidak memberi tahu yang mana.

Play Console menolak update: hapus izin Health Connect yang tidak dideklarasikan atau tidak perlu, lalu kirim ulang dengan alasan yang jelas.

Luncurkan migrasi secara bertahap

Bagian native (plugin, manifest, capability HealthKit) perlu rilis ke store. Setelah itu, query, UI, dan pemetaan data menggunakan JavaScript, yang bisa Anda iterasi dengan Live updates Capgo sementara pengguna menguji flow baru. Jika Anda juga membaca data sensor secara real-time, lihat panduan kami untuk membangun monitor detak jantung dengan Capacitor, dan dokumentasi plugin health untuk setiap tipe data.