Flutter数据库与后端服务集成插件supabase_addons的使用

Supabase是一个开源的Firebase替代品。它支持认证、数据库和存储更新。这个包的目的是在使用Supabase时让事情变得更简单。

目录

• 开始使用
• 认证插件
  • 如何工作？
  • 更改存储路径
• 分析
  • 开始使用分析
  • 记录事件
  • 认证事件
  • 内置事件
• 崩溃报告
  • 开始使用崩溃报告
  • 切换收集
  • 记录错误
  • 处理未捕获的错误
• 功能和问题

开始使用

首先，在你的pubspec.yaml文件中添加依赖：

dependencies:
  supabase: <latest-version>
  supabase_addons: <latest-version>

然后导入supabase和supabase_addons：

import 'package:supabase/supabase.dart';
import 'package:supabase_addons/supabase_addons.dart';

初始化插件：

await SupabaseAddons.initialize(
  client: SupabaseClient(SUPABASE_URL, SUPABASE_SECRET),
);

在所有操作完成后，你应该释放插件资源。如果不这样做，可能会导致性能问题：

SupabaseAddons.dispose();

认证插件

认证插件能够将用户会话持久化到设备存储中。它基于一个轻量级且快速的键值数据库Hive。

如何工作？

每次用户登录或会话更新时，用户会话都会被持久化到设备上。当用户登出时，会话会被从设备上移除。

这种行为在调用SupabaseAddons.initialize时默认启用。要禁用它，可以调用SupabaseAuthAddons.dispose()。一旦禁用，就无法再次开启。

更改存储路径

在初始化插件时，你可以更改storagePath到你想要的位置：

SupabaseAddons.initialize(
  ...,
  authPersistencePath: './auth'
);

如果你在一个Flutter环境中，你可以使用path_provider包来获取应用文档路径：

import 'package:path_provider/path_provider.dart';

final dir = await getApplicationDocumentsDirectory();

SupabaseAddons.initialize(
  ...,
  authPersistencePath: '${dir.path}/auth'
);

分析

分析是一个数据库插件。它提供了关于应用程序使用情况和用户参与度的见解。其报告帮助你清晰地了解用户的使用行为，从而做出有关应用程序营销和性能优化的明智决策。

开始使用分析

在数据库中创建一个名为analytics的表：

create table public.analytics (
  name text not null,
  params json,
  user_id text,
  timestamp text
);

初始化分析插件：

SupabaseAnalyticsAddons.initialize();

记录事件

初始化之后，你可以使用SupabaseAnalyticsAddons.logEvent来记录事件。

你可以传递三个参数：

• 必填 name，事件名称。不允许有空格，如果有，它们会被替换为_。
• params，事件信息。虽然不是必须的，但最好有这些信息以便渲染图形。信息越多越好。
• userId，事件中的用户ID。如果未提供，则使用当前会话。

SupabaseAnalyticsAddons.logEvent('goal_completion', params: {
  'name': 'lever_puzzle',
});

认证事件

当用户登录或注册时，会自动触发user_session事件。

你可以通过在初始化时传递logUserSignIn: false来禁用自动日志记录。

user_session事件的参数字段包含一些有用的信息：

• country_code，用户的国家。
• os，用户的操作系统。这是一段字符串，表示操作系统或平台。这是由Platform.operatingSystem提供的。

内置事件

该插件提供了一系列内置事件，可以在分析器中进行分析：

崩溃报告

崩溃报告是一个可以帮助你追踪、优先处理并修复稳定性问题的工具，这些问题会影响应用程序的质量。

开始使用崩溃报告

在数据库中创建一个名为crashlytics的表：

create table public.crashlytics (
  id uuid DEFAULT gen_random_uuid() primary key not null,
  exception text not null,
  stackTraceElements json,
  timestamp text not null,
  info json
);

初始化崩溃报告插件：

SupabaseCrashlyticsAddons.initialize();

切换收集

你可以通过以下方式控制崩溃报告的收集状态：

import 'package:flutter/foundation.dart' show kDebugMode;

if (kDebugMode) {
  // 在日常开发过程中强制禁用收集。
  // 如果你想在应用中测试崩溃报告，可以暂时将其设置为true。
  SupabaseCrashlyticsAddons.collectionEnabled = false;
} else {
  // 当不在调试模式时处理崩溃报告的启用状态，
  // 例如允许用户选择是否参与崩溃报告。
}

记录错误

要记录带有自定义信息的错误，可以使用try/catch块包裹代码：

import 'package:flutter/foundation.dart' show kDebugMode;

try {
  // 可能抛出异常的代码
} catch (error, stacktrace) {
  SupabaseCrashlyticsAddons.recordError(
    error,
    stacktrace,
    reason: 'The user is very dumb', // 原因在这里
    fatal: false, // 错误是否致命，比如应用程序崩溃
    printDetails: kDebugMode, // 是否将错误打印到控制台。通常只在调试模式下才打印
  );
}

处理未捕获的错误

如果你正在使用Flutter，可以通过重新定义FlutterError.onError来捕获并报告框架中的所有错误：

FlutterError.onError = (details) {
  FlutterError.dumpErrorToConsole(details, forceReport: true);

  SupabaseCrashlyticsAddons.recordError(
    details.exceptionAsString(),
    details.stack,
    reason: details.context,
    printDetails: false,
  );
}

为了捕获程序中可能发生的其他异常，可以使用runZonedGuarded包装你的Dart程序：

void main() async {
  runZonedGuarded<Future<void>>(() async {
    // 你的其余代码在这里
    runApp(MyApp());
  }, (error, stacktrace) {
    SupabaseCrashlyticsAddons.recordError(error, stacktrace);
  });
}

功能和问题

请在问题跟踪器中提交功能请求和错误报告。

完整示例代码

import 'dart:async';

import 'package:supabase/supabase.dart';
import 'package:supabase_addons/supabase_addons.dart';

import 'credentials.dart';

void main() async {
  // 初始化插件
  await SupabaseAddons.initialize(
      client: SupabaseClient(SUPABASE_URL, SUPABASE_SECRET),
      appVersion: '0.1.0');
  SupabaseCrashlyticsAddons.initialize();

  // 运行应用
  await runZonedGuarded<Future<void>>(() async {
    if (SupabaseAuthAddons.auth.currentSession == null) {
      print('No user found. Signing the user in');
      await SupabaseAuthAddons.auth.signIn(email: EMAIL, password: PASSWORD);
    } else {
      print('User found on the storage.');
    }

    // 解注释以下行以禁用崩溃报告测试
    throw 'test crashlytics';

    // 释放插件资源
  }, (error, stacktrace) {
    SupabaseCrashlyticsAddons.recordError(error, stacktrace);
  });

  // 释放插件资源
  // SupabaseAddons.dispose();
  // exit(0)
}