Flutter事件追踪插件hightouch_events的使用

Flutter事件追踪插件hightouch_events的使用

介绍

hightouch_events 是一个轻量级的库，用于在 Flutter 应用程序中轻松添加事件追踪功能。它支持以下平台：

• Android
• iOS
• MacOS
• Web

某些目标插件可能不支持所有平台功能。有关更多详细信息，请参阅其各自的平台 SDK。

安装

要将 hightouch_events 添加到您的项目中，请运行以下命令：

flutter pub add hightouch_events

然后在 Dart 文件中导入：

import 'package:hightouch_events/client.dart';

权限

Android

在应用的 AndroidManifest.xml 文件中添加以下行：

<uses-permission android:name="android.permission.INTERNET"/>

使用

设置客户端

hightouch_events 提供了一个名为 createClient 的方法，可以用来创建 Hightouch 事件客户端。此中央客户端管理所有的跟踪事件。建议将其作为主应用程序状态类的属性添加。

示例代码：

const writeKey = 'WRITE_KEY'; // 替换为您的实际写入密钥
final analytics = createClient(Configuration(writeKey));

必须传递至少 writeKey。其他可选配置选项如下表所示：

客户端选项

客户端方法

跟踪事件 (Track)

track 方法用于记录用户执行的任何操作，以及描述该操作的任何属性。

方法签名：

Future track(String event: string, {Map<String, dynamic>? properties});

示例代码：

analytics.track("View Product", properties: {
  "productId": 123,
  "productName": "Striped trousers"
});

屏幕事件 (Screen)

screen 方法用于记录用户在移动应用中看到的屏幕，以及关于该屏幕的任何属性。

方法签名：

Future screen(String name: string, {Map<String, dynamic>? properties});

示例代码：

analytics.screen("ScreenName", properties: {
  "productSlug": "example-product-123",
});

对于自动屏幕跟踪的设置，请参见下文。

标识用户 (Identify)

identify 方法用于将用户与其行为绑定，并记录有关他们的特征。这包括唯一的用户 ID 和任何已知的可选特征，如电子邮件、姓名等。

方法签名：

Future identify({String? userId, UserTraits? userTraits});

示例代码：

analytics.identify(userId: "testUserId", userTraits: UserTraits(
  username: "MisterWhiskers",
  email: "hello@test.com",
  custom: {
    "plan": "premium"
  }
));

关联组 (Group)

group API 方法用于将个人用户与某个组（公司、组织、账户、项目、团队等）关联起来。

方法签名：

Future group(String groupId, {GroupTraits? groupTraits});

示例代码：

analytics.group("some-company", groupTraits: GroupTraits(
  name: 'Hightouch',
  custom: {
    "region": "UK"
  }
));

别名 (Alias)

alias 方法用于合并两个用户身份，有效地将两组用户数据连接为一组。

方法签名：

Future alias(String newUserId);

示例代码：

analytics.alias("user-123");

重置 (Reset)

reset 方法清除当前用户和组的库内部状态。这对于用户可以在不同时间段内以不同身份登录的应用程序非常有用。

方法签名：

void reset();

示例代码：

analytics.reset();

强制上传 (Flush)

默认情况下，分析数据将在 30 秒后或当 20 个事件累积时发送到 API，以先到者为准。这些值可以通过 flushAt 和 flushInterval 配置选项进行修改。您也可以手动触发刷新事件。

方法签名：

Future flush();

示例代码：

analytics.flush();

高级清理 ((Advanced) Cleanup)

如果您需要重新初始化客户端（即在同一生命周期中多次调用 createClient），则需要在旧客户端上使用此方法清除任何订阅和计时器。

示例代码：

var analytics = createClient(Configuration(writeKey));

analytics.cleanup();

analytics = createClient(Configuration(writeKey));

如果未执行此操作，旧客户端实例将继续存在并保留计时器，导致所有事件触发两次。

自动屏幕跟踪

通过每次导航动作发送 screen() 事件会很快变得乏味，因此您可能希望全局跟踪导航。为此，您需要将分析导航观察者添加到应用程序的导航观察者中。例如，如果您使用的是 MaterialApp 类，可以添加以下内容：

return MaterialApp(navigatorObservers: [
  ScreenObserver()
]);

插件 + 时间线架构

