Flutter蓝牙设备管理插件beaconsmind_sdk的使用

Flutter蓝牙设备管理插件beaconsmind_sdk的使用

概述

beaconsmind_sdk 是一个用于 Flutter 应用的蓝牙设备管理插件。它可以帮助开发者轻松集成蓝牙设备（如信标）的管理功能，包括初始化、认证、通知处理以及信标设备的监听等。

前置条件

作为 Beaconsmind 客户端，会获得一个由 Beaconsmind 提供的服务环境，该环境包含 Beaconsmind 提供的所有服务。要正确访问 Beaconsmind API 和使用 SDK，需要提供环境的主机名。

示例：

https://adidas.bms.beaconsmind.com

请与 Beaconsmind 支持团队联系以获取有效环境和主机名的相关信息。

1. 安装

在项目的 pubspec.yaml 文件中添加 beaconsmind_sdk 依赖项：

dependencies:
  beaconsmind_sdk: ^x.x.x

然后运行以下命令安装：

flutter pub get

2. 平台设置

iOS

请遵循 此指南 进行 iOS 平台的配置。

Android

请遵循 此指南 进行 Android 平台的配置。

3. 初始化 SDK

调用 initialize() 方法来初始化 SDK，并尝试检索已登录用户。

import 'package:beaconsmind_sdk/beaconsmind_sdk.dart';

void initializeSDK() async {
  await Beaconsmind.instance.initialize(
    hostname: 'https://test-develop-suite.azurewebsites.net/', // 替换为实际的主机名
    appVersion: '1.0.0',
    androidNotificationBadgeName: 'ic_beacons',
    androidNotificationChannelName: 'beaconsmind',
    androidNotificationTitle: 'Beaconsmind sdk demo',
    androidNotificationText: 'Listening to beacons',
  );
}

4. 权限管理

beaconsmind_sdk 需要蓝牙和位置权限（whenInUse 或 always）来检测附近的信标设备，还需要通知权限来发送优惠信息。

使用 permission_handler 请求权限

可以考虑使用 permission_handler 包来请求必要的权限。

示例代码

import 'package:permission_handler/permission_handler.dart';

Future<void> requestPermissions() async {
  await Permission.bluetooth.request();
  await Permission.location.request();
  await Permission.notification.request();
}

测试模式

为了简化测试，可以使用 Beaconsmind.initializeDevelop() 方法一次性请求所有必需的权限。

5. 用户认证

使用 Beaconsmind 认证机制

如果客户数据存储在 Beaconsmind 后端，可以使用 UserManager.login() 方法进行用户认证。

登录现有用户

try {
  final user = await Beaconsmind.instance.login(
    username: _usernameController.text,
    password: _passController.text,
  );
  print('登录成功: $user');
} catch (e) {
  final snackBar = SnackBar(
    content: Text(e.toString()),
  );
  ScaffoldMessenger.of(context).showSnackBar(snackBar);
}

注册新用户

try {
  final user = await Beaconsmind.instance.signup(
    username: _emailController.text,
    firstName: _firstNameController.text,
    lastName: _lastNameController.text,
    password: _passController.text,
    confirmPassword: _passConfirmController.text,
  );
  print('注册成功: $user');
  Navigator.of(context).pop();
} catch (e) {
  final snackBar = SnackBar(
    content: Text(e.toString()),
  );
  ScaffoldMessenger.of(context).showSnackBar(snackBar);
}

使用自定义认证机制

如果客户数据存储在客户端后端，则需要在使用 Beaconsmind API 前完成认证。每次用户认证完成后，调用 Beaconsmind.instance.importAccount() 方法将基本客户数据发送到 Beaconsmind。

6. 监听 SDK 状态变化

SDK 提供了一个 Stream 来监听用户登录/登出状态的变化。

Beaconsmind.instance.contextEvents().listen((BeaconsmindSdkContext? event) {
  if (event == null) {
    print('用户未登录');
  } else {
    print('用户已登录: ${event.username}');
  }
});

7. 通知处理

SDK 使用 APNS（Apple Push Notification Service）处理 iOS 通知，使用 Firebase 处理 Android 通知。

设置设备令牌

根据 Beaconsmind 支持团队的要求选择合适的推送通知提供商。

如果 FCM 用于 Android 和 iOS

String? fcmToken = await FirebaseMessaging.instance.getToken();
await Beaconsmind.registerDeviceToken(
  token: fcmToken,
  platformType: PlatformType.fcm,
);

如果 FCM 用于 Android，APNS 用于 iOS

if (Platform.isAndroid) {
  final fcmToken = await FirebaseMessaging.instance.getToken();
  if (fcmToken != null) {
    await Beaconsmind.instance.registerDeviceToken(
      deviceToken: fcmToken,
      platformType: PlatformType.fcm,
    );
  }
}

if (Platform.isIOS) {
  final apnsToken = await getApnsToken();
  if (apnsToken != null) {
    await Beaconsmind.instance.registerDeviceToken(
      deviceToken: apnsToken,
      platformType: PlatformType.apns,
    );
  }
}

处理多个推送通知提供商

如果同时使用多个推送通知包（例如 moengage_flutter 和 firebase_messaging），需要通过代理服务转发通知。

实现步骤

1. 添加 FirebaseMessagingServiceProxy.kt 文件到 Android 项目。
2. 在 FirebaseMessagingServiceProxy 文件中更新 messagingServices 列表。
3. 在 AndroidManifest.xml 中注册代理服务。

8. 优惠处理

获取优惠信息

// 获取单个优惠
final offer = await Beaconsmind.instance.loadOffer(id: 123);

// 获取当前活跃的优惠列表
final offers = await Beaconsmind.instance.loadOffers();

与优惠交互

// 标记优惠为已接收
await Beaconsmind.instance.markOfferAsReceived(offerId: 123);

// 标记优惠为已阅读
await Beaconsmind.instance.markOfferAsRead(offerId: 123);

// 标记优惠为已兑换
await Beaconsmind.instance.markOfferAsRedeemed(offerId: 123);

9. 信标设备操作

信标设备交互

// 开始监听信标设备
await Beaconsmind.instance.startListeningBeacons();

// 停止监听信标设备
await Beaconsmind.instance.stopListeningBeacons();

// 获取信标设备摘要信息
final summary = await Beaconsmind.instance.getBeaconsSummary();

更多信标设备相关信息

• iOS 信标设备设置
• Android 信标设备设置

10. 资源释放

在应用退出时，调用 dispose() 方法清理资源并防止内存泄漏。

Beaconsmind.instance.dispose();

平台特定注意事项

Android

如果使用 ProGuard 且 SDK 版本低于 1.7.0，请在 proguard-rules.pro 文件中添加以下规则：

-keep class com.beaconsmind.api.models** { *; }