检测用户何时开始或结束活动

您可能需要设计您的应用程序，以识别用户何时开始或停止特定活动，例如步行、骑自行车或驾驶。例如，里程跟踪应用程序可以在用户开始驾驶时开始跟踪里程，或者消息应用程序可以在用户停止驾驶之前使所有对话静音。

活动识别转换 API 可用于检测用户活动的变化。您的应用程序订阅感兴趣的活动的转换，API 仅在需要时通知您的应用程序。此页面展示了如何使用活动识别转换 API（简称为转换 API）。

设置您的项目

要在您的应用程序中使用转换 API，您必须声明对 **Google 位置和活动识别** API 版本 12.0.0 或更高版本的依赖项，并在应用程序清单中指定 com.google.android.gms.permission.ACTIVITY_RECOGNITION 权限。

1. 要声明对 API 的依赖项，请将对 Google maven 存储库的引用添加到您的应用程序 build.gradle 文件的依赖项部分的实现条目中，例如 com.google.android.gms:play-services-location:12.0.0。有关更多信息，请参阅 设置 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 类表示。转换 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());

您可以通过将 ActivityTransitions 列表传递给 ActivityTransitionRequest 类来创建一个 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 回调。一个 ActivityTransitionResult 对象可以从 Intent 中提取，其中包含一个 ActivityTransitionEvent 对象列表。这些事件按时间顺序排列，例如，如果一个应用在 ACTIVITY_TRANSITION_ENTER 和 ACTIVITY_TRANSITION_EXIT 转换上请求 IN_VEHICLE 活动类型，那么当用户开始驾驶时会收到一个 ActivityTransitionEvent 对象，当用户转换到任何其他活动时会收到另一个 ActivityTransitionEvent 对象。

您可以通过创建一个 BroadcastReceiver 的子类并实现 onReceive() 方法来获取活动转换事件列表，从而实现您的回调。有关更多信息，请参阅 Broadcasts。以下示例展示了如何实现 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....
        }
    }
}

取消注册活动转换更新

您可以通过调用 removeActivityTransitionUpdates() 方法（ActivityRecognitionClient）并将您的 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());
        }
    }
);

其他资源

要详细了解用户活动识别 API 的使用方法，请查看以下资料

示例

示例演示了用户活动识别的最佳实践。