Flutter音乐评分插件finotescoreplugin的使用

入门指南

步骤一

1. 在 https://finotes.com 上注册并登录到仪表板。
2. 使用 “添加应用” 功能将 Android 和 iOS 应用程序链接到 Finotes。
3. 将 Finotes 插件集成到您的应用程序中。
4. 测试您的集成。

集成前的要求

• 插件支持 Dart SDK 版本大于等于 3.1.0 并小于 4.0.0。
• Flutter 版本应大于等于 3.3.0。
• 对于 Android 平台，Kotlin 版本应大于等于 1.8.0。

集成插件

在 pubspec.yaml 文件中添加 finotescoreplugin：

dependencies:
  finotescoreplugin: ^version

初始化Finotes

在主函数中调用 Fn.init() 函数。确保在调用 init API 之前先调用 WidgetsFlutterBinding.ensureInitialized()。

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

    WidgetsFlutterBinding.ensureInitialized();
    Fn.init();
}

设置Proguard规则

如果您在发布构建中使用 Proguard，则需要向 proguard-rules.pro 文件中添加以下内容：

-keep class com.finotes.android.finotescore.* { *; }

-keepclassmembers class * {
    @com.finotes.android.finotescore.annotation.Observe *;
}

-keepattributes SourceFile,LineNumberTable

请确保生产构建（每次构建）的映射文件被备份，以便从 Finotes 仪表板解混淆堆栈跟踪。 映射文件位置：project-folder/app/build/outputs/proguard/release/mapping.txt

测试集成

现在基本的 Finotes 插件集成已经完成，让我们确保仪表板和插件同步。

步骤一

在 Fn.init() 下添加 Fn.test()。

import 'package:finotescoreplugin/finotescoreplugin.dart';

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

    WidgetsFlutterBinding.ensureInitialized();
    Fn.init();

    Fn.test(); // 引发测试问题的行
}

步骤二

一旦应用程序打开，打开 Finotes 仪表板。 我们引发的测试问题应该被报告。

记得移除 Fn.test() 调用，否则每次运行应用程序时都会报告一个问题。

错误报告

通过基本集成，Finotes 会自动跟踪并报告未捕获的异常到 Finotes 仪表板。

报告已捕获区域的错误

任何已经在 Zone 中捕获的异常都需要报告，因为它们可能会阻止应用程序崩溃，但同时如果未报告可能会使应用程序不稳定。

runZonedGuarded<Future<void>>(() async {
  
    ....

}, (dynamic error, StackTrace stackTrace) {
    Fn.reportError(error, stackTrace); // 单行 API 来报告捕获的错误。
});

报告应用启动延迟

为了激活检测应用启动延迟的功能，扩展第一个状态类为 FnInitialState 类，并且其余的状态类扩展为 FnState 类。

如果应用程序加载时间超过 3000 毫秒，则会被报告到 Finotes 仪表板。

class _MyAppState extends FnInitialState<MyApp> { // 替换 State 类为 FnInitialState 类。
    ...

    [@override](/user/override)
    Widget build(BuildContext context) {
        super.build(context); // 确保在此处调用 super。
        return ...
    }
}

报告自定义问题

使用 Fn.reportIssue() API 来报告自定义问题。

Fn.reportIssue("Main App", "Payment failed", "Payment failed when selecting basic package");

内存泄漏

为了捕获应用程序中的内存泄漏，扩展 State 类为由插件提供的自定义类 FnState（替换第一个 State 类为 FnInitialState 类）。

class _MyAppState extends FnState<MyApp> { // 替换 State 类为 FnState 类。
    ...

}

跟踪UI阻塞问题

此功能在插件中自动激活。 通过基本集成，Finotes 会跟踪并报告可能导致 Android 的应用程序无响应（ANR）情况以及 iOS/iPadOS 中的应用程序挂起的情况。

报告HTTP(s)问题

FinotesCore 插件支持跟踪 HTTP(s) 调用。

在插件中添加 FnClient。

import 'package:finotescoreplugin/fn_client.dart';

