Taşıma işleminizi veya yeni uygulama geliştirme sürecinizi bugün başlatın. 100'den fazla kullanıcısı olan uygulamalar, 30 Mart'tan itibaren doğrulama için gönderilebilir.

Kullanıcılarınızın sorunsuz bir deneyim yaşamasını sağlamak için, eski Fitbit hesaplarının desteğinin sonlandırılmasıyla uyumlu olacak şekilde entegrasyonunuzu resmi olarak başlatmak üzere Mayıs 2026'nın sonuna kadar beklemenizi öneririz. Geliştiricilerden gelen geri bildirimleri değerlendirirken Mayıs ayının sonuna kadar bazı değişiklikler yapabileceğimizi hatırlatmak isteriz.

Taşıma rehberi

Google Health API, geliştiricilerin Fitbit kullanıcı verilerini sorgulamasına olanak tanıyan, baştan sona yeni bir API'dir. Bu sadece bir güncelleme değil, uygulamalarınızın güvenli, güvenilir ve sağlık teknolojisindeki gelecekteki gelişmelere hazır olmasını sağlayacak stratejik bir adım. API; uygulamalarınızı kaydetmek için yeni bir konsolu, Google OAuth 2.0 desteğini, yeni veri türlerini, yeni uç nokta şemasını ve yeni yanıt biçimini destekler.

Bu kılavuz, geliştiricilerin mevcut Fitbit Web API uygulamalarını yeni Google Health API'ye taşımasına yardımcı olmak için tasarlanmıştır.

Neden taşıma işlemi yapmalısınız?

Google Health API'yi kullanmanın avantajları şunlardır:

Gelişmiş güvenlik: Google'ın en iyi güvenlik uygulamalarına uygunluk, Google'ın güvenlik, gizlilik ve kimlik standartlarına uyum.
Tutarlılık: Daha sezgisel bir geliştirici deneyimi için veri biçimlerindeki, saat dilimlerindeki, ölçü birimlerindeki ve hata işlemeyle ilgili eski tutarsızlıkları ortadan kaldırır.
Ölçeklenebilirlik ve geleceğe hazırlık: Gelecekteki talepleri karşılayacak şekilde ölçeklenmek üzere tasarlanmıştır ve gRPC gibi modern protokolleri destekler.

Uygulama Kaydı

Tüm Google Health API uygulamaları, tüm Google uygulamalarınızı yönetmek için merkezi bir hub görevi gören Google Cloud Console kullanılarak kaydedilmelidir.

Uygulamanızı kaydetme talimatları için Başlangıç bölümündeki adımları uygulayın. Uygulamalarınızı kaydederken fark edeceğiniz farklılıklar aşağıda verilmiştir.

	Fitbit Web API	Google Health API
Herkese açık bağlantılar	https://dev.fitbit.com/apps	https://console.cloud.google.com
Yeni uygulama ekleme	Yeni uygulama kaydet'i tıklayın.	Google Cloud projesi oluşturma Google Health API'yi etkinleştirin.
Temel Bilgiler	Doldurulacak alanlar: Uygulama adı Açıklama Uygulama Web Sitesi URL'si Kurumsal Kuruluşun web sitesi URL'si Hizmet Şartları URL'si Gizlilik Politikası URL'si	Doldurulacak alanlar: Uygulama adı Destek e-posta adresi Kitle (dahili veya harici) İletişim e-postası Logo simgesi Uygulama web sitesi URL'si Gizlilik politikası URL'si Hizmet Şartları URL'si Yetkilendirilmiş alan
Uygulama Türleri	Geliştiricinin seçmesi gerekenler: Sunucu Müşteri Kişisel	Web uygulaması Android Chrome Uzantısı iOS TV'ler Masaüstü uygulaması Evrensel Windows Platformu
Müşteri Kimliği	Uygulama ayarları kaydedildiğinde kaydedilir.	Ayrı ayrı kaydedilir
Erişim Türü	Okuma ve yazma erişimi uygulama düzeyinde kontrol edilir.	Okuma ve yazma erişimi kapsam düzeyinde kontrol edilir.
Ek URL'ler	Yönlendirme URL'si: Kullanıcıların kapsamları yetkilendirdikten sonra yönlendirildiği site	Yetkilendirilmiş JavaScript Kaynakları: Web uygulamasını barındıran HTTP kaynağı Yönlendirme URL'si: Kullanıcıların kapsamları yetkilendirdikten sonra yönlendirildiği site

OAuth Uygulaması

