@pluggableai/fanmeter-sdk

适用于NativeScript应用程序的Pluggable的Fanmeter插件

npm install @pluggableai/fanmeter-sdk

注意，对于Android而言，Fanmeter需要使用一个数据同步前台服务来与非侵入式传感器运动数据与Pluggable的服务器进行通信。从Android API 34开始，当发布使用此类服务的应用程序时，您必须填写一个政策声明，以说明为何需要此类服务。在Fanmeter的情况下，填写此类政策时，您将被问到问题“您的应用程序需要使用FOREGROUND_SERVICE_DATA_SYNC权限执行哪些任务？”。

在那里，您应该

在“其他任务”中选择其他选项；
提供以下视频链接

https://youtu.be/w4d7Pgksok0

提供以下描述

Fanmeter is an Android SDK, incorporated in this app, that uses a Data Sync foreground service to communicate non-intrusive sensor motion data with Pluggable's servers, which are used to quantify the engagement of the user in real-time. The foreground service must start as soons as the user opts to participate in the event (so that it can collect and communicate motion data) and must keep running until the user himself decides to terminate his/her participation.

先决条件 [与FCM集成]

在您使用此插件之前，应确保您的应用程序已集成NativeScript Firebase，然后集成Firebase云消息传递（FCM）。步骤非常简单易懂。

通过在项目的根目录中运行以下命令来安装@nativescript/firebase-core插件（一个在您的应用程序中初始化FirebaseApp的插件）（在使用任何其他Firebase服务之前，必须安装此插件）。

npm install @nativescript/firebase-core

Android配置 - 必须下载并添加一个配置文件到项目中

在Firebase控制台中，添加一个新的Android应用程序并输入项目详情。“Android包名”必须与本地项目包名匹配，该包名可在nativescript.config.ts文件中找到；
下载google-services.json文件并将其放置在项目中的以下位置：/App_Resources/Android/src/google-services.json。

iOS配置 - 为了允许iOS应用程序安全地连接到Firebase项目，必须下载并添加一个配置文件到项目中

在Firebase控制台中，添加一个新的iOS应用程序并输入您的项目详情。“Apple bundle ID”必须与您的本地项目bundle ID匹配。bundle ID可以在使用Xcode打开项目时的“通用”选项卡中找到，或者可以在nativescript.config.ts文件中找到；
下载GoogleService-Info.plist文件并将其放置在项目中的以下位置：/App_Resources/iOS/GoogleService-Info.plist；
然后，需要执行一系列步骤以获取一个auth key .p8文件（APNs身份验证密钥）以向Apple设备发送推送通知。如果您尚未创建APNs身份验证密钥，请确保在Apple开发者中心中创建一个。然后，在Firebase控制台中的项目中，选择齿轮图标，选择项目设置，然后选择“云消息传递”选项卡。在“Apple应用程序配置”下的APNs身份验证密钥处，单击上传按钮。浏览到您保存密钥的位置，选择它，然后单击打开。添加密钥的密钥ID（可在Apple开发者中心中找到）并单击上传。

实例化Firebase并初始化一个默认应用程序（例如，在/app/app.ts文件中）

import { firebase } from '@nativescript/firebase-core'
const defaultApp = await firebase().initializeApp()

现在您可以通过运行以下命令来安装消息模块：

npm install @nativescript/firebase-messaging

然后，通过导入 @nativescript/firebase-messaging 模块来添加 SDK。您应该在应用程序中仅导入此模块一次，理想情况下在主文件中（例如 app.ts 或 main.ts）。

import '@nativescript/firebase-messaging'

iOS 配置 - 在您可以通过 Firebase 收发消息之前，iOS 需要进一步的配置。阅读文档并按照以下步骤设置 iOS 与 Firebase 云消息。

注意，上述教程中的一步是不完整的。特别是，允许处理接收到的后台推送通知的步骤。您应该在 app/App_Resources/iOS/Info.plist 中打开它，并在底部添加以下代码

<key>UIBackgroundModes</key>
<array>
  	<string>fetch</string>
  	<string>location</string>
  	<string>remote-notification</string>
</array>
<key>NSLocationAlwaysUsageDescription</key>
<string>GPS is required to collect data to classify your celebration during the event! </string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>GPS is required to collect data to classify your celebration during the event! </string>

请注意，对于 Android 和 iOS 应用程序，都需要 GPS 权限，因为粉丝可以参加受地理位置限制的活动。
然后，您可以通过在项目的根目录的终端中运行以下命令来重新构建项目

