應用程式可能必須經過特別設計,以識別使用者何時開始或停止特定活動,例如步行、騎單車或開車。舉例來說,當使用者開始開車時,里程追蹤應用程式可以開始追蹤里程數,或者訊息應用程式可以將所有對話靜音,直到使用者停止駕駛為止。
動作辨識轉場 API 可用來偵測使用者活動的變化。應用程式會訂閱需要追蹤的活動轉換事件,而 API 只會在需要時才會向應用程式發出通知。本頁面介紹如何使用 Activity Recognition Transition API (簡稱為 Transition API)。
設定專案
如要在應用程式中使用 Transition API,必須宣告 Google 位置和動作辨識 API 12.0.0 以上版本的依附元件,並在應用程式資訊清單中指定 com.google.android.gms.permission.ACTIVITY_RECOGNITION 權限。
- 如要宣告 API 的依附元件,請在 Google Maven 存放區中新增參考資料,接著將
com.google.android.gms:play-services-location:12.0.0的實作項目新增至應用程式build.gradle檔案的依附元件部分。詳情請參閱「設定 Google Play 服務」一文。 如要指定
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 支援下列活動: ACTIVITY_TRANSITION_ENTER或ACTIVITY_TRANSITION_EXIT的轉場類型。詳情請參閱ActivityTransition類別。
以下程式碼顯示如何建立 ActivityTransition 物件清單:
Kotlin
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()
Java
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 類別,如以下範例所示:
Kotlin
val request = ActivityTransitionRequest(transitions)
Java
ActivityTransitionRequest request = new ActivityTransitionRequest(transitions);
您可以註冊活動轉換的最新狀態,方法是將 ActivityTransitionRequest 的執行個體及 PendingIntent 物件傳遞至 requestActivityTransitionUpdates() 方法。requestActivityTransitionUpdates() 方法會傳回 Task 物件,可用來確認成功或失敗,如以下程式碼範例所示:
Kotlin
// 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
}
Java
// 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 方法:
Kotlin
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....
}
}
}
Java
@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 物件做為參數傳遞,如以下範例所示:
Kotlin
// 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)
}
Java
// 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());
}
}
);
其他資源
如要進一步瞭解使用者動作辨識 API 的使用方式,請參閱下列資料:
範例
展示使用者動作辨識最佳做法的範例。