建議您遵循下列最佳做法指南,確保應用程式能搭配 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 會在使用者嘗試連線應用程式時,改為將他們導向「管理權限」畫面。如果應用程式必須取得權限,整合項目才能正常運作,或許就可以採用上述做法。
請注意,新手上路活動可能會多次啟動,例如使用者之後撤銷授予應用程式的權限,然後又重新連結,就會發生此情況。