Flutter日志记录插件nlogger的使用

Nethru Logging SDK 是一个用于收集用户行为信息的库。以下是该插件的基本使用方法。

开始使用

在使用此库之前，必须确保在应用程序首次运行时调用一次 configure() 函数，并在此时指定所需的各种设置。

初始化配置

import 'package:nlogger/nlogger.dart';

await NLogger.configure(context, await rootBundle.loadString('assets/nlogger.json'));

注意：configure() 函数必须在应用首次启动时调用一次。可以将此函数放在 main() 方法中，通过 FutureBuilder 确保初始化不会影响用户体验。

发送日志

可以通过调用 event() 函数随时发送日志。

示例 1：简单日志记录

NLogger.event(action: 'example1', context: context);

示例 2：带参数的日志记录

NLogger.event(
  action: 'example2',
  params: {
    'p1': 'v1',
    'p2': 'v2'
  },
  context: context
);

用户登录信息

如果用户已登录，可以将用户信息传递给日志记录器。

await NLogger.setUserId('nethru');

默认附加信息

可以设置一些始终与每个日志一起发送的信息。

await NLogger.setSessionAttrs({
  'nth_p1': 'v1',
  'nth_p2': 'v2'
});

配置选项

configure() 函数支持以下配置选项：

API 参考

以下是 API 的详细说明：

Future<void> configure(BuildContext context, String json)

void event({
    bool https = true,
    String? serviceId,
    required String action,
    Map<String, String>? params,
    Map<String, String>? cookies,
    BuildContext? context
})

String getDeviceId()
Future<void> setDeviceId(String value)

String getCustomId()
Future<void> setCustomId(String value)

String getUserId()
Future<void> setUserId(String value)

Future<void> setSessionAttrs(Map<String, String> attrs)
Map<String, dynamic> getSessionAttrs()
Future<void> clearSessionAttrs()

Future<Map<String, dynamic>> getAllAttrs([BuildContext? context])

void setLogLevel(LogLevel level)

示例代码

以下是一个完整的示例代码，展示如何在 Flutter 应用程序中使用 nlogger 插件。

import 'package:flutter/material.dart';
import 'package:flutter/services.dart' show rootBundle;
import 'package:nlogger/nlogger.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  [@override](/user/override)
  Widget build(BuildContext context) {
    return FutureBuilder(
        future: initNLogger(context), // 异步初始化以避免影响用户体验
        builder: (context, snapshot) {
          return MaterialApp(
            title: 'Flutter Demo',
            theme: ThemeData(
              colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
              useMaterial3: true,
            ),
            home: const MyHomePage(title: 'Flutter Demo Home Page'),
          );
        });
  }
}

// 初始化 NLogger
Future<void> initNLogger(BuildContext context) async {
  // 调用 configure() 函数进行初始化
  await NLogger.configure(context, await rootBundle.loadString('assets/nlogger.json'));

  // 设置用户 ID
  await NLogger.setUserId('nethru');

  // 设置默认会话属性
  await NLogger.setSessionAttrs({
    'nth_p1': 'v1',
    'nth_p2': 'v2'
  });
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key, required this.title});
  final String title;

  [@override](/user/override)
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  int _counter = 0;

  // 增加计数并发送日志
  void _incrementCounter(BuildContext context) async {
    // 调用 event() 函数发送日志
    NLogger.event(
        action: 'click/plus_button',
        params: {
          'count': '${_counter + 1}'
        },
        context: context // 必须传递 BuildContext 包含区域信息
    );

    setState(() {
      _counter++;
    });
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        backgroundColor: Theme.of(context).colorScheme.inversePrimary,
        title: Text(widget.title),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            const Text(
              'You have pushed the button this many times:',
            ),
            Text(
              '$_counter',
              style: Theme.of(context).textTheme.headlineMedium,
            ),
          ],
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: () => _incrementCounter(context),
        tooltip: 'Increment',
        child: const Icon(Icons.add),
      ),
    );
  }
}