Google Health API uygulamaları yalnızca Google OAuth2 istemci kitaplıklarını destekler. Popüler çerçeveler için istemci kitaplıkları mevcuttur. Bu sayede OAuth 2.0'ı uygulamak daha kolaydır. Google OAuth2 kitaplıkları ile açık kaynak OAuth2 kitaplıkları arasındaki farklar şunlardır:

	Fitbit Web API	Google Health API
OAuth2 kitaplığı desteği	Açık Kaynak	Google OAuth2 istemci kitaplıkları
İşlevsellik	Platformlar arasında tutarsızlık	Platformlar arasında tutarlılık
Yetkilendirme URL'si	https://www.fitbit.com/oauth2/authorize	https://accounts.google.com/o/oauth2/v2/auth
Jeton URL'si	https://api.fitbit.com/oauth2/token	https://oauth2.googleapis.com/token
Erişim Jetonu Ömrü	8 saat	1 saat
Erişim Jetonu Boyutu	1.024 bayt	2.048 bayt
Yenileme Jetonu	Yenileme jetonları, yetkilendirme kodu verme akışı kullanılırken oluşturulur. Bir kullanıcı için yalnızca 1 yenileme jetonu oluşturulabilir. Jetonların geçerlilik süresi yoktur ve yalnızca bir kez kullanılabilir.	Yenileme jetonu oluşturmak için yetkilendirme dizesi "access_type=offline" sorgu parametresini içermelidir. Tek bir kullanıcı için birden çok yenileme jetonu oluşturulabilir. Yenileme jetonları zamana dayalı olabilir. Bu jetonlar 6 ay içinde kullanılmazsa, kullanıcı zamana dayalı erişim izni verirse veya uygulama "Test" modundaysa süresi dolar. Daha fazla bilgi için Yenileme jetonu geçerlilik süresi bölümüne bakın.
Jeton Yanıtı	JSON yanıtı şunları içerir: erişim jetonu erişim jetonunun süresinin dolması kapsamlar jeton türü yenileme jetonu kullanıcı kimliği	JSON yanıtı şunları içerir: erişim jetonu erişim jetonunun süresinin dolması kapsamlar jeton türü yenileme jetonu Kullanıcı kimliğini almak için users.getIdentity uç noktasını kullanın.

Uygulamanız farklı bir OAuth kitaplığı kullandığından Fitbit kullanıcılarının yeni entegrasyonunuz için yeniden izin vermesi gerekir. Erişim jetonlarının ve yenileme jetonlarının Google Health API'ye aktarılması ve çalışması mümkün değildir.

Kapsamlar

Google Health API kapsamlarını kullanmak için yetkilendirme isteğinizi güncellemeniz gerekir. Kapsamlar, uygulamanızın okuma veya yazma işlemlerini destekleyip desteklemediğini tanımlar. Uygulamanız için gerekli olmayan kapsamları kullanmayın. Uygulamanızın tasarımı değişirse daha sonra istediğiniz zaman kapsam ekleyebilirsiniz.

Google Health API kapsamları, https://www.googleapis.com/auth/googlehealth.{scope} ile başlayan bir HTTP URL'sidir. Örneğin, https://www.googleapis.com/auth/googlehealth.activity_and_fitness.

Kapsam eşlemeleri

Fitbit Web API kapsamlarının Google Health API kapsamlarıyla eşleşme şekli aşağıda verilmiştir:

*Tablo: Fitbit Web API'den Google Health API kapsam eşlemeleri*
Fitbit Web API Kapsamları	Google Health API Kapsamları
etkinlik	.activity_and_fitness .activity_and_fitness.readonly
cardio_fitness	.activity_and_fitness .activity_and_fitness.readonly
heartrate	.health_metrics_and_measurements .health_metrics_and_measurements.readonly
konum	.location.readonly
beslenme	.nutrition .nutrition.readonly
oxygen_saturation	.health_metrics_and_measurements .health_metrics_and_measurements.readonly
profil	.profile .profile.readonly
respiratory_rate	.health_metrics_and_measurements .health_metrics_and_measurements.readonly
ayarlar	.settings .settings.readonly
uyku	.sleep .sleep.readonly
sıcaklık	.health_metrics_and_measurements .health_metrics_and_measurements.readonly
ağırlık	.health_metrics_and_measurements .health_metrics_and_measurements.readonly

Veri türleri

Google Health API veri türlerinin ve bunların Fitbit Web API'si ile nasıl eşlendiğinin listesini aşağıda bulabilirsiniz.

