Flutter插件fanmeter的使用方法

Flutter插件fanmeter的使用方法

Pluggable’s Fanmeter Plugin for Flutter apps

Fanmeter插件负责在任何移动应用中启用Fanmeter。这是一个简单的即插即用插件，提供了一组方法，可以让用户参与诸如“最佳粉丝”或“超级粉丝”等激活。

Fully-automatized vs Manual Fanmeter

有两种可能的集成方式。一种是全自动化的，并使用一个默认的原生视图来启动用户参与Fanmeter——它还会在活动开始和结束时自动发送和交付推送通知。另一方面，如果你想创建自己的Fanmeter视图，则需要采用手动方式。

全自动化的Fanmeter

你希望一切自动化（包括默认的Fanmeter视图）。你应该也与FCM集成以处理接收到的通知，以便启动活动（总结来说，你需要使用execute、launchFanmeterNotification和可选的launchFanmeterView方法）；

手动的Fanmeter

你想自己处理条件并开发自己的视图（只需调用startService、stopService和isServiceRunning方法）。

预先条件

元数据

对于Android，需要推送权限，这样当一个前台服务正在运行时，会向用户显示通知。另外，需要注意的是，位置权限对于用户参与地理位置受限的事件是必需的。因此，你需要请求这些权限。

对于iOS，添加“后台模式”功能并启用“位置更新”。此外，你必须打开你的Info.plist文件并在文件底部添加以下代码：

<key>UIBackgroundModes</key>
<array>
    <string>fetch</string>
    <string>location</string>
    <string>remote-notification</string>
</array>
<key>NSLocationTemporaryUsageDescriptionDictionary</key>
<dict>
    <key>PreciseLocationRequired</key>
    <string>访问精确位置是在地理位置受限的事件期间必需的！</string>
</dict>
<key>NSLocationAlwaysUsageDescription</key>
<string>位置访问是为了参与地理位置受限的事件！</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>位置访问是为了参与地理位置受限的事件！</string>

请注意，对于仅Android，Fanmeter需要使用一个“数据同步前台服务”来与Pluggable的服务器通信非侵入性传感器数据。自Android API 34起，当你发布一个使用此类服务的应用时，你被要求填写一个“策略声明”，你必须证明这种服务的必要性。在Fanmeter的情况下，当你填写此类政策时，会被问到“什么任务要求您的应用使用FOREGROUND_SERVICE_DATA_SYNC权限？”。

在那里，你应该：

  1. 在其他任务中选择选项“其他”；
  2. 提供以下视频链接：
    https://youtu.be/w4d7Pgksok0
  3. 提供以下描述：
    Fanmeter是一款Android SDK，集成在这个应用中，使用了一个数据同步前台服务来与Pluggable的服务器通信非侵入性传感器数据，这些数据用于实时量化用户的参与度。前台服务必须在用户决定参与事件时立即启动（以便收集和通信数据），并且必须一直运行直到用户自己决定终止其参与。

推送通知

在使用此插件之前，如果你想要全自动化体验，你应该确保你的应用已经集成了Firebase Cloud Messaging（FCM），以便你的应用可以接收推送通知。

  1. 首先安装FlutterFire，这是一个工具，可以自动配置你的应用使用firebase；
  2. 然后，安装firebase_messaging，这是一个跨平台的消息解决方案；
  3. 然后，按照这些步骤开始在项目中使用Cloud Messaging包；
  4. 在iOS上集成Cloud Messaging插件需要在设备接收到消息之前进行额外设置。完整的步骤在这里，但要使消息传递生效，需要以下前提条件：
    • 你必须有一个有效的Apple开发者账户；
    • 你必须有一个物理iOS设备来接收消息。
  5. 对于iOS：
    • 如果你使用Swift，在你的AppDelegate.swift中确保添加了第一段代码；
    • 如果你使用Objective-C，将第二段代码添加到你的appdelegate.m文件中。

注意: FCM通过APNs不适用于iOS模拟器。为了接收消息和通知，需要实际设备。对于Android也是如此。

在Flutter应用中设置Fanmeter插件

安装插件

在配置好应用以集成FCM之后，你可以使用此插件正确地与你的粉丝互动！要在项目的根目录下安装插件，运行：

flutter pub add fanmeter

或者运行flutter pub upgrade以更新pubspec.yaml文件中列出的所有依赖项的最新兼容版本。

注意，对于Android，如果要自定义使用的通知图标，只需将所需的图标添加到Android的drawable文件夹中，并命名为ic_push_app_icon。否则，将会使用一个与你的应用无关的默认图标。

方法初始化

