建議您遵循下列最佳做法指南，確保應用程式能搭配 Health Connect 良好運作。
寫入資料
應用程式只能將「擁有來源」的資料寫入 Health Connect。
如果應用程式資料是從另一個應用程式匯入，則應由該應用程式負責將其擁有的資料寫入 Health Connect。
此外，建議您針對資料寫入例外狀況導入處理邏輯，例如資料在邊界外或發生內部系統錯誤時。您可以對工作排程機制套用輪詢和重試策略。如果最終無法順利寫入 Health Connect，請確保應用程式能夠移出該匯出點。請務必記錄並回報錯誤，以利診斷作業。
追蹤資料時，您可以根據應用程式寫入資料的方式採用以下幾項建議。
被動追蹤
這包括提供被動健身或健康追蹤功能的應用程式，例如在背景持續記錄步數或心率。
應用程式需採用以下做法，定期將資料寫入 Health Connect：
- 每次進行同步處理時，請僅寫入新資料及上次同步後修改的更新資料。
- 在每個寫入要求中，區塊要求最多為 1000 條記錄。
- 使用
WorkManager安排週期性背景工作，時間長度至少為 15 分鐘。 請限制只在裝置處於閒置狀態且電量充足時執行工作。
val constraints = Constraints.Builder() .requiresBatteryNotLow() .requiresDeviceIdle(true) .build() val writeDataWork = PeriodicWorkRequestBuilder<WriteDataToHealthConnectWorker>( 15, TimeUnit.MINUTES, 5, TimeUnit.MINUTES ) .setConstraints(constraints) .build()
主動追蹤
這類應用程式功能包括執行以運動和睡眠等事件為基礎的追蹤功能，或讓使用者手動輸入營養攝取等資訊。如果應用程式是在前景運作，或事件發生頻率相當低 (如一天幾次)，就會建立這類記錄。
請確保在整個事件期間，應用程式不會要求 Health Connect 保持在執行狀態。
資料必須透過以下其中一種方式寫入 Health Connect：
- 在事件完成後，將資料同步處理至 Health Connect。例如在使用者結束追蹤的運動時段後同步處理資料。
- 使用
WorkManager排定一次性工作，稍後再同步處理資料。
取樣率
將資料寫入 Health Connect 時，請使用適當的取樣率，協助降低儲存空間負載。舉例來說，建議您考量步數資料的記錄頻率，或是根據進行中健身活動 (比如速度訓練)，考慮須採用何種相連結的取樣率資料類型。
您不必為所有資料類型採用相同的取樣率。如要更新步數資料，每秒取樣一次的效果不會優於採用較低的取樣頻率，例如每 60 秒一次。不過，取樣率較高可讓使用者更詳細瞭解自己的健康與健身資料。您需要在精細程度和效能之間取得平衡，採用適當的取樣頻率。
同步處理資料
以下因素會影響同步處理程序。
權杖到期
未使用的「變更」權杖會在 30 天內到期，因此請務必採用適當的同步策略，避免在這類情況下遺失資訊。策略可包含以下方法：
- 搜尋應用程式資料儲存庫，找出最近取用且含有 Health Connect
id的記錄。 - 要求 Health Connect 提供特定時間戳記之後的記錄，並在應用程式資料儲存庫中插入或更新該記錄。
- 要求提供變更權杖，並保留至下次需要時使用。
建議的變更管理策略
如果應用程式收到無效或過期的「變更」權杖，建議您根據邏輯適用情形，採用下列管理策略：
- 讀取及簡化所有資料。這是最理想的策略。
- 儲存上次從 Health Connect 讀取資料時的時間戳記。
- 在權杖過期時，從最近的時間戳記或過去 30 天重新讀取所有資料。接著請根據先前讀取的資料，使用 ID 簡化這些資料。
- 在理想情況下，請實作用戶端 ID，因為必須使用用戶端 ID 才能更新資料。
- 僅限讀取自上次讀取時間戳記以來的資料。這會導致變更權杖到期前後的資料出現落差，但時間範圍會較短，可能需要數小時至數天。
- 儲存上次從 Health Connect 讀取資料時的時間戳記。
- 在權杖到期時，讀取這個時間戳記後的所有資料。
- 刪除再讀取過去 30 天的資料。這更貼近第一項整合作業的情況。
- 刪除應用程式在過去 30 天內從 Health Connect 讀取的所有資料。
- 刪除完成後，再次讀取所有資料。
- 讀取過去 30 天的資料，且不刪除重複的資料。這是最不理想的策略，且會導致使用者看到重複的資料。
- 刪除應用程式在過去 30 天內從 Health Connect 讀取的所有資料。
- 允許重複的項目。
資料類型變更權杖
如果應用程式可獨立取用多種資料類型，請針對每種資料類型使用單獨的變更權杖。請只在同時取用或完全不取用多種資料類型時，搭配使用資料類型清單與 Changes Sync API。
前景讀取
應用程式只有在前景運作時，才能從 Health Connect 讀取資料。從 Health Connect 同步處理資料時，Health Connect 的存取作業隨時可能中斷。舉例來說，應用程式從 Health Connect 讀取大量資料時，必須能處理同步作業中途發生的干擾，並在下次開啟應用程式時繼續作業。
匯入時間
如果應用程式無法在資料新增時收到通知，則應在以下兩個時間點檢查新資料：
- 每當應用程式開始在前景運作時。請在這種情況下使用生命週期事件。
- 應用程式持續在前景運作的期間。請定期檢查新資料。有新資料時通知使用者，讓使用者更新畫面以反映變更。
頻率限制
在少數情況下，Health Connect 會對應用程式要求設下頻率限制。這是為了降低對電池和裝置效能的影響。
- 我們強烈建議您遵循以下最佳做法指南，避免應用程式要求因頻率限制而遭到拒絕。
- 應用程式應有效應對頻率限制。舉例來說，如果要求因頻率限制而失敗，可以在下一個週期性工作期間寫入背景資料。
匯出應用程式新手上路活動
許多應用程式都有自訂的新手上路流程，例如功能教學，或徵詢使用者同意。我們強烈建議開發人員匯出 Health Connect 在使用者首次與應用程式互動時啟動的新手上路活動。方法是在資訊清單中新增以下內容：
<!-- Required to support pre-Android 14 devices with APK Health Connect -->
<activity
android:name=".OnboardingActivity"
android:exported="true"
android:permission="com.google.android.apps.healthdata.permission.START_ONBOARDING"
<intent-filter>
<action android:name="androidx.health.ACTION_SHOW_ONBOARDING"/>
</intent-filter>
</activity>
<!-- Required to support Android 14+ devices with platform Health Connect -->
<activity-alias
android:name="UAndAboveOnboardingActivity"
android:exported="true"
android:targetActivity=".OnboardingActivity"
android:permission="android.permission.health.START_ONBOARDING">
<intent-filter>
<action android:name="android.health.connect.action.ACTION_SHOW_ONBOARDING" />
</intent-filter>
</activity-alias>
請注意，Android 14 尚未提供此功能的相關支援，但很快就會推出。
如果使用者嘗試將應用程式與 Health Connect 連線，系統就會啟動匯出的活動。此活動必須要能符合以下條件：
- 顯示任何相關的使用者教學內容，例如說明會寫入或讀取哪些資料。
- 視情況徵詢使用者同意。
- 向 Health Connect 提出權限要求。
- 執行任何其他應用程式專屬邏輯，例如安排週期性 worker。
- 完成後，請允許使用者關閉活動。
對於「未」匯出新手上路活動的應用程式，Health Connect 會在使用者嘗試連線應用程式時，改為將他們導向「管理權限」畫面。如果應用程式必須取得權限，整合項目才能正常運作，或許就可以採用上述做法。
請注意，新手上路活動可能會多次啟動，例如使用者之後撤銷授予應用程式的權限，然後又重新連結，就會發生此情況。