您可以完全控制事件在上传到 Hightouch 事件 API 之前如何被处理。

为了自定义事件创建后的处理方式，您可以在事件通过的时间线中创建并放置各种插件。这条时间线被称为时间线。

插件类型

插件可以有自己的原生代码（如仅适用于 iOS 的 hightouch_events_plugin_idfa）或封装底层库（如 hightouch_events_plugin_firebase，它在幕后使用 firebase_core 和 firebase_analytics）。

目标插件

Hightouch 作为内置的 DestinationPlugin 提供。您可以添加任意数量的其他目标插件，并将事件和数据上传到它们以及 Hightouch。

或者，如果您更喜欢，在设置客户端时可以传递 autoAddHightouchDestination = false。这将防止自动添加 HightouchDestination 插件。

添加插件

您可以在任何时候通过 add() 方法添加插件。

示例代码：

import 'package:hightouch_events/client.dart';
import 'package:hightouch_events/event.dart';
import 'package:hightouch_events/state.dart';
import 'package:hightouch_events_plugin_advertising_id/plugin_advertising_id.dart';
import 'package:hightouch_events_plugin_idfa/plugin_idfa.dart';
import 'package:hightouch_events_plugin_firebase/plugin_firebase.dart' show FirebaseDestination;

const writeKey = 'WRITE_KEY';

class _MyAppState extends State<MyApp> {
  final analytics = createClient(Configuration(writeKey));

  @override
  void initState() {
    super.initState();
    initPlatformState();

    analytics
        .addPlugin(FirebaseDestination(DefaultFirebaseOptions.currentPlatform));
    analytics.addPlugin(PluginAdvertisingId());
    analytics.addPlugin(PluginIdfa());
  }
}

编写自己的插件

插件通过扩展提供的插件类之一来实现。可用的插件类有：

• Plugin
• EventPlugin
• DestinationPlugin
• UtilityPlugin
• PlatformPlugin

任何插件都必须扩展其中一个类。

您可以通过覆盖基类的不同方法来自定义功能。例如，这是一个简单的 Logger 插件：

import 'dart:convert';

import 'package:hightouch_events/analytics.dart';
import 'package:hightouch_events/event.dart';
import 'package:hightouch_events/plugin.dart';
import 'package:hightouch_events/logger.dart';

class EventLogger extends DestinationPlugin {
  var logKind = LogFilterKind.debug;

  EventLogger() : super("event_logger");

  @override
  void configure(Analytics analytics) {
    pAnalytics = analytics;
  }

  @override
  Future<RawEvent?>? execute(RawEvent event) async {
    log("${event.type.toString().toUpperCase()} event${event is TrackEvent ? " (${event.event})" : ''} saved: \n${jsonEncode(event.toJson())}",
        kind: logKind);
    return event;
  }
}

由于它覆盖了 execute() 方法，此 Logger 将为通过时间线的每个事件调用 log。

支持的插件

以下是您可以使用的插件表，以满足您的跟踪需求：

使用刷新策略控制上传

为了更精细地控制事件何时上传，您可以使用 FlushPolicies。

刷新策略定义了决定何时刷新的策略，可以基于间隔、特定时间、收到一定数量的事件甚至收到特定事件。这为您提供了更大的灵活性来决定何时将事件发送到 Hightouch。

要在客户端配置中使用刷新策略，可以这样做：

import 'package:hightouch_events/flush_policies/count_flush_policy.dart';
import 'package:hightouch_events/flush_policies/timer_flush_policy.dart';

final analytics = createClient(Configuration(/*...*/, flushPolicies: [
  CountFlushPolicy(10),
  TimerFlushPolicy(100000)
]));

您可以同时设置多个策略。每当其中任何一个决定是时候刷新时，它将触发事件上传。其余策略将重置，以便在每次刷新后重新启动逻辑。

这意味着只有第一个达到 shouldFlush 的策略才能触发刷新。在上面的例子中，事件计数达到 5 或计时器达到 500 毫秒，先发生的将触发刷新。

我们有几个标准的刷新策略：

• CountFlushPolicy：事件数量达到一定数量时触发。
• TimerFlushPolicy：按毫秒间隔触发。
• StartupFlushPolicy：仅在客户端启动时触发。

添加或移除策略

