Flutter数据分析插件flutter_analytics的使用

简介

flutter_analytics 是一个轻量级的分析SDK，用于从Flutter应用程序中收集匿名元数据。

使用方法

首先，确保已安装 flutter_analytics 插件。可以通过以下命令添加到项目中：

dependencies:
  flutter_analytics: ^x.x.x

然后，在代码中导入并初始化插件。

初始化插件

在应用生命周期中调用一次 setup() 方法来初始化插件。

import 'package:flutter_analytics/flutter_analytics.dart' show Analytics;

// 初始化插件，指定目标地址
Analytics().setup(destinations: ['http://localhost:3000/analytics']);

用户分组

通过 group() 方法唯一标识一组用户，并传递其特征（traits）。

// 唯一标识一组用户
Analytics().group('someGroupId', {'numTrait': 7, 'txtTrait': 'tGroup'});

当前用户识别

使用 identify() 方法唯一标识当前用户及其特征。

// 唯一标识当前用户
Analytics().identify('anUserId', {'numTrait': 5, 'txtTrait': 'uUser'});

屏幕追踪

通过 screen() 方法记录当前屏幕的视图。

// 记录当前屏幕
Analytics().screen('My Screen', {'numProp': -1, 'txtProp': 'pScreen'});

事件追踪

使用 track() 方法跟踪离散事件。

// 跟踪任意事件
Analytics().track('Any Event', {'numProp': 3, 'txtProp': 'pTrack'});

示例代码

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

// ignore_for_file: public_member_api_docs
import 'package:flutter/material.dart';
import 'package:flutter_analytics/flutter_analytics.dart' show Analytics;

Future<void> example() async {
  // 初始化插件，指定目标地址
  Analytics().setup(destinations: ['http://localhost:3000/analytics']);

  // 唯一标识一组用户
  Analytics().group('someGroupId', {'numTrait': 7, 'txtTrait': 'tGroup'});

  // 唯一标识当前用户
  Analytics().identify('anUserId', {'numTrait': 5, 'txtTrait': 'uUser'});

  // 记录当前屏幕
  Analytics().screen('My Screen', {'numProp': -1, 'txtProp': 'pScreen'});

  // 跟踪任意事件
  Analytics().track('Any Event', {'numProp': 3, 'txtProp': 'pTrack'});

  // 调试日志并打印事件（返回 `true` 可绕过目标地址）
  await Analytics().flush((batch) async {
    batch.forEach(print);

    return true;
  });
}

class ExampleApp extends StatefulWidget {
  const ExampleApp();

  @override
  State<StatefulWidget> createState() => ExampleAppState();
}

class ExampleAppState extends State<ExampleApp> with WidgetsBindingObserver {
  @override
  Widget build(BuildContext context) {
    return FutureBuilder(
      future: runExample(),
      builder: (context, snapshot) {
        return MaterialApp(
          home: Scaffold(
            body: Center(
              child: Text(snapshot.data as String ?? 'hold on'),
            ),
          ),
        );
      },
    );
  }

  @override
  void didChangeAppLifecycleState(AppLifecycleState state) =>
      Analytics().updateAppLifecycleState(state);

  @override
  void dispose() {
    WidgetsBinding.instance.removeObserver(this);
    super.dispose();
  }

  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
  }

  Future<String> runExample() async {
    try {
      await Analytics().requestPermission();
      await Future<void>.delayed(Duration(seconds: 5));
      await example();

      return 'Everything fine, see console!';
    } catch (e, s) {
      debugPrint('$e\n$s');

      return 'Something went wrong, see console!';
    }
  }
}

void main() => runApp(const ExampleApp());

服务器端消费示例

以下是一个AWS Lambda函数的示例，用于接收来自 flutter_analytics 的批量数据并将其上传到S3。

from base64 import b64decode
from boto3 import client
from datetime import datetime
from dateutil.parser import parse
from gzip import GzipFile
from io import BytesIO
from json import dumps, loads
from zlib import decompress, MAX_WBITS

s3 = client('s3')

bucket = 'my.bucket'
output_file = 'output.json'

def lambda_handler(event, context):
    try:
        return {'statusCode': 200, 'body': upload(event)}
    except Exception as e:
        return {'statusCode': 500, 'body': str(e)}


def upload(event):
    decoded = b64decode(loads(event['body'])['batch'])
    batch = loads(decompress(decoded, MAX_WBITS | 16))

    gz_body = BytesIO()
    gz = GzipFile(None, 'wb', 1, gz_body)
    gz.write(dumps(batch).encode('utf-8'))
    gz.close()

    s3.put_object(
        Body=gz_body.getvalue(),
        Bucket=bucket,
        Key=output_file,
        ContentEncoding='gzip',
        ContentType='application/json'
    )

    return '{"success":true}'

OTA远程配置

可以通过 configUrl 参数加载远程配置文件。

Analytics().setup(
  configUrl: 'https://gist.githubusercontent.com/oakromulo/7678b2b187a24e47c0ba93085575477d/raw/e72767273e4e6a73d14377f650be63d66033a6e3/config.json'
);

安装位置依赖

Android

在 AndroidManifest.xml 中添加以下权限：

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

更新 gradle.properties 文件：

android.enableJetifier=true
android.useAndroidX=true
org.gradle.jvmargs=-Xmx1536M

确保在 build.gradle 中包含以下依赖：

dependencies {
    classpath 'com.android.tools.build:gradle:3.3.0'
    classpath 'com.google.gms:google-services:4.2.0'
}
compileSdkVersion 28

iOS

在 Info.plist 中添加以下权限描述：

NSLocationWhenInUseUsageDescription
NSLocationAlwaysUsageDescription

注意：iOS模拟器存在一个已知问题，需要多次选择位置才能发送数据。

在模拟器上运行示例

cd ~/flutter_analytics/example
flutter packages get
open -a simulator
flutter run

运行集成测试

cd ~/flutter_analytics/test
flutter packages get
APP_CONFIG_URL="https://remote.config" flutter pub run tool/tool_env.dart
flutter drive --target=lib/main.dart