手动开始start（初始化与start分开）

默认情况下，如下面初始化代码所示，SDK 会自动start。

import 'package:rangers_applog_flutter_plugin/rangers_applog_flutter_plugin.dart';

// 初始化SDK
String appId = '{{APPID}}'; // 替换成自己的
String channel = '{{CHANNEL}}'; // 填写App下载/分发渠道，例如iOS一般是'App Store'
bool enableEncrypt = true; // 加密开关
bool enableDebugLog = false; // 原生端日志开关
bool enableAB = false; // AB实验开关

// 设置数据上送地址，假设国内-华北
String? host = 'https://gator.volces.com';

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

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

如果需要初始化和start分开，需要明确设置autoStart为false告知SDK只初始化，等待后续调用start

import 'package:rangers_applog_flutter_plugin/rangers_applog_flutter_plugin.dart';

// 初始化SDK
String appId = '{{APPID}}'; // 替换成自己的
String channel = '{{CHANNEL}}'; // 填写App下载/分发渠道，例如iOS一般是'App Store'
bool enableEncrypt = true; // 加密开关
bool enableDebugLog = false; // 原生端日志开关
bool enableAB = false; // AB实验开关

// 设置数据上送地址，假设国内-华北
String? host = 'https://gator.volces.com';

RangersApplogFlutterPlugin.addInitParams({
    'service_vendor': 'private', // 固定值 private
    'autoStart': false, // 设置为false，等待后续调用start
});

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

// 之后再start
RangersApplogFlutterPlugin.start();

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

设置公共属性

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

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

import 'package:rangers_applog_flutter_plugin/rangers_applog_flutter_plugin.dart';

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

移除公共属性

import 'package:rangers_applog_flutter_plugin/rangers_applog_flutter_plugin.dart';

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

用户登录态设置

用户登录

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

import 'package:rangers_applog_flutter_plugin/rangers_applog_flutter_plugin.dart';

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

用户登出

在账户登出时调用。

import 'package:rangers_applog_flutter_plugin/rangers_applog_flutter_plugin.dart';

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

设置用户属性

profileSet

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

import 'package:rangers_applog_flutter_plugin/rangers_applog_flutter_plugin.dart';

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

profileSetOnce

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

import 'package:rangers_applog_flutter_plugin/rangers_applog_flutter_plugin.dart';

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

profileIncrement

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

import 'package:rangers_applog_flutter_plugin/rangers_applog_flutter_plugin.dart';

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

profileAppend

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

import 'package:rangers_applog_flutter_plugin/rangers_applog_flutter_plugin.dart';

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

profileUnset

删除用户的属性。

import 'package:rangers_applog_flutter_plugin/rangers_applog_flutter_plugin.dart';

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

获取平台生成ID

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

import 'package:rangers_applog_flutter_plugin/rangers_applog_flutter_plugin.dart';

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

完整代码示例

import 'package:rangers_applog_flutter_plugin/autotrack.dart';
// ...

class _MyAppState extends State<MyApp> {
    @override
    void initState() {
      RangersApplogAutoTrack().config(RangersApplogAutoTrackConfig(
        pageConfigs: [
          RangersApplogAutoTrackPageConfig<Home>(
            pageID: 'home-id',
            pageTitle: 'Home',
            pagePath: '/home-custom',
            ignore: false,
          ),
          RangersApplogAutoTrackPageConfig<Page2>(
            pageID: 'page2-id',
          ),
          RangersApplogAutoTrackPageConfig<Page3>(
            pageID: 'page3-id',
          ),
        ],
        ignoreElementKeys: [],
      )).enablePageLeave().enableLog().enable();
      super.initState();
    }
    
    // ...
    @override
    Widget build(BuildContext context) {
      return MaterialApp(
        navigatorObservers: RangersApplogNavigationObserver.wrap([]),
        initialRoute: '/',
        routes: {
          '/': ((context) => Home()),
          '/page2': ((context) => Page2()),
          '/page3': ((context) => Page3()),
        },
      );
    }
}

全埋点中 pageview，pageleave 是通过 NavigatorObserver 采集的，我们可以直接在 MaterialApp 中配置 RangersApplogNavigationObserver：

import 'package:rangers_applog_flutter_plugin/autotrack.dart';

// ...
@override
Widget build(BuildContext context) {
  return MaterialApp(
    navigatorObservers: [RangersApplogNavigationObserver()],
    // ...
  );
}
// ...

也可以在已有的 navigatorObservers 列表中，通过 RangersApplogNavigationObserver.wrap 包裹：

import 'package:rangers_applog_flutter_plugin/autotrack.dart';

// ...
@override
Widget build(BuildContext context) {
  return MaterialApp(
    navigatorObservers: RangersApplogNavigationObserver.wrap([]),
    // ...
  );
}
// ...

使用全埋点

• 启用全埋点

在 App 的 initState() 中启用全埋点：

import 'package:rangers_applog_flutter_plugin/autotrack.dart';

// ...
@override
void initState() {
    RangersApplogAutoTrack().enable();
    super.initState();
}
// ...

• 全埋点开关

全埋点默认关闭，可通过以下方法打开：

import 'package:rangers_applog_flutter_plugin/autotrack.dart';

RangersApplogAutoTrack().enable();

关闭全埋点：

import 'package:rangers_applog_flutter_plugin/autotrack.dart';