*Tablo: Fitbit Web API'den Google Health API'ye veri türü eşlemeleri*
Fitbit Web API Veri Türü	Google Health API Veri Türü Uç nokta kimliği
Aktif Bölge Dakikası	Aktif Bölge Dakikası `active-zone-minutes`
Kullanıcının etkinlik düzeylerindeki değişiklikleri içerir.	Etkinlik Düzeyi `activity-level`
Rakım	Yükseklik `altitude`
Vücut yağ yüzdesi	Vücut Yağı `body-fat`
Her nabız bölgesinde `caloriesOut`	Kalp Atış Hızı Bölgesindeki Kalori Miktarı `calories-in-heart-rate-zone`
HRV özeti	Günlük Nabız Değişkenliği `daily-heart-rate-variability`
SpO2 özeti	Günlük oksijen doygunluğu `daily-oxygen-saturation`
Dinlenme nabzı	Günlük Dinlenme Nabzı `daily-resting-heart-rate`
Deri sıcaklığı	Günlük Uyku Sıcaklığı Türetmeleri `daily-sleep-temperature-derivations`
Mesafe	Mesafe `distance`
Kayıt etkinliği	Egzersiz `exercise`
Döşeme	Katlar `floors`
Nabız	Kalp Atış Hızı `heart-rate`
HRV Intraday	Nabız değişkenliği `heart-rate-variability`
SpO2 Gün İçi	Oksijen Doygunluğu `oxygen-saturation`
Kullanıcı koşarken VO2 maks değeri	Maksimum oksijen tüketimi koşusu `run-vo2-max`
Etkinlik zaman serisi, hareketsiz geçirilen süre (dakika)	Hareketsiz Kalma Süresi `sedentary-period`
Uyku	Uyku `sleep`
Adımlar	Adımlar `steps`
Etkinlik `caloriesOut`	Toplam Kalori `total-calories`
Maksimum oksijen tüketimi değeri	VO2 Maks `vo2-max`
Ağırlık	Ağırlık `weight`

Uç noktalar

REST uç noktaları, tüm veri türleri için tutarlı bir söz dizimi kullanır.

Hizmet Uç Noktası: Temel HTTP URL'si https://health.googleapis.com olarak değişir.
Uç nokta söz dizimi: Google Health API, desteklenen veri türlerinin çoğu tarafından kullanılabilen sınırlı sayıda uç noktayı destekler. Bu, tüm veri türleri için tutarlı bir söz dizimi sağlar ve uç noktaların kullanılmasını kolaylaştırır.
Kullanıcı tanımlayıcısı: Uç nokta söz diziminde kullanıcı kimliği veya ben belirtilmelidir. Kullanıcı beni kullanırken kullanıcı kimliği, erişim jetonundan çıkarılır.

Örnek: Google Health API kullanılarak çağrılan GET Profile uç noktası örneğini aşağıda bulabilirsiniz.

GET https://health.googleapis.com/v4/users/me/profile

Uç nokta eşlemeleri

Kullanılabilen veri türlerinin ve destekledikleri API yöntemlerinin listesi için Veri Türü Kullanılabilirliği tablosuna bakın.

Fitbit Web API Uç Nokta Türü	Google Health API
Tek bir günlük veri istediğiniz GET (Log \| Summary \| Daily Summary)	`windowSize` = 1 gün olan dailyRollup yöntemi
Ayrıntılı veriler istediğiniz GET (gün içi)	list yöntemi
Tarihe veya aralığa göre GET (zaman serisi)	Tarih aralığı içeren rollUp veya dailyRollUp yöntemi
GET (Günlük Listesi)	list yöntemi
Günlük oluşturma ve güncelleme	patch yöntemi
Günlükleri SİL	batchDelete yöntemi
GET Profile	users.getProfile, kullanıcının belirli bilgilerini döndürür. users.getSettings, kullanıcının birimlerini ve saat dilimlerini döndürür.
Profili GÜNCELLEME	users.updateProfile, kullanıcının belirli bilgilerini değiştirir. users.updateSettings, kullanıcının birimlerini ve saat dilimlerini değiştirir.
Kullanıcı kimliğini alma	users.getIdentity, kullanıcının eski Fitbit ve Google kullanıcı kimliğini döndürür.

Kullanıcılarınızı taşıma

Fitbit Web API'den Google Health API'ye geçiş, teknik bir güncellemeden daha fazlasıdır. OAuth kitaplığının değiştirilmesi nedeniyle kullanıcılarınızın yeni entegrasyonunuz için yeniden izin vermesi gerekir. Erişim jetonlarının ve yenileme jetonlarının Google Health API'ye aktarılması ve çalışması mümkün değildir. Taşıma işleminiz sırasında kullanıcıları elde tutmanıza yardımcı olmak için başarılı bir taşıma işlemine yönelik bazı teknik ve stratejik önerileri aşağıda bulabilirsiniz.

