Android Sleep API 程式碼研究室

1. 簡介

建構項目

在本程式碼研究室中，您會建構 Android 應用程式來偵測使用者的睡眠時間。這個應用程式將：

要求權限
註冊 Android Sleep API
擷取 API 事件並在使用者介面中顯示
不再需要取消註冊

軟硬體需求

最新版本的 Android Studio (Android Build Tools v21 以上版本)
搭載 Android 10 (API 級別 29) 以上版本的裝置

2. 開始設定

複製範例專案存放區

為了方便您盡快上手，我們準備了新手範例專案。在終端機 / 指令列中輸入 git --version，確認您使用 git。如果尚未安裝，請按照這裡的操作說明安裝。然後執行下列指令，以複製專案。

 git clone https://github.com/android/codelab-android-sleep/

匯入專案

啟動 Android Studio，然後在歡迎畫面中選取「Open an existing Android Studio project」，然後開啟專案目錄。

專案載入後，系統也可能會顯示快訊，通知您 Git 不會追蹤所有本機變更。您可以按一下「Ignore」或右上方的「X」圖示 (系統不會將任何變更推送回 Git 存放區。)

如果您在「Android」檢視畫面中，專案視窗的左上角會顯示如下圖所示的項目 (在「Project」檢視畫面中，您必須展開專案才能看到這些項目)。

共有兩個資料夾圖示 (start 和 complete)。每個資料夾圖示都稱為「module」(模組)。

請注意，由於 Android Studio 首次會在背景編譯專案，因此可能需要幾秒鐘的處理時間。在此期間，Android Studio 底部的狀態列會顯示旋轉圖示：

建議您等到此動作完成後再變更程式碼。這使 Android Studio 提取所有必要的元件。

此外，如果畫面顯示「Reload for language changes to take effect?」的提示或類似內容，請選取「Yes」。

瞭解範例專案

一切準備就緒，可以新增活動辨識功能了。我們將使用 start 模組，這是本程式碼研究室的起點。換句話說，您必須在每個步驟中新增程式碼至 start。

complete 模組可用於檢查你的作品，在發生問題時也可以參考。

主要元件總覽：

MainActivity.kt：在使用者啟動應用程式時顯示應用程式主畫面。
SleepReceiver.kt：從 API 擷取並儲存睡眠事件至資料庫。
BootReceiver.kt：在裝置開機完成時重新註冊 Sleep API，以便監聽 Sleep API 事件。

執行範例專案

執行應用程式。

將 Android 裝置連接到電腦。
在工具列中，從下拉式選取器中選取 start 設定，選取所需裝置，然後按一下旁邊的綠色三角形 (執行) 按鈕：

裝置上應會顯示下列應用程式：

我們尚未實際新增任何用於追蹤睡眠情況的程式碼，不過會在之後的章節提供。

我們將在下一節查看必要的程式庫和權限。

3. 查看程式庫及新增權限

查看 build.gradle 和 AndroidManifest.xml

若要在應用程式中使用 Sleep API，您必須宣告 Google 位置和活動辨識 API 的依附元件，並在應用程式資訊清單中指定 com.google.android.gms.permission.ACTIVITY_RECOGNITION 權限。

在 start 模組的 build.gradle 檔案中，搜尋 「TODO: Review play services library required for activity recognition」(TODO：查看活動辨識所需的遊戲服務程式庫)。這個步驟沒有任何動作。您只需查看我們需要的已宣告依附元件，看起來應該像這樣：

    // TODO: Review play services library required for activity recognition.
    implementation 'com.google.android.gms:play-services-location:18.0.0'

在 start 模組中，搜尋 AndroidManifest.xml 中的「TODO: Add activity recognition and boot complete permissions」，並將下列程式碼新增至 <manifest> 元素。

<!-- TODO: Add activity recognition and receive boot complete permissions. -->
<!-- Required for 29+. -->
<uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />

您的程式碼現在看起來應該會像這樣：

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
         package="com.android.example.sleepcodelab">
...
<!-- TODO: Add activity recognition and receive boot complete permissions. -->
<!-- Required for 29+. -->
<uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
  ...
</manifest>

如註解所示，您必須新增 API 29 版本的執行階段權限。

大功告成！您的應用程式現在可以支援睡眠活動辨識功能。只需要新增該程式碼就能完成。

查看活動辨識權限檢查

若有必要，我們必須檢查及要求執行階段權限：

我們會在 MainActivity.kt 中檢查活動辨識權限。
若未授予權限，我們會呼叫 displayPermissionSettingsSnackBar()。這個 Snackbar 說明權限的需求，並讓使用者可在系統設定中核准該權限。

在 start 模組中，搜尋 MainActivity.kt 中的 「TODO: Review Activity Recognition permission check」(TODO：查看活動辨識權限檢查)。此時，你會看到這個程式碼片段。

注意：這個部分沒有任何動作。

// TODO: Review Activity Recognition permission checking.
private fun activityRecognitionPermissionApproved(): Boolean {
   return PackageManager.PERMISSION_GRANTED == ActivityCompat.checkSelfPermission(
           this,
           Manifest.permission.ACTIVITY_RECOGNITION
   );
}

啟用/停用睡眠追蹤功能