RangersApplogAutoTrack().disable();

• pageview 开关

pageview 默认开启，可用以下方法关闭：

import 'package:rangers_applog_flutter_plugin/autotrack.dart';

RangersApplogAutoTrack().disablePageView();

开启 pageview：

import 'package:rangers_applog_flutter_plugin/autotrack.dart';

RangersApplogAutoTrack().enablePageView();

• pageleave 开关

pageleave 默认关闭，可用以下方法开启（入参为 true，或者不传）：

import 'package:rangers_applog_flutter_plugin/autotrack.dart';

RangersApplogAutoTrack().enablePageLeave();

关闭 pageleave：

import 'package:rangers_applog_flutter_plugin/autotrack.dart';

RangersApplogAutoTrack().disablePageLeave();

• click 开关

click 默认开启，可用以下方法关闭：

import 'package:rangers_applog_flutter_plugin/autotrack.dart';

RangersApplogAutoTrack().disableClick();

开启 click：

import 'package:rangers_applog_flutter_plugin/autotrack.dart';

RangersApplogAutoTrack().enableClick();

• 设置 click 元素的自定义ID

我们通过 Key 来设置元素的自定义 ID，自定义 ID 在 click 埋点中会放在 element_manual_key 字段中一起上报，值是 Key 的 toString() 方法返回值，可以直接使用 RangersApplogElementKey。
触发 click 埋点的元素目前支持以下组件：

• GestureDetector
• InkWell
• ElevatedButton
• ListTile

对于支持列表以外的组件，则无法通过 Key 设置自定义 ID，click 埋点会触发在组件内部的 GestureDetector 上。

import 'package:rangers_applog_flutter_plugin/autotrack.dart';

...
ListTile(
  key: RangersApplogElementKey('custom-key'),
  title: Text("Click Me"),
  onTap: () {}
)
...

• 忽略 click 元素

如果不希望统计某些元素的 click 埋点，可以通过以下办法忽略 click 元素：
通过 RangersApplogElementKey 设置 ignore：

import 'package:rangers_applog_flutter_plugin/autotrack.dart';

...
ListTile(
  key: RangersApplogElementKey('custom-key', ignore: true),
  title: Text("Click Me"),
  onTap: () {},
)
...

通过 ignoreElementKeys() 方法指定元素的 key：

import 'package:rangers_applog_flutter_plugin/autotrack.dart';

...
final customKey = RangersApplogElementKey('custom-key');

...
RangersApplogAutoTrack().ignoreElementKeys([customKey]);

...
ListTile(
  key: customKey,
  title: Text("Click Me"),
  onTap: () {},
)
...

通过 ignoreElementStringKeys() 方法指定元素 key 的 string 值，只要与 key 的 toString() 返回值匹配即可生效，这里建议使用 RangersApplogElementKey：

import 'package:rangers_applog_flutter_plugin/autotrack.dart';

...
RangersApplogAutoTrack().ignoreElementStringKeys(['custom-key']);

...
ListTile(
  key: RangersApplogElementKey('custom-key'),
  title: Text("Click Me"),
  onTap: () {},
)
...

• 开启日志

日志默认关闭，可通过以下方式开启：

import 'package:rangers_applog_flutter_plugin/autotrack.dart';

RangersApplogAutoTrack().enableLog();

相关配置（可选）

• pageConfigs：用于配置页面的参数，影响 pageview，pageleave 埋点。需要指定页面的类型，配置只对指定页面生效。
  • pageID：页面的自定义 ID，在 pageview，pageleave 埋点中会放在 page_manual_key 字段上报。
  • pageTitle：页面的标题，如果不配置，则使用 AppBar 中指定的 title，配置后优先使用配置的值。在 pageview，pageleave 埋点中会放在 page_title 字段上报。
  • pagePath：页面的路径，如果不配置，则使用 MaterialApp 中通过 routes 配置的路径，配置后优先使用配置的值。在 pageview，pageleave 埋点中会放在 page_path 字段上报。
  • ignore：默认为 false，设置为 true 后会忽略当前页面的 pageview，pageleave 埋点。
• ignoreElementKeys：忽略入参中通过 Key 指定元素的 click 埋点。
• ignoreElementStringKeys：忽略入参中通过字符串指定元素的 click 埋点，匹配方式是字符串内容必须与元素 key 的 toString() 返回值相同。
• enablePageView：默认为 true，设置为 false 后会关闭所有的 pageview 埋点。
• enablePageLeave：默认为 false，设置为 true 后会开启所有的 pageleave 埋点。
• enableClick：默认为 true，设置为 false 后会关闭所有的 click 埋点。

示例

import 'package:rangers_applog_flutter_plugin/autotrack.dart';

RangersApplogAutoTrack().config(RangersApplogAutoTrackConfig(
  pageConfigs: [
    RangersApplogAutoTrackPageConfig<Home>(
      pageID: 'home-id',
      pageTitle: 'Home',
      pagePath: '/home-custom',
      ignore: false,
    ),
    RangersApplogAutoTrackPageConfig<Page2>(
      pageID: 'page2-id',
    ),
    RangersApplogAutoTrackPageConfig<Page3>(
      pageID: 'page3-id',
    ),
  ],
  ignoreElementKeys: [],
  ignoreElementStringKeys: [],
  enablePageView: true,
  enablePageLeave: false,
  enableClick: true,
));