...

var client = http.Client(); // 常规 HTTP 客户端进行调用。

var client = FnClient(); // 用 Finotes 插件客户端替换您的 HTTP 客户端。

活动轨迹

活动标记是在应用程序运行期间发生的事件。为了捕获应用中使用的状态的生命周期事件，扩展 State 类为插件提供的自定义类 FnState（替换第一个 State 类为 FnInitialState 类）。

class _MyAppState extends FnState<MyApp> { // 替换 State 类为 FnState 类。
    ...

    [@override](/user/override)
    Widget build(BuildContext context) {
        super.build(context); // 确保在此处调用 super。
        return ...
    }
}

设置自定义活动轨迹

开发人员可以在应用程序的任何地方使用 Fn.setActivityMarker() 设置自定义活动轨迹标记。这些标记会在出现问题时与生命周期事件一起显示。

Fn.setActivityMarker("Main App", "User tapped on payment button");

启用 Finotes 日志

您可以使用 logMe() API 激活内部 Finotes 日志。 激活 logMe() API 将打印插件生成的所有日志，包括错误和警告日志。

Fn.logMe();

在准备生产发布时，务必移除日志 API。

示例代码

import 'dart:async';
import 'dart:convert';

import 'package:finotescoreplugin/finotescoreplugin.dart';
import 'package:finotescoreplugin/fn_client.dart';
import 'package:finotescoreplugin/state_custom.dart';
import 'package:finotescoreplugin/observe.dart';
import 'package:flutter/material.dart';

void main() {
  runApp(const MyRootApp());

  WidgetsFlutterBinding
      .ensureInitialized(); // 确保执行 'ensureInitialized' 之后再执行 Fn.init()。

  Fn.logMe();
  Fn.init(); // 需要调用此函数来激活插件。
  Observe().setMaskedHeaders(["connection"]);
  Observe().setWhiteListedDomain(["jsonplaceholder.typicode.com"]);
  Observe().setBaseUrlTimeouts({
    "jsonplaceholder.typicode.com": 1000
  }); // 超时值应大于或等于 1000。
}

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

  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(primarySwatch: Colors.blue),
      home: const MyScreenApp(),
    );
  }
}

class MyScreenApp extends StatefulWidget {
  const MyScreenApp({Key? key}) : super(key: key);

  [@override](/user/override)
  State<MyScreenApp> createState() => _MyAppState();
}

class _MyAppState extends FnInitialState<MyScreenApp> {
  // 替换 'State' 类为 'FnState' 以允许 finotescore 插件跟踪生命周期方法。
  int _counter = 0;

  [@override](/user/override)
  void initState() {
    super.initState();
  }

  void fetchTodoWithHttpClient() async {
    var client = FnClient(); // 用 finotescore 客户端替换您的 HTTP 客户端。

    try {
      var response = await client
          .get(Uri.https('jsonplaceholder.typicode.com', 'todos/1'));
      var decodedResponse = jsonDecode(utf8.decode(response.bodyBytes)) as Map;
      print(decodedResponse);
    } finally {
      client.close();
    }
  }

  void _incrementCounter(BuildContext context) {
    Fn.test();
    if (_counter <= 0) {
      fetchTodoWithHttpClient();
    }

    setState(() {
      _counter++;
    });
    Fn.setActivityMarkerAt("Main",
        "User tapped on increment counter"); // 设置活动标记以获取问题上下文。

    runZonedGuarded(() async {
      throw Exception(); // 异常所在行。
    }, (error, stackTrace) {
      Fn.reportError(
          error, stackTrace); // 单行 API 来报告捕获的错误。
    });
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    super.build(context);
    return Scaffold(
      appBar: AppBar(
        title: const Text('Plugin example app'),
      ),
      body: Center(
        child: Text('Run $_counter'),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: () {
          _incrementCounter(context);
        },
        tooltip: 'Increment',
        child: const Icon(Icons.add),
      ), // 这个逗号使得自动格式化更美观。
    );
  }
}