Flutter感知功能插件percept_flutter的使用

Flutter感知功能插件percept_flutter的使用

引言

本文档将详细介绍如何使用Percept Flutter SDK。

开始使用

1. 安装

1. 在你的项目 pubspec.yaml 文件中添加以下依赖项：

   dependencies:
       percept_flutter: ^5.0.2
   

2. 使用以下命令安装包：

   $ flutter pub get
   

3. 在你的Dart代码中导入该包以供使用：

   import 'package:percept_flutter/percept_flutter.dart';
   

2. 初始化Percept SDK

import 'package:percept_flutter/percept_flutter.dart';

class YourClassState extends State<YourClass> {
  Percept percept;

  @override
  void initState() {
    super.initState();
    percept = Percept(token);
  }
}

Percept 构造函数接受一些可选参数，如下所示：

int maxBatchSize = 100,
int maxDelayMins = 30,
int maxCacheSizeMb = 10,
int clearAfterDays = 7

注意： token 是与您的应用关联的Percept工作区令牌。

3. 设置用户

成功初始化SDK后，在登录时使用以下函数设置当前用户：

percept.setUser(
  userId: "userId",
  userProperties: {UserProperty.name: "TestUser"},
  additionalProperties: {"isVerifiedAccount": true}
);

4. 设置当前用户属性

使用 setCurrentUserProperties 方法来设置由 setUser 创建的用户配置文件上的属性：

// 首先调用此方法
await percept.setUser(userId: 'U1');

// 设置用户 `deviceToken` 和 `isPaidUser` 属性为true
percept.setCurrentUserProperties(
  userProperties: {UserProperty.deviceToken: "token"},
  additionalProperties: {"isPaidUser": true}
);

用户属性只能包含在 UserProperty 枚举中的键，如下所示：

注意： 要获取您的Firebase令牌，可以使用：

FirebaseMessaging.instance.getToken()

或

FirebaseMessaging.instance.onTokenRefresh.listen((token) => { });

5. 互动

与Firebase Messaging集成：以简化推送通知功能并准确监控其对归因的影响

1. 捕获当应用程序从终止状态通过交互推送通知启动会话时的事件。

// 获取导致应用程序从终止状态打开的任何消息。
RemoteMessage? initialMessage = await FirebaseMessaging.instance.getInitialMessage();
if (initialMessage != null) {
  _percept.trackPNTerminated(initialMessage.toMap());
}

1. 捕获当应用程序从后台状态通过交互推送通知恢复会话时的事件。

// 获取导致应用程序从终止状态打开的任何消息。
FirebaseMessaging.onMessageOpenedApp.listen(
  (message) => _percept.trackPNBackground(message.toMap()),
);

1. 捕获当应用程序处于前台状态并且接收到推送通知时的事件。

// 获取当应用程序处于前台时接收到的任何消息。
FirebaseMessaging.onMessage.listen(
  (message) => _percept.trackPNForeground(message.toMap()),
);

1. 通知SDK在终止状态下接收通知以便更好地归因

在调用 runApp 之前注册处理器。有关后台FCM消息处理的详细信息，请参阅 https://firebase.google.com/docs/cloud-messaging/flutter/receive#background_messages

import 'package:percept_flutter/constants.dart';
import 'package:percept_flutter/utils/comm_helpers.dart';

@pragma('vm:entry-point')
Future<void> bgMessageHandler(RemoteMessage message) async {
  CapturePerceptCommRequest(
    PerceptCommunicationState.received, 
    message.toMap(), 
    PERCEPT_TEST_KEY
  );
}

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp(options: DefaultOptions.currentPlatform);
  FirebaseMessaging.onBackgroundMessage(bgMessageHandler);
  runApp(MyApp());
}

此属性将在每个随后跟踪的事件中通过 pi_pn_attribution 属性进行跟踪。

除了 pi_pn_attribution 属性外，还会跟踪以下属性：

注意： 必须实现Firebase Messaging才能启用这些属性的支持。

6. 发送事件

您可以使用以下函数捕获事件。Percept会自动生成一个唯一的ID，并将其存储在本地存储或cookie中。

// 仅跟踪事件名称
percept.capture('Referral Banner Click');

// 跟踪带有属性的事件名称
percept.capture('Screen View', {'screenName': 'Homepage'});

// 跟踪已处理的错误
percept.captureError(error, stackTrace);

在初始化库后，Percept将自动跟踪一些默认属性。

7. 设置全局属性

设置全局属性，这些属性将与所有后续事件一起传递：

percept.setGlobalProperties({'global-property-key', 'value'});

8. 获取所有全局属性

获取所有全局属性：

percept.getGlobalProperties();

9. 清除

在注销时调用清除函数以删除所有与用户相关的数据：

percept.clear();

SDK自动跟踪的事件

SDK跟踪的属性

除了其他平台特定的设备信息外，还包括：

IOS:

Android:

处理实验

1. 启用实验

要启用实验跟踪，将 enableExperiment 选项设置为 true 在 initOptions 中。您还可以指定一个回调函数以在获取到实验数据时处理数据。

final initOptions = InitOptions(
  enableExperiment: true,
  experimentFetchedCb: (data) {
    final experimentData = data['experimentData'];
    final experimentUserType = data['experimentUserType'];
    final isExperimentDataResolved = data['isExperimentDataResolved'];

    if (isExperimentDataResolved) {
      print('Experiment data fetched: $experimentData');
    } else {
      print('Experiment data could not be resolved.');
    }
  },
  experimentRefetchIntervalMin: 10, // 每10分钟重新获取一次实验数据
);

Percept('Your Project Token', initOptions);

注意： experimentRefetchIntervalMin 选项设置了自动重新获取实验数据的时间间隔（分钟）。间隔必须至少为5分钟。如果提供了小于5的值，它将自动设置为5分钟，并记录警告。

2. 获取实验数据

您可以随时使用 getExperiment 方法获取实验数据。此方法返回一个Future，解析为指定实验的变体数据。

final experimentName = 'example-experiment';
final variant = await percept.getExperiment(experimentName);

if (variant) {
  print('User is in variant: $variant');
} else {
  print('No variant data available');
}

3. 重新获取实验数据

如果您设置了 experimentRefetchIntervalMs 选项，SDK将在指定的时间间隔内自动重新获取实验数据。您也可以使用 refetchExperiment 方法手动重新获取实验数据。

await percept.refetchExperiment();

4. 获取所有活动的实验

您可以使用 getAllActiveExperiments 方法获取所有活动的实验及其变体。

final activeExperiments = await percept.getAllActiveExperiments();
print('Active experiments:', activeExperiments);

5. 获取实验用户类型

您可以使用 getExperimentUserType 方法获取实验的用户类型。

final userType = await percept.getExperimentUserType();
print('Experiment user type:', userType);