刷新策略的主要优点之一是可以动态添加和移除策略。当您想要减少或增加刷新次数时，这非常强大。

例如，如果您检测到用户没有网络连接，您可以禁用刷新：

if (isConnected) {
  analytics.addFlushPolicy(policiesIfNetworkIsUp);
} else {
  analytics.removeFlushPolicy(policiesIfNetworkIsUp)
}

创建自己的刷新策略

您可以通过实现 FlushPolicy 接口或扩展 FlushPolicyBase 类来创建自定义刷新策略。FlushPolicyBase 已经创建并处理了 shouldFlush 值的重置。

FlushPolicy 只需要实现以下方法：

• onEvent(RawEvent event)：每次由客户端跟踪的事件都会调用此方法。

还可以选择性地实现以下方法：

• reset()：刷新触发后调用（无论是由您的策略、其他策略还是手动触发）。
• start()：在刷新策略启用并添加到客户端时执行。这是开始后台操作、异步调用、配置执行前的好地方。

它们还有一个 shouldFlush 布尔值。当此值设置为 true 时，客户端将尝试上传事件。每个策略应根据其自身逻辑将此值重置为 false，尽管在 reset 方法中这样做比较常见。

示例代码：

import 'package:hightouch_events/event.dart';
import 'package:hightouch_events/flush_policies/flush_policy.dart';

class FlushOnScreenEventsPolicy extends FlushPolicy {

  @override
  onEvent(RawEvent event) {
    // 仅在发生屏幕事件时刷新
    if (event is ScreenEvent) {
      this.shouldFlush = true;
    }
  }

  @override
  reset() {
    // 父类将重置 shouldFlush 值，以便下一个屏幕事件再次触发刷新
    // 但您也可以在另一个事件发生或超时时重置该值
    super.reset();
  }
}

自定义日志记录

默认情况下，所有日志记录都是通过标准的 Flutter 日志机制完成的。要自定义日志记录，您可以构建自己的日志记录器，该日志记录器必须实现 LogTarget 混合类。例如：

import 'package:hightouch_events/logger.dart';

void customDebugLog(String msg) {
  // ...
}

void customWarningLog(String msg) {
  // ...
}

void customErrorLog(String msg) {
  // ...
}

class CustomLogger with LogTarget {
  @override
  void parseLog(LogMessage log) {
    switch (log.kind) {
      case LogFilterKind.debug:
        customDebugLog("Hightouch: ${log.message}");
        break;
      case LogFilterKind.warning:
        customWarningLog("Hightouch: ${log.message}");
        break;
      case LogFilterKind.error:
        customErrorLog("Hightouch: ${log.message}");
        break;
    }
  }
}

// 设置默认日志记录器为 CustomLogger
LogFactory.logger = CustomLogger();

错误处理

您可以通过 errorHandler 选项处理分析客户端错误。

错误处理程序配置接收一个函数，每当分析客户端发生错误时都会调用此函数。它将接收到一个扩展自 errors.dart 中错误的异常。

您可以使用此错误处理来在出现问题时触发客户端的不同行为。例如，如果客户端受到速率限制，您可以使用错误处理程序将刷新策略更改为不那么激进：

import 'package:hightouch_events/errors.dart';

//...

final flushPolicies = [CountFlushPolicy(5), TimerFlushPolicy(500)];

void errorHandler(Exception error) {
  if (error is NetworkServerLimited) {
    // 删除所有刷新策略
    analytics.removeFlushPolicy(analytics.getFlushPolicies());
    // 添加不太持久的刷新策略
    analytics.addFlushPolicy([
      CountFlushPolicy(100),
      TimerFlushPolicy(5000)
    ]);
  }
}

final analytics = createClient(Configuration(writeKey),
  errorHandler: errorHandler,
  flushPolicies: flushPolicies);

插件报告错误

插件也可以通过使用分析客户端的 <code>.error</code> 函数向处理器报告错误。我们建议使用 <code>PluginError</code> 保持一致性，并附上 <code>innerError</code> 实际异常：

import 'package:hightouch_events/errors.dart';

//...

try {
  distinctId = await mixpanel.getDistinctId();
} catch (e) {
  analytics.error(
    PluginError('Error: Mixpanel error calling getDistinctId', e)
  );
}