ns clean
ns build android
ns build ios

注意：在 NativeScript 中，Firebase 消息必须在应用程序初始化过程中尽快调用，否则它将无法检测和处理通知以及通知点击。请确保您在应用程序初始化时尽快实现所有必需的方法。

Fanmeter 使用

在您的应用程序配置与 FCM 集成后，您就可以使用此插件来正确地与您的粉丝互动了！Fanmeter Native Script 插件是全自动的。

首先，通过在项目的根目录下运行以下命令来安装 Fanmeter 包，它会暴露三个新方法：

npm install @pluggableai/fanmeter-sdk

pluggableExecute 方法用于在用户点击通知时立即启动 SDK。它接受一组参数，包括：
- externalUserId，公司数据库中的用户标识符 - 可以是用户名、uuid 或其他；
- externalTokenId，单个智能手机标识符（允许在不同设备上使用相同的账户）；
- notificationData，一个包含来自通知的数据的映射；
- externalUserEmail，用户的电子邮件（可选）；
- fcmToken，FCM 标识符（对于完全自主的活动是必需的）；
- ticketNumber，用户的票号（可选）；
- ticketStand，用户所在的位置（可选）；
- notificationClassResponse，当用户点击通知时正在实例化的类的名称 - 例如："com.company.activities.SearchActivity"（null 打开默认视图）；
- log，启用额外的日志记录（可选）。
它还返回以下值
- 1：成功；
- -80：没有 GPS/PUSH 权限；-81：GPS 已禁用；-82：无效的事件坐标；
- -92：无效的许可证；-93：无效的事件；-94：无效的事件日期；-95：externalUserId 或 externalTokenId 为空；-96：获取事件详情失败；-97：无法启动后台服务。

...
import { FanmeterSdk } from '@pluggableai/fanmeter-sdk';
...

let EXTERNAL_USER_ID = 'your_user_id';
let EXTERNAL_TOKEN_ID = 'the_id_of_the_device';
let EXTERNAL_USER_EMAIL = '[email protected]';
let FCM_TOKEN = 'the_fcm_token';
let TICKET_NUMBER = null;
let TICKET_STAND = null;
let NOTIFICATION_CLASS_RESPONSE = null;
let FANMETER_LOG = true;

let COMPANY_NAME = 'your_company_name';
let LICENSE_KEY = 'your_company_key';

const defaultApp = async function () {
    console.log('defaultApp function started');
    await firebase().initializeApp();
    console.log('Firebase Initialized');
};
defaultApp();

// ...

const setFirebaseInits = async function () {

    firebase().messaging().onNotificationTap((message) => {
        let result = FanmeterSdk.pluggableExecute(
            EXTERNAL_USER_ID, 
            EXTERNAL_TOKEN_ID, 
            message.data, 
            EXTERNAL_USER_EMAIL, 
            FCM_TOKEN, 
            TICKET_NUMBER, 
            TICKET_STAND, 
            NOTIFICATION_CLASS_RESPONSE, 
            FANMETER_LOG
        );
        console.log('Fanmeter Notification Tap: ' + result);
    });

}

pluggableExecuteWithLocalNotification 方法用于告诉 SDK 向用户发送本地通知，这在 Android 中是必需的，以便在应用程序处于前台时启动推送通知。它接受一组参数，包括
- externalUserId，公司数据库中的用户标识符 - 可以是用户名、uuid 或其他；
- externalTokenId，单个智能手机标识符（允许在不同设备上使用相同的账户）；
- notificationData，一个包含来自通知的数据的映射；
- externalUserEmail，用户的电子邮件（可选）；
- fcmToken，FCM 标识符（对于完全自主的活动是必需的）；
- ticketNumber，用户的票号（可选）；
- ticketStand，用户所在的位置（可选）；
- notificationClassResponse，当用户点击通知时正在实例化的类的名称 - 例如："com.company.activities.SearchActivity"（null 打开默认视图）；
- log，启用额外的日志记录（可选）。
它还返回以下值
- 1：成功；
- -80：没有 GPS/PUSH 权限；-81：GPS 已禁用；-82：无效的事件坐标；
- -92：无效的许可证；-93：无效的事件；-94：无效的事件日期；-95：externalUserId 或 externalTokenId 为空；-96：获取事件详情失败；-97：无法启动后台服务。

// ...