Çift kitaplık stratejisi

Fitbit Web API ve Google Health API farklı OAuth2 kitaplıklarını kullandığından, her iki kitaplığın da kod tabanınızda bulunduğu bir "köprüleme" dönemi yönetmeniz gerekir.

Paralel Yetkilendirme Yönetimi

İstemcileri Kapsülleme: "Sağlık Hizmetiniz" için bir soyutlama katmanı veya arayüz oluşturun. Bu sayede uygulamanızın geri kalanı, söz konusu kullanıcı için hangi kitaplığın (Fitbit OAuth veya Google OAuth) etkin olduğunu bilmeden veri isteyebilir.
Veritabanı Şema Güncellemesi: Kullanıcı tablonuzu oauth_type işaretini içerecek şekilde güncelleyin. Örneğin, Fitbit OAuth için fitbit, Google OAuth için google kullanın.
- Yeni Kullanıcılar: Varsayılan olarak Google Health API ve Google OAuth kitaplığı kullanılır. oauth_type değerini google olarak ayarlayın.
- Mevcut Kullanıcılar: Yeniden izin verme akışını tamamlayana kadar Fitbit Web API'de kalır. oauth_type değerini fitbit olarak ayarlayın.

"Step-Up" yeniden izin akışı

Kullanıcıyı çıkış yapmaya zorlamak yerine kademeli yetkilendirme yaklaşımını kullanın:

Fitbit Açık Kaynak Jetonunu Algılama: Bir Fitbit Web API kullanıcısı uygulamayı açtığında "Hizmet Güncellemesi" bildirimi tetiklenir.
Google OAuth akışını başlatın: Kullanıcı "Güncelle"yi tıkladığında Google OAuth2 kitaplığı akışını başlatın.
Değiştirme ve İptal Etme: Google OAuth jetonu başarıyla alındıktan sonra kullanıcı profiline kaydedin, oauth_type değerini fitbit olarak güncelleyin ve (mümkünse) kullanıcının güvenlik profilini temiz tutmak için eski fitbit jetonunu programatik olarak iptal edin.google

Kullanıcıları elde tutma oranını en üst düzeye çıkarma

Yeniden izin alma, müşteri kaybı açısından "tehlikeli bölge"dir. Kullanıcıların uygulamayı terk etmesini önlemek için aşağıdaki kullanıcı deneyimi en iyi uygulamalarını uygulayın:

"Önce Değer" İletişimi

“API'mizi güncelledik” ifadesiyle başlamayın. Yeni Google destekli sistemin avantajlarını vurgulayın:

Gelişmiş güvenlik: Google'ın sektör lideri hesap koruması ve iki faktörlü kimlik doğrulamadan bahsedin.
Güvenilirlik: Daha hızlı senkronizasyon süreleri ve daha kararlı veri bağlantıları.
Özellik Kilitleme: Kullanıcıları, yeni özellikler ve veri türleri için güncelleme yapılması gerektiği konusunda nazikçe bilgilendirin.

Akıllı Zamanlama

Yüksek Değerli Görevleri Kesintiye Uğratmayın: Kullanıcı antrenman yaparken veya yiyecekleri günlüğe kaydederken yeniden kullanıcı rızası ekranını asla tetiklemeyin.
"Hatırlatma" aşaması: İlk 30 gün boyunca kapatılabilir bir banner kullanın.
"Kesin Sonlandırma" Aşaması: Yeniden izni yalnızca resmi Fitbit Web API desteğinin sonlandırılmasıyla ilgili son tarihlerle aynı zamana denk gelecek şekilde, birkaç hafta boyunca uyarılar gönderdikten sonra zorunlu kılın.

Taşıma Akışı Karşılaştırması

Eski ve yeni akışlar arasındaki net görsel ayrım, geliştiricilerin mantığın nerede dallandığını anlamasına yardımcı olur.

Özellik	Fitbit Web API (Eski)	Google Health API (Google-Identity)
Auth Library	Standart Açık Kaynak	Google Kimlik Hizmetleri (GIS) / Google Auth
Kullanıcı Hesapları	Fitbit Eski Kimlik Bilgileri	Google Hesabı
Jeton Türü	Fitbit'e özel erişim / yenileme	Google tarafından verilen erişim/yenileme jetonları
Kapsam Yönetimi	Geniş kapsamlı izinler	Ayrıntılı / Artımlı izinler

Hesap taşıma işleminin inceliklerini ele alma

Fitbit'in dokümanlarına göre, hesaplarını Google'a taşıyan kullanıcılar genellikle üçüncü taraf bağlantılarını hemen kaybetmez. Ancak API sürümünü değiştirmek geliştirici tarafında zorunlu bir işlemdir.

