偵測使用者何時開始或結束一項活動

應用程式可能必須經過特別設計，以識別使用者何時開始或停止特定活動，例如步行、騎單車或開車。舉例來說，當使用者開始開車時，里程追蹤應用程式可以開始追蹤里程數，或者訊息應用程式可以將所有對話靜音，直到使用者停止駕駛為止。

Activity Recognize Transition API 可用來偵測使用者活動的變化。應用程式會訂閱需要追蹤的活動轉換事件，而 API 只會在需要時才會向應用程式發出通知。本頁面介紹如何使用 Activity Recognize Transition API (簡稱為 Transition API)。

設定專案

如果要在應用程式中使用 Transition API，必須宣告一個 Google Location 及 Activity Recognition API 12.0.0 及以上版本的依附元件，並在應用程式資訊清單中指定 com.google.android.gms.permission.ACTIVITY_RECOGNITION 權限。

1. 若要對 API 宣告一個依附元件，請在 Google Maven 存放區中新增參考資料，接著將執行的輸入內容新增至 com.google.android.gms:play-services-location:12.0.0 中，以加至應用程式 build.gradle 檔案的依附元件部分。詳情請參閱「設定 Google Play 服務」一文。

2. 若要指定 com.google.android.gms.permission.ACTIVITY_RECOGNITION 的權限，請在應用程式資訊清單中新增 <uses-permission> 元素，如以下範例所示：

    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
            package="com.example.myapp">
   
      <uses-permission android:name="com.google.android.gms.permission.ACTIVITY_RECOGNITION" />
      …
    </manifest>
   

註冊活動轉換的狀態更新

若要接收活動轉換的通知，必須導入以下程式碼：

• ActivityTransitionRequest 物件，用於指定活動類型以及其轉換。
• PendingIntent 回呼，用於應用程式接收通知。詳情請參閱「使用待處理意圖」一節。

若要建立 ActivityTransitionRequest 物件，必須建立一個 ActivityTransition 物件清單，內容為想要接收通知的轉換。ActivityTransition 物件，其中包含下列資料：

• 以 DetectedActivity 類別表示的活動類型。Transition API 支援下列活動：
  • IN_VEHICLE
  • ON_BICYCLE
  • RUNNING
  • STILL
  • WALKING
• ACTIVITY_TRANSITION_ENTER 或 ACTIVITY_TRANSITION_EXIT 的轉換類型。 詳情請參閱 ActivityTransition 類別。

以下程式碼顯示如何建立 ActivityTransition 物件清單：

val transitions = mutableListOf<ActivityTransition>()

transitions +=
        ActivityTransition.Builder()
          .setActivityType(DetectedActivity.IN_VEHICLE)
          .setActivityTransition(ActivityTransition.ACTIVITY_TRANSITION_ENTER)
          .build()

transitions +=
        ActivityTransition.Builder()
          .setActivityType(DetectedActivity.IN_VEHICLE)
          .setActivityTransition(ActivityTransition.ACTIVITY_TRANSITION_EXIT)
          .build()

transitions +=
        ActivityTransition.Builder()
          .setActivityType(DetectedActivity.WALKING)
          .setActivityTransition(ActivityTransition.ACTIVITY_TRANSITION_EXIT)
          .build()

List<ActivityTransition> transitions = new ArrayList<>();

transitions.add(
        new ActivityTransition.Builder()
          .setActivityType(DetectedActivity.IN_VEHICLE)
          .setActivityTransition(ActivityTransition.ACTIVITY_TRANSITION_ENTER)
          .build());

transitions.add(
        new ActivityTransition.Builder()
          .setActivityType(DetectedActivity.IN_VEHICLE)
          .setActivityTransition(ActivityTransition.ACTIVITY_TRANSITION_EXIT)
          .build());

transitions.add(
        new ActivityTransition.Builder()
          .setActivityType(DetectedActivity.WALKING)
          .setActivityTransition(ActivityTransition.ACTIVITY_TRANSITION_EXIT)
          .build());

建立 ActivityTransitionRequest 物件的方法是將 ActivityTransitions 清單傳遞至 ActivityTransitionRequest 類別，如以下範例所示：

