Flutter日志分析与监控插件loglytics的使用

Flutter日志分析与监控插件loglytics的使用

📊 Loglytics

Loglytics 提供了一个完整的解决方案，用于简单但强大的日志记录，并同时（但可选地）发送应用内部的分析和崩溃报告。最初，这个包是为了集成到 firebase_analytics 和 firebase_crashlytics 中创建的，但通过一个可爱的界面，现在也可以实现其他分析或崩溃报告解决方案。

除了简化日志记录和发送分析外，Loglytics 还旨在改善您的整体分析方法。所有在 Loglytics 内部的分析都基于主题和参数。每个分析都将根据功能（或其他项目部分，您认为合适）进行封装，并为它们定义主题列表（例如 'login_button') 和可能的参数（例如 'time_on_page')。一般来说，主题可以有一个事件关联到它们，而参数则是额外详细信息。因为我们为每个功能（或其他项目部分）指定并存储了我们的分析，在一个中央位置，我们避免了错误，并在项目中创造了某种秩序、清晰和结构，这通常是当分析从各个地方发送时经常被忽视的。

🔎 如何开始？

首先，我们需要确定是否要在项目中实现自定义分析和/或崩溃报告。如果不需要，我们仍然可以使用 Loglytics 来记录和发送基本分析，而无需进行任何配置。如果我们确实想使用其中一个或两者，我们必须实现 AnalyticsInterface 和 CrashReportsInterface，以便将它们传递给 Loglytics.setUp() 方法。在调用 Loglytics.setUp() 方法之前，我们需要发送任何分析或崩溃报告。下面是一个使用 Firebase Analytics 和 Firebase Crashlytics 的实现示例。请注意，analytics 参数中的回调是必要的，以方便访问我们实现的 Analytics 对象。更多关于 Analytics 对象的信息稍后会提到。

import 'package:firebase_analytics/firebase_analytics.dart';
import 'package:loglytics/analytics/analytics_interface.dart';

class AnalyticsImplementation implements AnalyticsInterface {
  AnalyticsImplementation(this._firebaseAnalytics);
  final FirebaseAnalytics _firebaseAnalytics;

  @override
  Future<void> logEvent({required String name, Map<String, Object?>? parameters}) async {
    await _firebaseAnalytics.logEvent(name: name, parameters: parameters);
  }

  @override
  Future<void> resetAnalyticsData() async {
    await _firebaseAnalytics.resetAnalyticsData();
  }

  @override
  Future<void> setCurrentScreen({required String name, String? screenClassOverride}) {
    if (screenClassOverride != null) {
      return _firebaseAnalytics.setCurrentScreen(screenName: name, screenClassOverride: screenClassOverride);
    } else {
      return _firebaseAnalytics.setCurrentScreen(screenName: name);
    }
  }

  @override
  Future<void> setUserId(String? id) async {
    await _firebaseAnalytics.setUserId(id);
  }

  @override
  Future<void> setUserProperty({required String name, required String? value}) async {
    await _firebaseAnalytics.setUserProperty(name: name, value: value);
  }
}

import 'package:firebase_crashlytics/firebase_crashlytics.dart';
import 'package:flutter/foundation.dart';
import 'package:loglytics/crashlytics/crashlytics_interface.dart';

class CrashReportsImplementation implements CrashReportsInterface {
  CrashReportsImplementation(this._firebaseCrashlytics);
  final FirebaseCrashlytics _firebaseCrashlytics;

  @override
  Future<void> log(String message) async {
    await _firebaseCrashlytics.log(message);
  }

  @override
  Future<void> recordError(
    exception,
    StackTrace? stack, {
    reason,
    Iterable<DiagnosticsNode> information = const [],
    bool? printDetails,
    bool fatal = false,
  }) async {
    await _firebaseCrashlytics.recordError(
      exception,
      stack,
      reason: reason,
      information: information,
      printDetails: printDetails,
      fatal: fatal,
    );
  }

  @override
  Future<void> setCustomKey(String key, Object value) async {
    await _firebaseCrashlytics.setCustomKey(key, value);
  }

  @override
  Future<void> setUserIdentifier(String identifier) async {
    await _firebaseCrashlytics.setUserIdentifier(identifier);
  }
}

Loglytics.setUp(
  analyticsInterface: AnalyticsImplementation(Object()),
  crashReportsInterface: CrashReportsImplementation(Object()),
);

