import 'dart:async'; import 'package:flutter/widgets.dart'; import 'package:yx_tracking_flutter/src/config/analytics_config.dart'; import 'package:yx_tracking_flutter/src/core/analytics_core.dart'; import 'package:yx_tracking_flutter/src/core/interceptors.dart'; import 'package:yx_tracking_flutter/src/model/device_info.dart'; import 'package:yx_tracking_flutter/src/model/recent_event_summary.dart'; import 'package:yx_tracking_flutter/src/model/user_info.dart'; export 'src/config/analytics_config.dart'; export 'src/core/interceptors.dart'; export 'src/model/device_info.dart'; export 'src/model/event.dart'; export 'src/model/recent_event_summary.dart'; export 'src/model/user_info.dart'; export 'src/util/tag_templates.dart'; /// 对外唯一入口(Facade)。 class Analytics { /// 私有构造,避免外部实例化。 Analytics._(); /// 获取一个实例(用于满足 lint 对构造器的要求)。 factory Analytics.instance() => Analytics._(); static AnalyticsCore _core = AnalyticsCore(); static _AnalyticsLifecycleObserver? _lifecycleObserver; @visibleForTesting /// 测试钩子:读取当前核心实现。 static AnalyticsCore get coreForTesting => _core; @visibleForTesting /// 测试钩子:覆盖内部核心实现。 static set coreForTesting(AnalyticsCore core) => _core = core; /// 初始化 SDK。 static Future init(AnalyticsConfig config) => _core.init(config); /// 记录事件。 static Future track( String eventType, { Map? eventParams, Map? customTags, int? timestamp, }) { return _core.track( eventType, eventParams: eventParams, customTags: customTags, timestamp: timestamp, ); } /// 设置用户信息。 static Future setUser(UserInfo? userInfo) => _core.setUser(userInfo); /// 覆盖设备信息。 static Future setDeviceInfo(DeviceInfo deviceInfo) => _core.setDeviceInfo(deviceInfo); /// 触发一次上报。 static Future flush({bool force = false}) => _core.flush(force: force); /// 当前本地缓存事件数量(用于调试/演示)。 static Future cachedEventCount() => _core.cachedEventCount(); /// 最近事件摘要(用于调试面板)。 static Future> cachedRecentEvents({ int limit = 20, }) => _core.cachedRecentEvents(limit: limit); /// Phase 2:手动触发一次配置刷新(默认强制刷新)。 static Future refreshConfig({bool force = true}) => _core.refreshConfig(force: force); /// Phase 3:立即上报一次 SDK 指标(调试/测试用)。 static Future reportMetricsNow() => _core.reportMetricsNow(); /// Phase 3:注册事件拦截器。 static void addInterceptor(AnalyticsInterceptor interceptor) { _core.addInterceptor(interceptor); } /// 动态设置 Debug 开关。 static void setDebug({required bool enabled}) { unawaited(_core.setDebug(enabled: enabled)); } /// 可选:当宿主确定不再需要 SDK 时调用。 static Future dispose() async { unbindLifecycleObserver(); await _core.dispose(); } /// 可选:绑定应用生命周期监听,进入后台时自动 flush。 static void bindLifecycleObserver({ bool flushOnBackground = true, bool flushOnDetached = true, }) { if (_lifecycleObserver != null) { return; } WidgetsFlutterBinding.ensureInitialized(); final observer = _AnalyticsLifecycleObserver( flushOnBackground: flushOnBackground, flushOnDetached: flushOnDetached, onFlush: () { unawaited(_core.flush(force: true)); }, ); _lifecycleObserver = observer; WidgetsBinding.instance.addObserver(observer); } /// 解绑生命周期监听,避免重复注册或泄漏。 static void unbindLifecycleObserver() { final observer = _lifecycleObserver; if (observer == null) { return; } WidgetsBinding.instance.removeObserver(observer); _lifecycleObserver = null; } } class _AnalyticsLifecycleObserver extends WidgetsBindingObserver { _AnalyticsLifecycleObserver({ required this.flushOnBackground, required this.flushOnDetached, required this.onFlush, }); final bool flushOnBackground; final bool flushOnDetached; final VoidCallback onFlush; @override void didChangeAppLifecycleState(AppLifecycleState state) { switch (state) { case AppLifecycleState.inactive: case AppLifecycleState.paused: case AppLifecycleState.hidden: if (flushOnBackground) { onFlush(); } case AppLifecycleState.detached: if (flushOnDetached) { onFlush(); } case AppLifecycleState.resumed: break; } } }