1.1 集成 Flutter 插件 #

在 Flutter 项目的 pubspec.yaml 中添加 rangers_applog_flutter_plugin 依赖

dependencies:
  ......
  rangers_applog_flutter_plugin: 1.5.0

并安装插件

flutter packages get

1.2 集成 iOS 原生端依赖 #

1.2.1 集成iOS SDK #

如您使用CocoaPods远程集成，请参考iOS SDK集成1.1～1.4小节；
如您需手动引入集成，请参考1.5小节。

1.2.2 配置Scheme(可选) #

如需使用实时埋点检测（https://www.volcengine.com/docs/6285/66054）功能，请参考 iOS SDK集成 第3节，配置Scheme。

1.3 集成 Android 原生端依赖 #

1.3.1 集成Android SDK #

如您使用远程集成，请参考Android SDK集成 1.1～1.5小节；
如您需手动引入集成，请参考1.7小节。

1.3.2 配置Scheme(可选) #

如需使用实时埋点检测（https://www.volcengine.com/docs/6285/66054）功能，请参考Android SDK集成 第3节，配置Scheme。

1.4 集成 鸿蒙 原生端依赖（版本大于1.4.1） #

请移步文档：Flutter SDK 鸿蒙接入

说明
SDK会在初始化的时候就采集用户信息，请确保您采集用户信息之前已经获得用户授权。
合规建议操作如下：
用户授权后再进行SDK的初始化，取得用户授权前所有的信息都不会采集，预置事件也不会被采集。

2.1 获取appid #

在开始集成前，首先需要在集团中拥有一个应用，进行 SDK 集成前，您需要获取对应应用的 appid 信息。

• SaaS-云原生场景下，您可以在「项目中心」->「项目管理」->「项目详情」-> 接入应用的「详情」->「应用 ID」中可查看您的 appid，详情请参见项目管理。
  
• SaaS-非云原生场景下，您可以在「应用列表」-> 接入应用的「详情」->「应用 ID」中可查看您的 appid，详情请参见应用列表。
  

2.2 获取数据上送地址 #

进行数据接入上报时，您需要根据当前的环境类型和端类型确认您的数据上报地址，如果上报地址设置错误，后续会导致您无法查询到上报的数据。

SaaS-云原生 & SaaS-非云原生 #

私有化环境 #

私有化部署场景下，您需要获取部署私有化环境时，自行规划配置的数据上送地址。如您不清楚此地址，请联系您的项目经理或客户成功经理。

2.3 初始化SDK #

2.3.1 SaaS-云原生版本 #

如您使用SaaS-云原生，请参照如下代码初始化SDK。

import 'package:rangers_applog_flutter_plugin/rangers_applog_flutter_plugin.dart';

// 初始化SDK
String appId = '{{APPID}}'; // 参考2.1节获取
String channel = '{{CHANNEL}}'; // 填写App下载/分发渠道，例如iOS一般是'App Store'
bool enableEncrypt = true; // 加密开关
bool enableDebugLog = false; // 原生端日志开关

// 设置数据上送地址
// 国内-华北
String? host = 'https://gator.volces.com';
// 国内-华南
// String? host = 'https://gator.uba.cn-guangzhou.volces.com';
// 海外-柔佛
// String? host = 'https://gator.uba.ap-southeast-1.volces.com';

RangersApplogFlutterPlugin.addInitParams({
    'service_vendor': 'private', // 固定值 private
});

RangersApplogFlutterPlugin.initRangersAppLog(appId, channel, enableAB, enableEncrypt, enableDebugLog, host);

2.3.2 私有化版本 #

如您使用私有化部署版本，请参照如下代码初始化SDK。

import 'package:rangers_applog_flutter_plugin/rangers_applog_flutter_plugin.dart';

// 初始化SDK
String appId = '{{APPID}}'; // 参考2.1节获取
String channel = '{{CHANNEL}}'; // 填写App下载/分发渠道，例如iOS一般是'App Store'
bool enableEncrypt = true; // 加密开关
bool enableDebugLog = false; // 原生端日志开关

// 设置私有化部署数据上送地址，参考2.2节获取，{{REPORT_URL}} 例如 https://yourdomain.com，注意域名后不要加“/”
String? host = '{{REPORT_URL}}';

RangersApplogFlutterPlugin.addInitParams({
    'service_vendor': 'private', // 固定值 private
});

RangersApplogFlutterPlugin.initRangersAppLog(appId, channel, enableAB, enableEncrypt, enableDebugLog, host);

2.3.3 SaaS-非云原生版本 #

import 'package:rangers_applog_flutter_plugin/rangers_applog_flutter_plugin.dart';

// 初始化SDK
String appId = '{{APPID}}'; // 参考2.1节获取
String channel = '{{CHANNEL}}'; // 填写App下载/分发渠道，例如iOS一般是'App Store'
bool enableEncrypt = true; // 加密开关
bool enableDebugLog = false; // 原生端日志开关
// 非云原生环境使用默认的数据上报地址
String? host = '';

RangersApplogFlutterPlugin.addInitParams({
    // 国内环境
    'service_vendor': '',
    // 海外byteplus
    // 'service_vendor': 'sg',
});

RangersApplogFlutterPlugin.initRangersAppLog(appId, channel, enableAB, enableEncrypt, enableDebugLog, host);