📈 如何发送分析（和崩溃报告）？

接下来，我们需要确定如何实现特征样式的分析实施方式。无论如何，重要的是我们可以定义项目的某些部分（如一个功能），并将其链接到特定部分的主题和参数（或功能）。一旦我们明确了这一点，我们就可以设置第一个 Analytics 实现的实例。下面是一个登录功能示例，其中包含一个主题和一个参数的实现。

import 'package:loglytics/loglytics.dart';

class LoginAnalytics extends Analytics {
  final String loginButton = 'login_button';
  final String timeOnPage = 'time_on_page';

  final String _loginView = 'login_view';

  void viewPage() {
    service.viewed(subject: _loginView);
  }
}

在指定主题和参数之后，我们现在需要将 LoginAnalytics 对象添加到我们早些时候提到的 Loglytics.setUp 调用中。我们通过在 AnalyticsFactory 中注册对象来实现这一点。此方法接受一个回调，该回调用于通过依赖注入和 get_it 包提供 Analytics 对象。一起看起来应该像这样：

Loglytics.setUp(
  analyticsImplementation: AnalyticsImplementation(Object()),
  crashReportsImplementation: CrashReportsImplementation(Object()),
  shouldLogAnalytics: true,
  analytics: (analyticsFactory) {
    analyticsFactory.registerAnalytic(() => LoginAnalytics());
  },
);

请注意，我们使用单独的 GetIt 实例来维护这些回调。如果你的应用程序使用 GetIt 并且你时不时重置它，请不要忘记重置这些（或者选择不这样做，你的选择）。

现在我们可以移动到我们的第一个 Loglytics 混入类的使用。我们将刚刚制作的登录 Analytics 实现的名字作为通用参数传递给 Loglytics 混入类。这看起来如下：

class LoginClass with Loglytics<LoginAnalytics> {}

💡 提示：评论你的 Analytics 实现，并为分析师创建 Dart 文档，这样他们就能了解应用程序内正在发送的所有分析！

这就是全部内容，现在我们有了所有工具来为应用程序的这一特性/项目部分的日志记录和发送分析。现在当我们输入 analytics 然后选择一个动作时，我们会拥有所有定义的主题和参数（对于这一特性/项目部分）的回调（✨）。使用它可以看起来像这样：

class LoginClass with Loglytics<LoginAnalytics> {
  
  void initialise() {
    // 其他代码在这里
    analytics.viewPage();
  }

  void login() {
    // 让我们在按钮点击时进行日志记录。
    analytics.service.tapped(subject: analytics.loginButton);
    // 假设登录成功。
    analytics.service.succeeded(
      subject: analytics.login,
      parameters: {
        // 那花了点时间
        analytics.timeOnPage: 123,
      },
    );
  }
}

🔧 自定义分析

如果我们要在 Analytics 实现中使用自己的方法（而不是主题字符串），则可以使用 CustomAnalytic 对象。这是一个简单的包装器，接受事件名称和可选参数。为了发送它，必须调用事件方法。这个方法的行为与其他方法相似，只是只有一个回调，并且它期望一个 CustomAnalytic 对象作为返回值（你可以通过特定的方法从你的 Analytics 实现传递下来）。实现它可以看起来像这样：

class ExampleAnalytics extends Analytics {
  // 事件名称
  final buttonViewedWithSomeMagic = 'button_viewed_with_some_magic';
  // 参数
  final name = 'name';

  CustomAnalytic buttonViewedWithSomeMagic(String buttonName) {
    return CustomAnalytic(
      name: buttonViewedWithSomeMagic,
      parameters: {
        name: buttonName,
      },
    );
  }
}

使用它可以看起来像这样：

void _doSomething() {
  analytics.service.custom(analytic: analytics.buttonViewedWithSomeMagic('magic_button'));
}

☝️ 使用类独立地

从版本 0.10.0 开始，也有可能创建 Log, Loglytics 和 AnalyticsService 对象。如果你在 Loglytics.setUp 方法中定义了 CrashlyticsInterface 或 AnalyticsInterface，这些也将向其相应的实现发送事件。定义三个类可能会看起来有点像这样：

class IndividualUsage {
  late final Loglytics loglytics = Loglytics.create(location: runtimeType.toString());
  late final Log log = Log(location: runtimeType.toString());
  late final AnalyticsService analyticsService = AnalyticsService();
}