initialize方法对于全自动和手动场景都是必需的。它负责初始化SDK，并且必须在使用任何其他方法之前调用（一种可能的方法是在主应用程序进程中调用它）。

import 'package:fanmeter/fanmeter.dart';

// ...

String COMPANY_NAME = 'your_company_name';
String COMPANY_KEY = 'your_company_key';
String EXTERNAL_USER_ID = 'your_user_id';
String EXTERNAL_TOKEN_ID = 'the_id_of_the_device';
String EXTERNAL_USER_EMAIL = 'email@domain.com';
String FCM_TOKEN = 'the_fcm_token';
String TICKET_NUMBER = 't-1234';
String TICKET_STAND;
String REGULATION_URL;
String NOTIFICATION_CLASS_RESPONSE;
bool FANMETER_LOG = true;

final _fanmeterPlugin = Fanmeter();

// 当Fanmeter SDK初始化时，它初始化所有公司和用户数据。
final result = await _fanmeterPlugin.initialize(
    COMPANY_NAME,
    COMPANY_KEY,
    EXTERNAL_USER_ID,
    EXTERNAL_TOKEN_ID,
    EXTERNAL_USER_EMAIL,
    FCM_TOKEN,
    TICKET_NUMBER,
    TICKET_STAND,
    REGULATION_URL,
    FANMETER_LOG
);

其中：

  • COMPANY_NAME，是你的公司在Fanmeter中的名称；
  • COMPANY_KEY，是你的公司的许可证密钥；
  • EXTERNAL_USER_ID，是在你的数据库中的用户标识符（可以是用户名、uuid等）；
  • EXTERNAL_TOKEN_ID，是个别智能手机标识符（允许同一个账户在不同设备上使用）；
  • EXTERNAL_USER_EMAIL，是用户的电子邮件。可为空；
  • FCM_TOKEN，是用户的FCM令牌id。可为空；
  • TICKET_NUMBER，是用户的票号 - 用于额外分析。可为空；
  • TICKET_STAND，是用户所在的看台 - 用于额外分析。可为空；
  • REGULATION_URL，是事件的规则URL。可为空；
  • FANMETER_LOG，启用额外日志记录。

全自动化的Fanmeter

在初始化插件之后，你现在可以开始调用Fanmeter。特别是，如果你希望自动化整个过程，这个库提供了三个方法，必须按照以下方式调用。具体来说：

  • execute，在用户点击通知时启动SDK的默认Fanmeter视图；
  • launchFanmeterNotification，在Android应用处于前台状态时向用户发送本地通知；
  • launchFanmeterView，启动SDK的默认Fanmeter视图。它可以与你的应用中的按钮或横幅关联，将用户重定向到Fanmeter的原生视图，允许没有通知权限的用户参与活动。它将打开当前日期最近的事件的Fanmeter视图。

execute方法用于后台进程，将打开默认的Fanmeter视图给用户。另一方面，launchFanmeterNotification方法在Android应用处于前台状态时发送本地通知。例如，可以在.dart文件中使用以下代码：

import 'package:fanmeter/fanmeter.dart';

// ...

/// 在前台接收推送。
void _firebaseMessagingForegroundHandler(RemoteMessage message) async {
    if(message.notification != null) {
        Map<String, String> notificationData = message.data.map((key, value) => MapEntry(key, value.toString()));
        final result = await _fanmeterPlugin.launchFanmeterNotification(
            notificationData,  
            NOTIFICATION_CLASS_RESPONSE
        );
    }	
}

/// 处理用户点击推送。
void _handlePushTap(RemoteMessage message) async {
    Map<String, String> notificationData = message.data.map((key, value) => MapEntry(key, value.toString()));
    final result = await _fanmeterPlugin.execute(
        notificationData, 
        NOTIFICATION_CLASS_RESPONSE
    );
}

Future<void> setupInteractedMessage() async {
    // 获取任何导致应用程序从终止状态打开的消息。
    RemoteMessage? initialMessage = await FirebaseMessaging.instance.getInitialMessage();
    if(initialMessage != null) {
        _handlePushTap(initialMessage);
    }
    // 还处理应用程序在后台时的任何交互。
    FirebaseMessaging.onMessageOpenedApp.listen(_handlePushTap);
}

@override
void initState() {
    // ...

    // 监听前台推送。
    FirebaseMessaging.onMessage.listen(_firebaseMessagingForegroundHandler);

    // 处理通知点击。
    setupInteractedMessage();

    // ...
}