在 start 模組中，搜尋 MainActivity.kt 中的「TODO: Enable/Disable Sleep tracking and ask for permissions if needed」。請將 onClickRequestSleepData() 方法替換為以下程式碼。

// TODO: Enable/Disable sleep tracking and ask for permissions if needed.
fun onClickRequestSleepData(view: View) {
   if (activityRecognitionPermissionApproved()) {
       if (subscribedToSleepData) {
           unsubscribeToSleepSegmentUpdates(applicationContext, sleepPendingIntent)
       } else {
           subscribeToSleepSegmentUpdates(applicationContext, sleepPendingIntent)
       }
   } else {
       requestPermissionLauncher.launch(permission.ACTIVITY_RECOGNITION)
   }
}

如果「動作辨識」權限已獲核准，且使用者訂閱了睡眠資料，系統就會訂閱睡眠更新通知。否則，我們會取消訂閱。

針對使用者未授予權限的情況，我們會傳送啟動畫面活動給使用者，說明需要取得權限的原因並允許使用者啟用。

4. 訂閱 Sleep API 更新

建立 PendingIntent

在 start 模組中，搜尋 MainActivity.kt 中的「TODO: Create a PendingIntent for Sleep API events」。貼上下列程式碼片段。

// TODO: Create a PendingIntent for Sleep API events
sleepPendingIntent =
   SleepReceiver.createSleepReceiverPendingIntent(context = applicationContext)

現在，我們終於在可取得 Sleep API 資料時取得更新通知。

要求取得 Sleep API 更新通知

在 start 模組中，搜尋 MainActivity.kt 中的「TODO: Request Sleep API Updates」。貼上下列程式碼片段。

// TODO: Request Sleep API updates
val task = ActivityRecognition.getClient(context).requestSleepSegmentUpdates(
   pendingIntent,
   // Registers for both SleepSegmentEvent and SleepClassifyEvent data.
   SleepSegmentRequest.getDefaultSleepSegmentRequest()
)

task.addOnSuccessListener {
   mainViewModel.updateSubscribedToSleepData(true)
   Log.d(TAG, "Successfully subscribed to sleep data.")
}
task.addOnFailureListener { exception ->
   Log.d(TAG, "Exception when subscribing to sleep data: $exception")
}

成功註冊 Sleep API 更新通知後，您的應用程式會在註冊的 PendingIntent 中收到睡眠偵測通知。

在 start 模組中，搜尋 receiver/BootReceiver.kt 中的 「TODO: Request Sleep API」(TODO：要求取得 Sleep API)。貼上下列程式碼片段。

// TODO: Request Sleep API upon boot complete
val subscribedToSleepData = repository.subscribedToSleepDataFlow.first()
if (subscribedToSleepData) {
   subscribeToSleepSegmentUpdates(
       context = context,
       pendingIntent = SleepReceiver.createSleepReceiverPendingIntent(context)
   )
}

這個程式碼可讓應用程式在裝置重新啟動後繼續接收 Sleep API 更新通知。

5. 處理事件

發生睡眠分類或睡眠時間偵測事件時，您的應用程式會收到 Intent 回呼。您可以從 Intent 擷取 SleepSegmentEvent 或 SleepClassifyEvent 物件的清單。

讓我們新增程式碼來處理這些事件。

在 start 模組中，搜尋 receiver/SleepReceiver.kt 中的「TODO: Extract sleep information from PendingIntent」。在註解後方新增以下程式碼。

// TODO: Extract sleep information from PendingIntent.
if (SleepSegmentEvent.hasEvents(intent)) {
   val sleepSegmentEvents: List<SleepSegmentEvent> =
       SleepSegmentEvent.extractEvents(intent)
   addSleepSegmentEventsToDatabase(repository, sleepSegmentEvents)
} else if (SleepClassifyEvent.hasEvents(intent)) {
   val sleepClassifyEvents: List<SleepClassifyEvent> =
       SleepClassifyEvent.extractEvents(intent)
   addSleepClassifyEventsToDatabase(repository, sleepClassifyEvents)
}

這項操作會將 SleepSegmentEvent 或 SleepClassifyEvent 資料儲存至會議室資料庫。MainActivity 使用 LiveData 透過 ViewModel 存取該資料庫資訊。若要進一步瞭解這些類別如何搭配運作，請參閱設有檢視畫面程式碼研究室的聊天室。

這樣就完成了！請嘗試執行應用程式。

6. 安裝應用程式並查看程式碼

使用傳輸線將裝置連結至工作站。在 Android Studio 中按一下「Run」，即可在您的裝置上安裝及執行應用程式。授予「動作辨識」權限並輕觸「SUBSCRIBE TO SLEEP DATA」按鈕後，第一個 SleepClassifyEvent 應該會在大約 10 分鐘後顯示。SleepSegmentEvent 應該會在 1 天內顯示。

歡迎您隨時詳閱完整程式碼，瞭解自己完成的部分，並進一步瞭解程式碼如何搭配運作。

查看程式碼 (選擇性)

以下查看程式碼是選擇性。其中包含 Sleep API 和資料庫實體之間的資料對應詳細資料：

data/db/SleepClassifyEventEntity.kt
data/db/SleepSegmentEventEntity.kt