const setFirebaseInits = async function () {
    // Allows you to always display notifications while the application is in the foreground.
    firebase().messaging().showNotificationsWhenInForeground = true

    firebase().messaging().onNotificationTap((message) => {
         // ...
    });

    firebase().messaging().onMessage(async (remoteMessage) => {
        let result = FanmeterSdk.pluggableExecuteWithLocalNotification(
            EXTERNAL_USER_ID, 
            EXTERNAL_TOKEN_ID, 
            remoteMessage.data, 
            EXTERNAL_USER_EMAIL, 
            FCM_TOKEN, 
            TICKET_NUMBER, 
            TICKET_STAND, 
            NOTIFICATION_CLASS_RESPONSE, 
            FANMETER_LOG
        );
        console.log('Fanmeter Message: ' + result);
  });

}

pluggableLaunchFanmeterView 方法用于告诉 SDK 启动 Fanmeter 原生视图。例如，它可以与公司的应用程序中的一个按钮关联，将用户重定向到 Fanmeter 原生视图，允许没有通知权限的用户参加活动。它将以与当前日期最接近的事件打开 Fanmeter 视图，接受一组参数，包括
- companyName，请求启动服务的公司名称；
- licenseKey，请求启动服务的公司密钥。
- externalUserId，公司数据库中的用户标识符 - 可以是用户名、uuid 或其他；
- externalTokenId，单个智能手机标识符（允许在不同设备上使用相同的账户）；
- externalUserEmail，用户的电子邮件（可选）；
- fcmToken，FCM 标识符（对于完全自主的活动是必需的）；
- ticketNumber，用户的票号（可选）；
- ticketStand，用户所在的位置（可选）；
- log，启用额外的日志记录（可选）。
它还返回以下值
- 1：成功；
- -80：没有 GPS/PUSH 权限；-81：GPS 已禁用；-82：无效的事件坐标；
- -92：无效的许可证；-93：无效的事件；-94：无效的事件日期；-95：externalUserId 或 externalTokenId 为空；-96：获取事件详情失败；-97：无法启动后台服务。

// ...

launchNativeView() {
    let result = FanmeterSdk.pluggableLaunchFanmeterView(
        COMPANY_NAME, 
        LICENSE_KEY, 
        EXTERNAL_USER_ID, 
        EXTERNAL_TOKEN_ID, 
        EXTERNAL_USER_EMAIL, 
        FCM_TOKEN, 
        TICKET_NUMBER, 
        TICKET_STAND, 
        FANMETER_LOG
    );
    console.log('Launch Fanmeter Native View: ' + result);
}

订阅特定主题同样强制，以确保用户能够收到事件通知。

// Subscribe user to a specific topic.
firebase().messaging().subscribeToTopic('football_senior').then(() => {
    console.log('Subscribed to topic: football_senior')
});

其他重要方法包括请求用户权限以便能够发送通知和请求GPS权限。此外，获取用户令牌并监听变化以获取用户FCM_TOKEN并在变化时更新它。

// Request user permission
async function requestUserPermission() {
    const authStatus = await firebase()
      .messaging()
      .requestPermission({
          ios: {
              alert: true
          }
      })
    const enabled =
      authStatus === AuthorizationStatus.AUTHORIZED ||
      authStatus === AuthorizationStatus.PROVISIONAL

    console.log('Authorization status: ', authStatus)
    if (enabled) {
        const didRegister = await firebase().messaging().registerDeviceForRemoteMessages().then(() => {
            // Init Firebase and calling the below methods
            setFirebaseInits();
        });
    }
}

requestUserPermission()

// Get user token 
firebase().messaging().getToken().then(token => {
    console.log('User token: ', token)
    FCM_TOKEN = token
    //saveTokenToDatabase(token)
});

// Listen to user token changes
firebase().messaging().onToken(token => {
    console.log('User token changed to: ', token)
    FCM_TOKEN = token
    //saveTokenToDatabase(token)
});

注意：对于Android，要自定义使用的通知图标，只需在Android的drawable文件夹中添加所需的图标，并命名为ic_push_app_icon。否则，将使用默认图标，该图标与您的应用程序无关。

许可证

重新分发和使用源代码和二进制代码，无论是否修改，只要满足以下条件

源代码的重新分发必须保留上述版权声明、本条件列表和以下免责声明。
二进制形式的重新分发必须在文档和/或其他提供的材料中复制上述版权声明、本条件列表和以下免责声明。

@pluggableai/fanmeter-sdk

先决条件 [与FCM集成]

Fanmeter 使用

更多信息

许可证