Flutter数据转换与实验室功能插件convertlabsdk的使用

前言

本文档提供了 Flutter 数据转换与实验室功能插件 convertlabsdk 的使用指南。通过此插件，开发者可以在 Flutter 应用中轻松实现数据采集、客户身份管理以及事件跟踪等功能。

1. 使用说明

本文档适用于具备一定 Flutter 开发能力的用户。以下是插件的基本要求：

• 插件版本：convertlabsdk:v1.0.9
• Flutter 版本要求：Flutter >=2.12.0 <3.0.0

2. SDK 导入

2.1 在 pubspec.yaml 中添加 SDK

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

dependencies:
   convertlabsdk:^1.0.9

2.2 导入包

在 Dart 文件中导入插件包：

import 'package:convertlabsdk/convertlabsdk.dart';

3. 初始化

在应用启动时，需要对插件进行初始化。初始化只需执行一次。

3.1 初始化插件

void main() {
  // 初始化选项
  var options = ConvertLabOptions(
      trackUrl: 'https://your-track-url.com/cbe/track?tid=1234567890', // 替换为实际的追踪 URL
      appId: 'your-app-id', // 替换为实际的 App ID
      appName: 'YourAppName'); // 替换为应用名称

  // 是否自动记录进入、离开视图事件
  options.autoTrackOpenAppEvent = true;

  // 是否打印日志
  options.enableDebugLogging = true;

  // 数据上传时间间隔（单位：秒）
  options.flushInterval = 30;

  // 禁用采集项
  options.disableCollect = [
    ConvertLabOptions.COLLECT_ANDROID_ID,
    ConvertLabOptions.COLLECT_IDFA,
    ConvertLabOptions.COLLECT_LOCATION,
    ConvertLabOptions.COLLECT_MAC
  ];

  // 初始化插件
  ConvertLabClient.getInstance.init(options).then((value) => null);

  runApp(MyApp());
}

4. 客户身份管理

4.1 设置客户身份

ConvertLabClient.getInstance.setIdentity("身份证类型", "身份证号码").then((value) => null);

4.2 获取当前客户身份

ConvertLabClient.getInstance.currentIdentity().then((result) {
  print("当前客户身份: $result");
});

4.3 清除客户身份

ConvertLabClient.getInstance.clearIdentity().then((result) {
  print("清除后的客户身份: $result");
});

5. 跟踪客户事件

5.1 跟踪自定义客户事件

// 跟踪带有自定义属性的事件
Map<String, dynamic> customProperties = {'key1': 'value1', 'key2': 'value2'};
ConvertLabClient.getInstance.trackMap('custom-event-id', customProperties);

// 跟踪不带属性的事件
ConvertLabClient.getInstance.track('simple-event-id');

5.2 跟踪进入、离开视图事件

// 跟踪进入视图事件
ConvertLabClient.getInstance.trackOpenView('HomePage');

// 跟踪离开视图事件
ConvertLabClient.getInstance.trackExitView('HomePage');

5.3 跟踪通知推送相关事件

5.3.1 跟踪 JPush 推送相关事件

// 设置 JPush 推送相关参数
ConvertLabClient.getInstance.onJPushReceiveRegisterId('app-key', 'registration-id');

// 监听 JPush 消息
Map<String, dynamic> jpushMessage = {'key': 'value'};
ConvertLabClient.getInstance.onJPushReceiveMessageData(jpushMessage);
ConvertLabClient.getInstance.trackReceiveJPushMessage(jpushMessage);

5.3.2 跟踪 GeTui 推送相关事件

// 设置 GeTui 推送相关参数
ConvertLabClient.getInstance.onGeTuiReceiveClientId('app-key', 'client-id');

// 监听 GeTui 消息
Map<String, dynamic> geTuiMessage = {'key': 'value'};
ConvertLabClient.getInstance.onGeTuiReceiveMessageData('task-id', 'message-id', geTuiMessage);
ConvertLabClient.getInstance.trackReceiveGeTuiPayloadData(geTuiMessage);

6. 设置全局参数

可以通过 push 方法设置全局参数，这些参数会在后续的事件跟踪中自动传递。

Map<String, dynamic> globalParams = {'global-key': 'global-value'};
ConvertLabClient.getInstance.onGlobalParamsPush(globalParams);

7. 混合开发

7.1 SDK 导入

Flutter 插件本身内置了 Android 和 iOS 的原生 SDK。在 Android 中可以直接调用原生方法，而在 iOS 中需要引入头文件。

7.2 初始化

如果应用是混合开发，初始化只需要在原生端完成一次。

示例代码

以下是一个完整的示例代码，展示如何在 Flutter 中使用 convertlabsdk 插件。

import 'package:flutter/material.dart';
import 'package:convertlabsdk/convertlabsdk.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();

  // 初始化插件
  var options = ConvertLabOptions(
      trackUrl: 'https://your-track-url.com/cbe/track?tid=1234567890',
      appId: 'your-app-id',
      appName: 'FlutterDemo');

  options.autoTrackOpenAppEvent = true;
  options.enableDebugLogging = true;
  options.flushInterval = 40;

  options.disableCollect = [
    ConvertLabOptions.COLLECT_ANDROID_ID,
    ConvertLabOptions.COLLECT_IDFA,
    ConvertLabOptions.COLLECT_LOCATION,
    ConvertLabOptions.COLLECT_MAC
  ];

  ConvertLabClient.getInstance.init(options).then((value) => null);

  // 设置客户身份
  ConvertLabClient.getInstance.setIdentity("身份证", "51028xxxxxxxxxxx299");

  // 跟踪自定义事件
  Map<String, dynamic> customProperties = {'key': 'value'};
  ConvertLabClient.getInstance.trackMap('custom-event-id', customProperties);

  // 跟踪通知推送事件
  ConvertLabClient.getInstance.onJPushReceiveRegisterId('app-key', 'registration-id');
  ConvertLabClient.getInstance.onJPushReceiveMessageData({'key': 'value'});

  // 设置全局参数
  Map<String, dynamic> globalParams = {'global-key': 'global-value'};
  ConvertLabClient.getInstance.onGlobalParamsPush(globalParams);

  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('ConvertLab SDK Demo')),
        body: Center(child: Text('Flutter ConvertLab SDK Example')),
      ),
    );
  }
}