Flutter行程分析插件flutter_drivekit_trip_analysis的使用

安装

要使用此插件，请在项目中运行以下命令：

flutter pub add drivekit_trip_analysis

现在，您可以导入 package:flutter_drivekit_trip_analysis/flutter_drivekit_trip_analysis.dart 并在Dart代码中使用 DriveKitTripAnalysis。

使用

您需要安装 flutter_drivekit_core 插件，并按照说明指定API密钥和用户标识符。然后，您可以开始使用DriveKit行程分析插件。例如，您可以激活自动启动模式，如下所示：

await DriveKitTripAnalysis.instance.activateAutoStart(true);

请参阅DriveKit行程分析文档以获取更多关于我们提供的功能的信息。

手动初始化

如果您已禁用DriveKit自动初始化：

Android项目

在您的 MainApplication 类中调用 DriveKitTripAnalysis 类的 initialize 方法。

// MainApplication.kt

// …
override fun onCreate() {
    super.onCreate()
    DriveKit.initialize()

    val tripNotification: TripNotification = ...
    DriveKitTripAnalysis.initialize(tripNotification)

    // 初始化其他您使用的DriveKit模块：
    // DriveKitDriverData.initialize()
    // 等等。
}

iOS项目

在您的 AppDelegate 中调用 initialize 方法。

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    DriveKit.shared.initialize()
    DriveKitTripAnalysis.shared.initialize(appLaunchOptions: launchOptions)
    (…)
}

API

isAutoStartActivated

Future<bool> isAutoStartActivated();

此方法返回 true 如果启用了自动启动。

final isAutoStartActivated = await DriveKitTripAnalysis.instance.isAutoStartActivated();

activateAutoStart

Future<void> activateAutoStart(bool activate);

自动模式检测车辆移动并触发行程分析，无需驾驶员干预，同时应用程序处于后台。分析会在行程结束时自动停止。

此功能推荐用于避免驾驶时分散注意力和处理手机。自动模式经过优化，以限制电池消耗。

默认情况下，自动启动是禁用的。要启用自动行程检测模式，请调用以下方法：

await DriveKitTripAnalysis.instance.activateAutoStart(true);

要禁用自动行程检测，请将参数设置为 false：

await DriveKitTripAnalysis.instance.activateAutoStart(false);

⚠️ 如果在禁用自动行程检测时行程正在进行，则行程不会被取消。如果要取消行程，还应调用 cancelTrip 方法。

startTrip

Future<void> startTrip();

您可以调用以下方法开始行程：

await DriveKitTripAnalysis.instance.startTrip();

ℹ️ 如果行程已经开始了，调用此方法将不起作用。

stopTrip

Future<void> stopTrip();

您可以调用以下方法停止行程。行程会立即停止：

await DriveKitTripAnalysis.instance.stopTrip();

ℓ 如果车辆停止时间超过配置的超时时间，行程将自动停止。

ℓ 如果没有进行中的行程，调用此方法将不起作用。

cancelTrip

Future<void> cancelTrip();

如果要取消行程，可以调用此方法：

await DriveKitTripAnalysis.instance.cancelTrip();

isTripRunning

Future<bool> isTripRunning();

此方法返回 false 如果SDK处于 INACTIVE 状态且没有行程正在运行。

final isTripRunning = await DriveKitTripAnalysis.instance.isTripRunning();

setCustomTimeOut

Future<void> setStopTimeOut(int timeOut)

一个正在分析的行程会在一段时间的不活动后自动停止（从车辆停止时开始）。DriveQuant SDK允许设置行程结束的时间。

默认情况下，行程分析在240秒后停止。您可以根据需要调整该值，并选择120到480秒之间的任何整数值。调用以下方法：

await DriveKitTripAnalysis.instance.setStopTimeOut(123);

ℓ 如果设置了大于 480 的值，该值将被强制设置为 480。

ℓ 如果设置了小于 120 的值，该值将被强制设置为 120。

addTripListener

TripListener 接口提供了关于行程分析有用的信息和事件。

例如，您可以使用以下方法来了解行程分析何时开始、完成、取消、何时检测到碰撞等：

void addTripListener(TripListener listener);

TripListener 接口包含多个需要实现的方法：

有关所有可能值的更多信息，请参阅本地文档：Android / iOS

removeTripListener

您可以使用以下方法移除特定的 TripListener：

void removeTripListener(TripListener listener);

removeAllTripListeners

您可以使用以下方法移除所有注册的 TripListener：

void removeAllTripListeners();

isCrashDetectionActivated

Future<bool> isCrashDetectionActivated();

此方法返回 true 如果启用了碰撞检测。

final isCrashDetectionActivated = await DriveKitTripAnalysis.instance.isCrashDetectionActivated();

activateCrashDetection

碰撞检测功能包括在DriveKit行程分析组件中，能够收集和分析智能手机传感器数据，自动检测汽车事故的发生。

了解更多功能详情：iOS / Android

DriveKitTripAnalysis有一个输入参数可用于启用或禁用该功能：

Future<void> activateCrashDetection(bool activate);

要启用碰撞检测，请将参数设为 true：

await DriveKitTripAnalysis.instance.activateCrashDetection(true);

要禁用碰撞检测，请将参数设为 false：

await DriveKitTripAnalysis.instance.activateCrashDetection(false);

isMonitoringPotentialTripStart

Future<bool> isMonitoringPotentialTripStart();