2.3.4 非核心初始化参数（可选）（版本>=1.4.1） #

// 目前支持region/autoStart
Map<String, dynamic> initParams = {
  'region': 'cn',//对应客户端上报的app_region字段，用于需要自定义app_region的情况
  'autoStart': true,//false-初始化不start,true-初始化即start，默认为true(用于需要将init和start分开的场景)
};
RangersApplogFlutterPlugin.addInitParams(initParams);

RangersApplogFlutterPlugin.initRangersAppLog(appId, channel, enableAB, enableEncrypt, enableDebugLog, host);

3.1 登录态变化调用 #

3.1.1 账户登录 #

如您的产品中有账户体系，请在用户登录后立即设置uuid，以保证用户登录前后口径一致性。

import 'package:rangers_applog_flutter_plugin/rangers_applog_flutter_plugin.dart';

// 登录时设置您账号体系的ID, 并保证其唯一性
RangersApplogFlutterPlugin.setUserUniqueId('{{USER_UNIQUE_ID}}');

3.1.2 账户登出 #

在账户登出时调用。

import 'package:rangers_applog_flutter_plugin/rangers_applog_flutter_plugin.dart';

// 登出时设置uuid为null
RangersApplogFlutterPlugin.setUserUniqueId(null);

3.2 设置用户属性 #

3.2.1 profileSet #

设置用户属性，存在则覆盖，不存在则创建。

import 'package:rangers_applog_flutter_plugin/rangers_applog_flutter_plugin.dart';

// 示例：设置用户属性，属性名为key，属性值为value
RangersApplogFlutterPlugin.profileSet({"key": "value"});

3.2.2 profileSetOnce #

设置用户属性，存在则不设置，不存在则创建，适合首次相关的用户属性，比如首次访问时间等。

import 'package:rangers_applog_flutter_plugin/rangers_applog_flutter_plugin.dart';

// 示例：设置用户属性，属性名为key_once，属性值为value_once
RangersApplogFlutterPlugin.profileSetOnce({"key_once": "value_once"});

3.2.3 profileIncrement #

设置数值类型的属性，可进行累加。

import 'package:rangers_applog_flutter_plugin/rangers_applog_flutter_plugin.dart';

// 示例：设置用户属性，属性名为key，属性值为1
RangersApplogFlutterPlugin.profileIncrement({"key": 1});

3.2.4 profileAppend #

设置List类型的用户属性，可持续向List内添加。

import 'package:rangers_applog_flutter_plugin/rangers_applog_flutter_plugin.dart';

// 示例：设置用户属性，属性名为key，原本已有属性值，现添加属性值为value_append
RangersApplogFlutterPlugin.profileAppend({"key": "value_append"});

3.2.5 profileUnset #

删除用户的属性。

import 'package:rangers_applog_flutter_plugin/rangers_applog_flutter_plugin.dart';

// 例：删除用户属性，属性名为key
RangersApplogFlutterPlugin.profileUnset("key");

4.1 上报代码埋点 #

用户行为日志采用事件event+属性params的形式，事件一般对应多个属性，也可以仅有事件没有属性。
仅上报事件的代码埋点，示例如下：

import 'package:rangers_applog_flutter_plugin/rangers_applog_flutter_plugin.dart';

// 示例：上报事件event，该事件不包含属性
RangersApplogFlutterPlugin.onEventV3("event");

上报事件和对应属性的代码埋点，示例如下：

import 'package:rangers_applog_flutter_plugin/rangers_applog_flutter_plugin.dart';

// 示例：上报事件event，该事件包含两个属性
//      一个string类型的属性，属性名为key_string，属性值为value_string
//      一个int类型的属性，属性名为key_int，属性值为10
RangersApplogFlutterPlugin.onEventV3("event", {
    "key_string": "value_string",
    "key_int": 10
});

4.2 事件公共属性 #

如需在每个事件中都包括某属性，可通过公共属性设置，无需在每个事件中重复设置。公共属性只需设置一次，即可包括在所有代码埋点事件中。

4.2.1 设置公共属性 #

关于自定义 “公共属性” 请注意：

1. 上报机制是随着每一次日志发送进行提交，默认的日志发送频率是1分钟，所以如果在一分钟内连续修改自定义公共属性，按照日志发送前的最后一次修改为准 2. 不推荐高频次修改，如每秒修改一次

import 'package:rangers_applog_flutter_plugin/rangers_applog_flutter_plugin.dart';

// 设置自定义的公共属性，属性名为key_public，属性值为value_public
RangersApplogFlutterPlugin.setHeaderInfo({
    "key_public": "value_public"
});

4.2.2 移除公共属性 #

import 'package:rangers_applog_flutter_plugin/rangers_applog_flutter_plugin.dart';

// 示例：移除属性名为key_public的公共属性
RangersApplogFlutterPlugin.removeHeaderInfo("key_public");

5.1 获取平台ID与通知 #

请注意 deviceid 是火山生成的 id，不是原始设备 id。

import 'package:rangers_applog_flutter_plugin/rangers_applog_flutter_plugin.dart';

// 请在初始化完成的3秒后开始获取，否则可能返回为空
String did = await RangersApplogFlutterPlugin.getDeviceId();

Flutter是跨平台的 ui 框架，埋点验证仅支持原生端埋点验证。
Flutter端埋点验证思路可参见通用埋点验证文档：通用埋点验证操作指引。