analytics_sdk 0.1.0

通用 Flutter 埋点 SDK，纯 Dart 实现，支持公共参数、离线队列与批量上报。

analytics_sdk

通用 Flutter 埋点 SDK（Plugin 形态，核心逻辑纯 Dart 实现）。

特性

• 插件工程，Android/iOS 保留默认模板，后续可扩展原生能力
• 纯 Dart 实现采集、公共参数、离线队列、批量上报
• 不依赖任何业务代码，各 App 通过配置快速接入
• 自动采集：App 启动、前后台、页面进入（page_view）、页面离开（page_leave）
• 元素可见性采集：Analytics.visible 自动上报 element_visible / element_hidden
• 适配 GetX 路由表（GetPage 数组 + routingCallback）
• 内置公共参数：设备型号、系统版本、App 版本、网络、locale 等
• 内置隐私过滤：剔除 token/phone 等敏感字段

快速接入

1. 添加依赖

dependencies:
  analytics_sdk:
    path: ../analytics_sdk
    # 或 git:
    #   url: git@company:mobile/analytics_sdk.git
    #   ref: v0.1.0

2. 初始化（main.dart）

import 'package:analytics_sdk/analytics_sdk.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Analytics.init(
    const AnalyticsConfig(
      appId: 'app的包名',
      serverUrl: 'https://analytics.company.com/v1/events/batch',
      env: AnalyticsEnv.release,
      enableDebugLog: false,
      superPropertiesProvider: () async => {
        'channel': 'app_store',
      },
    ),
  );

  runApp(const MyApp());
}

3. 页面路由埋点

MaterialApp

MaterialApp(
  navigatorObservers: [
    Analytics.navigatorObserver(),
  ],
  // ...
)

自动上报：

导航	事件
push / replace	离开页 page_leave + 进入页 page_view
pop	离开页 page_leave + 返回页 page_view

ignoredRoutes 中的路由会同时跳过进入与离开埋点：

Analytics.navigatorObserver(ignoredRoutes: {'/splash'})

GetX（GetPage 路由表）

static final routerPages = [
  GetPage(name: AppRoutes.splashPage, page: () => const SplashPage()),
  GetPage(name: AppRoutes.loginPage, page: () => const LoginPage()),
];

GetMaterialApp(
  initialRoute: AppRoutes.splashPage,
  getPages: routerPages,
  routingCallback: Analytics.routingCallback(),
);

与业务已有 routingCallback 合并：

routingCallback: Analytics.routingCallback(
  onRouting: (routing) {
    AppOrientation.syncWithRoute(routing?.current);
  },
),

或多个回调：

routingCallback: Analytics.combineRoutingCallbacks([
  (routing) => AppOrientation.syncWithRoute(routing?.current),
  Analytics.routingCallback(),
]),

4. 生命周期（可选）

在根 State 混入：

class _MyAppState extends State<MyApp> with AnalyticsLifecycleMixin {
  // ...
}

自动上报 app_foreground / app_background。

5. 业务埋点

点击类事件：在业务 onPressed / onTap 中直接调用，无需 SDK 包装组件：

ElevatedButton(
  onPressed: () {
    Analytics.track('login_success', properties: {
      'login_type': 'phone_code',
    });
    // 原有业务逻辑...
  },
  child: const Text('登录'),
);

元素可见性：可选包裹需要曝光采集的组件，不拦截任何手势：

Analytics.visible(
  elementName: 'home_banner',
  properties: const {'position': 'top'},
  child: BannerWidget(), // 业务组件行为不变
)

自动上报 element_visible（进入可视区域）和 element_hidden（离开可视区域 / 组件销毁）。

用户身份：

await Analytics.identify(userId: userId);
await Analytics.resetIdentity(); // 登出
await Analytics.flush();         // 手动刷盘

配置说明

配置项	默认值	说明
enableAutoPageView	true	自动采集页面进入
enableAutoPageLeave	true	自动采集页面离开
pageLeaveEventName	page_leave	页面离开事件名
sampleRate	1.0	全局采样率（0.0 ~ 1.0）
flushInterval	15s	定时上报间隔
flushBatchSize	20	单次 HTTP 请求最大条数
visibleEventName	element_visible	元素可见事件名
invisibleEventName	element_hidden	元素不可见事件名
exposureVisibleFraction	0.5	可见面积比例阈值
immediateEvents	{}	命中后立即上报的事件
blockedEvents	{}	禁止采集的事件

批量上报机制

• 定时上报：默认每 15 秒触发一次 flush()，队列中有多少发多少（不必攒满）
• 单批上限：flushBatchSize = 20 表示单次 HTTP 最多 20 条，超出则分批发完
• 立即上报：immediate: true、immediateEvents 命中、Debug 环境、page_leave 等场景会立刻 flush

公共参数说明

每条事件自动携带：

分类	字段
app	app_id, app_version, build_number, package_name, env, sdk_version
device	platform, os_version, device_model
identity	anonymous_id, session_id, user_id(登录后)
super	network_type, locale, timezone_offset_minutes + 自定义

自定义公共参数：

Analytics.setSuperProperties({'channel': 'huawei'});
Analytics.mergeSuperProperties({'ab_group': 'A'});

事件命名规范

• 仅小写字母、数字、下划线
• 以字母开头，最长 64 字符
• 示例：login_success、cast_start、page_view、page_leave

上报协议

{
  "sent_at": 1710000000999,
  "events": [
    {
      "event_id": "evt_xxx",
      "event_name": "login_success",
      "event_type": "track",
      "event_time": 1710000000123,
      "collection_mode": "manual",
      "identity": { "anonymous_id": "...", "session_id": "...", "user_id": "..." },
      "app": { "app_id": "app的包名", "app_version": "3.2.0" },
      "device": { "platform": "ios", "device_model": "iPhone15,2" },
      "super_properties": { "network_type": "wifi", "locale": "zh-CN" },
      "properties": { "login_type": "phone_code" }
    }
  ]
}

调试

开发环境建议：

AnalyticsConfig(
  env: AnalyticsEnv.debug,
  enableDebugLog: true,
  serverUrl: '', // 为空时只落本地队列并打印日志，不上报网络
)

接入 Checklist

• ❌ Analytics.init 在 runApp 前调用
• ❌ 配置唯一 appId
• ❌ MaterialApp 注册 navigatorObserver，或 GetX 注册 routingCallback
• ❌ 登录成功 identify
• ❌ 登出 / token 失效 resetIdentity
• ❌ 点击类事件在业务 handler 中 track
• ❌ 需要曝光采集的组件用 Analytics.visible 包裹

Example

example/ 目录提供 GetX 路由表、routingCallback、可见性采集、点击埋点等完整示例，可直接运行参考。

版本

• 0.1.0：MVP，纯 Dart 核心 + Plugin 骨架