其中：

  • notificationData，是从通知中接收到的远程数据；
  • NOTIFICATION_CLASS_RESPONSE，当用户点击通知时实例化的类的名称 - 例如：“com.company.activities.SearchActivity”（空值打开应用的默认视图）。

最后，launchFanmeterView方法应该在按钮点击时调用，将用户重定向到Fanmeter的默认视图。它可以与应用中的按钮/横幅关联，将用户重定向到Fanmeter的原生视图，允许没有通知权限的用户参与活动。eventTitle参数是可选的。如果提供，它将打开指定事件的Fanmeter视图。否则，它将打开当前日期最近的事件的Fanmeter视图。

final result = await _fanmeterPlugin.launchFanmeterView(eventTitle);

这些函数返回以下值：

  • 1，成功；
  • -80，无GPS/推送权限；
  • -81，GPS禁用；
  • -82，无效的事件坐标；
  • -89，SDK未初始化；
  • -91，无效的通知数据；
  • -92，无效的公司许可证；
  • -93，无效的事件；
  • -94，事件现在未发生；
  • -95，无效的外部用户数据；
  • -96，未能获取事件数据；
  • -97，未能启动Fanmeter服务；

还需要订阅用户到FCM主题，以便他们可以接收事件通知。这可以通过以下方式完成：

Future<void> setupToken() async {
    // 每次应用程序加载时获取令牌。
    FCM_TOKEN = await FirebaseMessaging.instance.getToken();
    // 订阅特定主题。
    await FirebaseMessaging.instance.subscribeToTopic('football_senior');
}

手动的Fanmeter

如果你想要完全控制并实现自己的UI，这个库提供了三个方法，必须按照以下方式调用。具体来说：

  • startService，启动Fanmeter服务，使你的客户端设备在特定事件期间启用Fanmeter；
  • stopService，停止Fanmeter服务。即使用户没有明确停止服务，它也会在事件结束后自动停止。这如果成功则返回1，否则返回错误码；
  • isServiceRunning，用于检查当前Fanmeter服务的状态。如果服务正在运行则返回1，否则返回0。

startService方法用于启动Fanmeter服务，应该按以下方式调用（例如，与特定按钮关联）：

// 你应该管理事件以编程方式获取它们的名称，而不是硬编码字符串。
String EVENT_TITLE = "Round 1 - 2024/2025 Season"
final result = await _fanmeterPlugin.startService(
    eventTitle, 
    NOTIFICATION_CLASS_RESPONSE
);

其中：

  • EVENT_TITLE，是用户在启动服务时将参与的事件的名称；
  • NOTIFICATION_CLASS_RESPONSE，当用户点击通知时实例化的类的名称 - 例如：“com.company.activities.SearchActivity”（空值打开应用的默认视图）。

此方法返回以下值：

  • 1，成功；
  • -80，无GPS/推送权限；
  • -81，GPS禁用；
  • -82，无效的事件坐标；
  • -89，SDK未初始化；
  • -91，无效的通知数据；
  • -92，无效的公司许可证；
  • -93，无效的事件；
  • -94，事件现在未发生；
  • -95，无效的外部用户数据；
  • -96，未能获取事件数据；
  • -97，未能启动Fanmeter服务；

stopService方法用于停止Fanmeter服务（可以与前面的方法切换）。即使用户没有明确停止服务，它也会在事件结束时自动停止。这如果成功则返回1，否则返回错误码。

final result = await _fanmeterPlugin.stopService();

最后，isServiceRunning方法用于检查当前Fanmeter服务的状态。这如果服务正在运行则返回1，否则返回0。

final result = await _fanmeterPlugin.isServiceRunning();

其他信息

还有其他重要方法是请求用户权限以便能够发送通知和请求GPS权限。还要获取用户令牌并监听更改以获取用户的FCM_TOKEN并在更改时更新它。

Future requestPermission() async {
    FirebaseMessaging messaging = FirebaseMessaging.instance;
    // 请求推送权限。
    NotificationSettings settings = await messaging.requestPermission(
        alert: true,
        announcement: false,
        badge: true,
        carPlay: false,
        criticalAlert: false,
        provisional: true,
        sound: true,
    );
    print('User granted permission: ${settings.authorizationStatus}');
    // 前台推送展示。
    await messaging.setForegroundNotificationPresentationOptions(
        alert: true,
        badge: true,
        sound: true,
    );	
}

Future<void> updateFcmToken() async {
    // 每次应用程序加载时获取令牌。
    FCM_TOKEN = await FirebaseMessaging.instance.getToken();
}

更多关于Flutter插件fanmeter的使用方法的实战教程也可以访问 https://www.itying.com/category-92-b0.html

回到顶部