val request = ActivityTransitionRequest(transitions)

ActivityTransitionRequest request = new ActivityTransitionRequest(transitions);

可以註冊活動轉換的最新狀態，方法是將 ActivityTransitionRequest 的執行個體及 PendingIntent 物件傳遞至 requestActivityTransitionUpdates() 方法。requestActivityTransitionUpdates() 方法會傳回一個 Task 物件，可以用來確認成功或失敗，如以下程式碼範例所示：

// myPendingIntent is the instance of PendingIntent where the app receives callbacks.
val task = ActivityRecognition.getClient(context)
        .requestActivityTransitionUpdates(request, myPendingIntent)

task.addOnSuccessListener {
    // Handle success
}

task.addOnFailureListener { e: Exception ->
    // Handle error
}

// myPendingIntent is the instance of PendingIntent where the app receives callbacks.
Task<Void> task = ActivityRecognition.getClient(context)
          .requestActivityTransitionUpdates(request, myPendingIntent);

task.addOnSuccessListener(
    new OnSuccessListener<Void>() {
        @Override
        public void onSuccess(Void result) {
            // Handle success
        }
    }
);

task.addOnFailureListener(
    new OnFailureListener() {
        @Override
        public void onFailure(Exception e) {
            // Handle error
        }
    }
);

成功註冊活動轉換的最新狀態後，應用程式會在註冊的 PendingIntent 中收到通知。

處理活動轉換事件

當要求的活動發生轉換，應用程式會收到 Intent 回呼。可以從 Intent 中擷取 ActivityTransitionResult 物件，其中包含一個 ActivityTransitionEvent 物件清單。事件會依時間先後順序排列，例如，如果應用程式要求 IN_VEHICLE 活動類型（位於 ACTIVITY_TRANSITION_ENTER 上）以及 ACTIVITY_TRANSITION_EXIT 轉換，則當使用者開始開車時，就會收到一個 ActivityTransitionEvent 物件，當使用者轉換至其他活動時，則會收到另一個。

若要實作一個回呼，可以建立一個 BroadcastReceiver 的子類別並實作 onReceive() 方法以取得活動轉換事件清單。詳情請參閱廣播的相關說明。以下範例說明如何實作 onReceive() 方法：

override fun onReceive(context: Context, intent: Intent) {
    if (ActivityTransitionResult.hasResult(intent)) {
        val result = ActivityTransitionResult.extractResult(intent)!!
        for (event in result.transitionEvents) {
            // chronological sequence of events....
        }
    }
}

@Override
public void onReceive(Context context, Intent intent) {
    if (ActivityTransitionResult.hasResult(intent)) {
        ActivityTransitionResult result = ActivityTransitionResult.extractResult(intent);
        for (ActivityTransitionEvent event : result.getTransitionEvents()) {
            // chronological sequence of events....
        }
    }
}

取消註冊活動轉換的狀態更新

您可以取消註冊活動轉換的狀態更新，方法是呼叫 ActivityRecognitionClient 的 removeActivityTransitionUpdates() 方法，接著將 PendingIntent 物件做為參數傳遞，如以下範例所示：

// myPendingIntent is the instance of PendingIntent where the app receives callbacks.
val task = ActivityRecognition.getClient(context)
        .removeActivityTransitionUpdates(myPendingIntent)

task.addOnSuccessListener {
    myPendingIntent.cancel()
}

task.addOnFailureListener { e: Exception ->
    Log.e("MYCOMPONENT", e.message)
}

// myPendingIntent is the instance of PendingIntent where the app receives callbacks.
Task<Void> task = ActivityRecognition.getClient(context)
        .removeActivityTransitionUpdates(myPendingIntent);

task.addOnSuccessListener(
    new OnSuccessListener<Void>() {
        @Override
        public void onSuccess(Void result) {
            myPendingIntent.cancel();
        }
    }
);

task.addOnFailureListener(
    new OnFailureListener() {
        @Override
        public void onFailure(Exception e) {
            Log.e("MYCOMPONENT", e.getMessage());
        }
    }
);