使用以下命令检查功能是否已激活：

final isMonitoringPotentialTripStart = await DriveKitTripAnalysis.instance.isMonitoringPotentialTripStart();

setMonitorPotentialTripStart

Future<void> setMonitorPotentialTripStart(bool activate);

DriveKit的自动启动模式会检测行程并立即开始记录。这种操作模式可能并不适用于所有用例。

您的应用可能需要其他信息或业务逻辑才能启用行程记录。例如，可能需要检查：

• 是否有连接设备靠近智能手机。
• 该行程记录是否在给定的时间段内可接受。

在这种情况下，您可能希望订阅那些指示行程可能开始的事件，但不一定启动GPS传感器和行程分析。

这就是为什么DriveKit允许您订阅那些指示行程可能开始的触发事件。

了解更多功能详情：iOS / Android

默认情况下，该配置是禁用的。调用以下方法将参数设为 true 来启用它。

await DriveKitTripAnalysis.instance.setMonitorPotentialTripStart(true);

要禁用该功能，请将参数设为 false：

await DriveKitTripAnalysis.instance.setMonitorPotentialTripStart(false);

setVehicle

Future<void> setVehicle(Vehicle vehicle);

为了获得更精确的驾驶行为分析，建议配置驾驶员所使用的车辆。通过调用以下方法可以做到这一点：

await DriveKitTripAnalysis.instance.setVehicle(
  const Vehicle(
    carTypeIndex: 2,
    carEngineIndex: 2,
    carPower: 200,
    carMass: 1500,
    carGearboxIndex: 3,
    carConsumption: 6.5,
    carAutoGearboxNumber: 1,
    engineDisplacement: 1500,
    carPassengers: 2,
    length: 4.7,
    width: 1.9,
    height: 1.5,
    engineCylinderNb: 6,
    driveWheels: 1,
  ),
);

车辆参数的详细描述见这里。

ℓ 如果未配置车辆，将使用默认车辆，其参数如下：

carTypeIndex = 1

carEngineIndex = 1

carPower = 150

carMass = 1400

carGearboxIndex = 2

carConsumption = 4.5

engineDisplacement = 1200

frontTireSize = “205/55/16”

rearTireSize = “205/55/16”

length = 4.5

width = 1.8

height = 1.45

engineCylinderNb = 4

driveWheels = 0

getTripMetadata

Future<Map<String, String>?> getTripMetadata()

要获取配置的元数据副本，请调用以下方法：

final tripMetadata = await DriveKitTripAnalysis.instance.getTripMetadata();

ℓ 对返回对象的任何修改都不会影响与行程一起发送的元数据。

setTripMetadata

Future<void> setTripMetadata(Map<String, String>? metadata)

可以为行程添加一些元数据。

const tripMetadata = {
  'key1': 'value1',
  'key2': 'value2',
};
await DriveKitTripAnalysis.instance.setTripMetadata(tripMetadata);

元数据必须表示为键/值对的对象，其中键和值都是字符串类型。 可以在行程结束前的任何时候设置元数据。

ℓ 如果发送了元数据，它也会添加到推送数据请求的metaData字段中。

updateTripMetadata

Future<void> updateTripMetadata(String key, String? value)

可以更新特定键的元数据值。

await DriveKitTripAnalysis.instance.updateTripMetadata('key', 'newValue');

deleteTripMetadata

Future<void> deleteTripMetadata(String key)

可以删除特定键的元数据值。

await DriveKitTripAnalysis.instance.deleteTripMetadata('key');

deleteAllTripMetadata

Future<void> deleteAllTripMetadata()

可以删除所有行程元数据。

await DriveKitTripAnalysis.instance.deleteAllTripMetadata();

getCurrentTripInfo

Future<CurrentTripInfo?> getCurrentTripInfo()

当行程分析开始时，您可能需要一些关于它的信息，如触发行程记录的 StartMode、本地唯一标识符等。

await DriveKitTripAnalysis.instance.getCurrentTripInfo();

如果行程没有运行，该方法将返回 null。否则，返回以下数据：

getLastTripLocation

Future<LastTripLocation?> getLastTripLocation()

此函数返回用户最后一次行程的结束位置。

位置由GPS坐标（纬度和经度）、行程结束日期以及GPS读数的精度指标定义。

您可以使用行程结束时的坐标用于多种目的，例如：

• 帮助用户找到他们的车辆。
• 通知客户用户已到达特定目的地。
• 创建地理围栏以定位车辆。

ℓ 最后一次行程是指DriveKit SDK记录的最后行程，无论使用何种交通工具。

await DriveKitTripAnalysis.instance.getLastTripLocation();

如果用户未认证、未进行行程或者没有有效行程，该方法可能会返回 null。否则，返回以下数据：

AccuracyLevel

示例代码

import 'package:flutter/material.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  [@override](/user/override)
  Widget build(BuildContext context) {
    return const MaterialApp(home: HomePage());
  }
}

class HomePage extends StatefulWidget {
  const HomePage({super.key});

  [@override](/user/override)
  State<HomePage> createState() => _HomePageState();
}

class _HomePageState extends State<HomePage> {
  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('DriveKitTripAnalysis Example')),
      body: const Column(
        children: [
          Text('请参考主flutter示例SDK'),
          Text(
            'https://github.com/DriveQuantPublic/flutter-drivekit/tree/main/example',
          ),
        ],
      ),
    );
  }
}