Jeton Geçerliliğini Kontrol Etme: Fitbit jetonlarının "Yetkisiz" hatalarıyla başarısız olup olmadığını kontrol etmek için bir arka plan çalışanı kullanın. Bu durum, kullanıcının hesabını taşıdığını ancak uygulamanızın bu değişikliği henüz algılamadığını gösterebilir.
Sorunsuz Hata: Bir Fitbit OAuth çağrısı başarısız olursa kullanıcıyı, yeni Google OAuth akışını özel olarak kullanan özel bir "Fitbit'e yeniden bağlan" sayfasına yönlendirin.

Kod örneği

Eski Fitbit Web API'den Google Health API'ye geçmek için genel OAuth2 kitaplıklarından Google Auth Kitaplığı'na geçmeniz gerekir. Aşağıda, bu "Çift Kitaplık" durumunu işlemek için JavaScript'te yazılmış bir mimari öneri ve sözde kod uygulaması verilmiştir.

1. "Ara Katman Yazılımı Anahtarı"

Tüm kullanıcıları aynı anda taşıyamayacağınız için arka uçunuzun, veritabanınızda depolanan kullanıcının mevcut apiVersion değerine göre hangi kitaplığın kullanılacağını belirlemesi gerekir.

Uygulama

const { OAuth2Client } = require('google-auth-library');
const FitbitV1Strategy = require('fitbit-oauth2-library').Strategy;

// 1. Initialize the Google Health API Client
const GHAClient = new OAuth2Client(
  process.env.GOOGLE_CLIENT_ID,
  process.env.GOOGLE_CLIENT_SECRET,
  process.env.REDIRECT_URI
);

// 2. Create a Unified Fetcher
async function fetchSteps(user) {
  if (user.apiVersion === 4) {
    // ---- GOOGLE OAUTH LIBRARY LOGIC ----
    GHAClient.setCredentials({ refresh_token: user.refreshToken });
    const url = 'GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints';
    const res = await GHAClient.request({ url });
    return res.data;
  } else {
    // ---- FITBIT WEB API LEGACY LOGIC ----
    // Use your existing Fitbit open-source library logic here
    return callLegacyV1Api(user.accessToken);
  }
}

2. Kullanıcı deneyimi akışını taşıma

Elde tutma oranını en üst düzeye çıkarmak için "Kesintiye uğrat ve yükselt" modelini kullanın. Bu sayede, kullanıcı uygulamayla etkileşime geçene kadar yeniden giriş yapmaya zorlanmaz.

Yönlendirme mantığı

Bir Fitbit Web API kullanıcısı belirli bir özelliği kullandığında taşıma işlemini tetikleyin:

app.get('/dashboard', async (req, res) => {
  const user = await db.users.find(req.user.id);

  if (user.apiVersion === 1) {
    // Render a "soft" migration page explaining the Google transition
    return res.render('migrate-to-google', {
      title: "Keep your data syncing",
      message: "Fitbit is moving to Google accounts. Re-connect now to stay updated."
    });
  }

  const data = await fetchSteps(user);
  res.render('dashboard', { data });
});

3. Önemli Teknik Geçişler

JavaScript taşıma komut dosyalarınızı yazarken aşağıdaki farkları göz önünde bulundurun:

Özellik	Fitbit Web API (Eski)	Google Health API (Google-Identity)
Jeton Uç Noktası	https://api.fitbit.com/oauth2/token	https://oauth2.googleapis.com/token
Auth Library	Standart Açık Kaynak	Google Auth
Kapsam	etkinlik	https://www.googleapis.com/auth/googlehealth.activity_and_fitness
Kullanıcı Kimliği	/oauth2/token yanıtında döndürülen Fitbit kodlanmış kimliği	users.getIdentity uç noktasından döndürülen kullanıcı kimliği

4. Elde tutma kontrol listesi

Oturumun Kalıcılığı: Google Health API access_token'ı başarıyla doğrulanıp veritabanınıza kaydedilene kadar kullanıcının eski Fitbit Web API oturumunu temizlemeyin.
Otomatik iptal: Google Health API'ye geçiş tamamlandıktan sonra, eski Fitbit iptal uç noktasına POST isteği gönderin: https://api.fitbit.com/oauth2/revoke. Bu sayede kullanıcı, Fitbit ayarlarında "yinelenen" uygulama izinleri görmez.
Hata İşleme: Bir Fitbit çağrısı 401 Yetkisiz yanıtını döndürürse hata mesajı göstermek yerine otomatik olarak Google OAuth akışına yönlendirin.

Taşıma rehberi Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.