fanmeter

Description:

fanmeter

Pluggable's Fanmeter Plugin for Flutter apps #
Fanmeter's Flutter plugin for Flutter apps. This plugins allows you to create fanmeter events. You have two ways of doing it:


You want everything automated and, so, you'll need to integrate with FCM to handle the received notifications that start the event (see the next section and you'll need to use the fanmeterExecute, fanmeterExecuteWithLocalNotification and, optinally, the fanmeterLaunchFanmeterView method);


You want to handle the conditions yourself (without Fanmeter's notifications). You can skip the next section (the Pre-conditions one) and start calling the fanmeterStartService, fanmeterStopService, and fanmeterIsServiceRunning methods.


Nonetheless, note that for Android, push permission is required so that a notification is shown to the user so that he knows that a foreground service is running. Also, note that the GPS permission is needed for the fans to participate in the geo-restricted events.
Hence, you need to ask for such permission in Android. For iOS, add the Background Modes capability and enable Location Updates. Also, you must open your Info.plist file and add something the following code at the bottom:
<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>
copied to clipboard
Note that, for Android only, Fanmeter is required to use a Data Sync foreground service to communicate non-intrusive sensor motion data with Pluggable's server. Since API 34 of Android, when publishing an app that uses such services, you are required to fill a Policy Declaration where you must justify the need for such services. In Fanmeter's case, when filling such policy, you will be asked the question "What tasks require your app to use the FOREGROUND_SERVICE_DATA_SYNC permission?".
There, you should:

Select the option OTHER in Other tasks;
Provide the following video link:

https://youtu.be/w4d7Pgksok0
copied to clipboard

Provide the following description:

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.
copied to clipboard
Pre-conditions [Integrate with FCM] #
Before using this plugin you should guarantee that your app already integrates with Firebase Cloud Messaging so that your app can receive push notifications.


First install FlutterFire, a tool which automatically configures your app to use firebase;


Then, install firebase_messaging, a cross-platform messaging solution;


Then, to start using the Cloud Messaging package within your project follow these steps;


Integrating the Cloud Messaging plugin on iOS requires additional setup before your devices receive messages. The full steps are available here, but the following prerequisites are required to be able to enable messaging:

You must have an active Apple Developer Account;
You must have a physical iOS device to receive messages.



Also for iOS:

If you are using swift, in your AppDelegate.swift make sure you have added the first code;
If you're using flutter with objective-c, add the second code to your appdelegate.m file.

import Firebase

FirebaseApp.configure() //add this before the code below
GeneratedPluginRegistrant.register(with: self)
copied to clipboard
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
[FIRApp configure]; //add this at the top
// ...
}
copied to clipboard


NOTE: FCM via APNs does not work on iOS Simulators. To receive messages & notifications a real device is required. The same is recommended for Android.
Fanmeter Usage #
After configuring your app to integrate with FCM, you are ready to use this plugin to properly engage with your fans! To install the plugin just run, in the root of the project:
flutter pub add fanmeter
* Or run flutter pub upgrade to update to the latest compatible versions of all the dependencies listed in the pubspec.yaml file.
* For Android, to customize the used notification icon, just add the desired icon in the Android's drawable folder and name it ic_push_app_icon. Otherwise, a default icon, not related to your app, will be used.
Fully-automated Fanmeter #
If you want to automate the entire process, this library exposes two mandatory methods, which can be imported and used in your main.dart files as demonstrated in the next lines.


The fanmeterExecute method is used to launch the SDK as soon as a notification is tapped by the user. The fanmeterExecuteWithLocalNotification method is used to tell the SDK to launch a local notification to the user, which is required by Android to launch push notifications when the app is in the foreground. Both accept the same set of parameters:

externalUserId, the user identifier in the company's db - can be the username, the uuid, or other;
externalTokenId, the individual smartphone identifier (allows for same accounts in different devices);
notificationData, a map containing data coming from the notification;
externalUserEmail, the user's email (optional);
fcmToken, the FCM token id (mandatory for autonomous events);
ticketNumber, the ticket number of the user (optional);
ticketStand, the stand where the given user is (optional);
notificationClassResponse, the name of the class that is being instantiated when the user clicks the notification - example: "com.company.activities.SearchActivity" (null opens a default view);
log, enables additional logging (optional).

It also returns the following values:

1: SUCCESS;
-80: No GPS/PUSH Permissions; -81: GPS Disabled; -82: Invalid event coordinates;
-92: Invalid License; -93: Invalid Event; -94: Invalid event dates; -95: externalUserId or externalTokenId are empty; -96: Failed to get event details; -97: Failed to start background service.

These should be called as follows:
import 'package:fanmeter/fanmeter.dart';

//...

final _fanmeterPlugin = Fanmeter();

String EXTERNAL_USER_ID = 'your_user_id';
String EXTERNAL_TOKEN_ID = 'the_id_of_the_device';
String? EXTERNAL_USER_EMAIL = '[email protected]';
String? FCM_TOKEN = 'the_fcm_token';
String? TICKET_NUMBER = 'T-1234';
String? TICKET_STAND;
String? NOTIFICATION_CLASS_RESPONSE;
bool FANMETER_LOG = true;

String COMPANY_NAME = 'your_company_name';
String COMPANY_LICENSE_KEY = 'your_company_key';
String EVENT_TITLE = 'eventTitle';

/// Receive pushes while in the foreground.
void _firebaseMessagingForegroundHandler(RemoteMessage message) async {
if (message.notification != null) {
Map<String, String> notificationData = message.data.map((key, value) => MapEntry(key, value.toString()));
final fanmeterExecuteSDKWithLocalNotification = await Fanmeter().fanmeterExecuteWithLocalNotification(
EXTERNAL_USER_ID,
EXTERNAL_TOKEN_ID,
notificationData,
EXTERNAL_USER_EMAIL,
FCM_TOKEN,
TICKET_NUMBER,
TICKET_STAND,
NOTIFICATION_CLASS_RESPONSE,
FANMETER_LOG
);
print("[ExecuteSDKWithLocalNotification]: $fanmeterExecuteSDKWithLocalNotification");
}
}

/// Handle push tap by the user.
void _handlePushTap(RemoteMessage message) async {
Map<String, String> notificationData = message.data.map((key, value) => MapEntry(key, value.toString()));
final fanmeterExecute = await Fanmeter().fanmeterExecute(
EXTERNAL_USER_ID,
EXTERNAL_TOKEN_ID,
notificationData,
EXTERNAL_USER_EMAIL,
FCM_TOKEN,
TICKET_NUMBER,
TICKET_STAND,
NOTIFICATION_CLASS_RESPONSE,
FANMETER_LOG
);
print("[ExecuteSDK]: $fanmeterExecute");
}

Future<void> setupInteractedMessage() async {
// Get any messages which caused the application to open from a terminated state.
RemoteMessage? initialMessage = await FirebaseMessaging.instance.getInitialMessage();
if (initialMessage != null) {
_handlePushTap(initialMessage);
}

// Also handle any interaction when the app is in the background.
FirebaseMessaging.onMessageOpenedApp.listen(_handlePushTap);
}

@override
void initState() {
/...

// Listen for foreground pushes
FirebaseMessaging.onMessage.listen(_firebaseMessagingForegroundHandler);

// Handle notification tap.
setupInteractedMessage();

/...
}
copied to clipboard


Also, the fanmeterLaunchFanmeterView method is used to tell the SDK to launch the Fanmeter native view. For example, it can be associated with a button in the company's app, redirecting the user to the Fanmeter native view, allowing users without notification permissions to participate in the event. It will open the Fanmeter view with the event with the closest date to the current date, accepting a set of parameters, including:

companyName, the name of the company requesting to start the service;
licenseKey, the company key requesting to start the service;
externalUserId, the user identifier in the company's db - can be the username, the uuid, or other;
externalTokenId, the individual smartphone identifier (allows for same accounts in different devices);
externalUserEmail, the user's email (optional);
fcmToken, the FCM token id (mandatory for fully autonomous events);
ticketNumber, the ticket number of the user (optional);
ticketStand, the stand where the given user is (optional);
log, enables additional logging (optional).

It also returns the following values:

1: SUCCESS;
-80: No GPS/PUSH Permissions; -81: GPS Disabled; -82: Invalid event coordinates;
-92: Invalid License; -93: Invalid Event; -94: Invalid event dates; -95: externalUserId or externalTokenId are empty; -96: Failed to get event details; -97: Failed to start background service.

//...

Future<void> launchView() async {
final result = await _fanmeterPlugin.fanmeterLaunchFanmeterView(
COMPANY_NAME,
COMPANY_LICENSE_KEY,
EXTERNAL_USER_ID,
EXTERNAL_TOKEN_ID,
EXTERNAL_USER_EMAIL,
FCM_TOKEN,
TICKET_NUMBER,
TICKET_STAND,
FANMETER_LOG
);
print("[Launch Fanmeter View]: $result");
}

//...
copied to clipboard


You also need to know the FCM token ID associated with each user device. It's equally mandatory to subscribe the user to a specific topic so that they can receive event notifications:
Future<void> setupToken() async {
// Get the token each time the application loads
FCM_TOKEN = await FirebaseMessaging.instance.getToken();
// Subscribe to topic
await FirebaseMessaging.instance.subscribeToTopic('football_senior');
}
copied to clipboard


OWN-UI Fanmeter #
If you want to integrate Fanmeter in your own UI, you can use the fanmeterStartService, fanmeterStopService, and fanmeterIsServiceRunning methods. These methods are exposed by the library to handle user sensor data collection during an event and can be used, if needed, as follows.


You should call the fanmeterStartService method to let the SDK enable sensor data collection for your client's device during a particular event. It accepts a set of parameters, including:

companyName, the name of the company requesting to start the service;
licenseKey, the license key of the company requesting to start the service;
eventTitle, the event name;
externalUserId, the user identifier in the company's db - can be the username, the uuid, or other;
externalTokenId, the individual smartphone identifier (allows for same accounts in different devices);
externalUserEmail, the user's email (optional);
fcmToken, the FCM token id (optional);
ticketNumber, the ticket number of the user (optional);
ticketStand, the stand where the given user is (optional);
notificationClassResponse, he name of the class that is being instantiated when the user clicks the notification - example: "com.pluggableai.activities.SearchActivity" (optional);
log, enables additional logging (optional).

It also returns the following values:

1: SUCCESS;
-80: No GPS/PUSH Permissions; -81: GPS Disabled; -82: Invalid event coordinates;
-92: Invalid License; -93: Invalid Event; -94: Invalid event dates; -95: externalUserId or externalTokenId are empty; -96: Failed to get event details; -97: Failed to start background service.

//...

Future<void> executeStartService() async {
final result = await _fanmeterPlugin.fanmeterStartService(
COMPANY_NAME,
COMPANY_LICENSE_KEY,
EVENT_TITLE,
EXTERNAL_USER_ID,
EXTERNAL_TOKEN_ID,
EXTERNAL_USER_EMAIL,
FCM_TOKEN,
TICKET_NUMBER,
TICKET_STAND,
NOTIFICATION_CLASS_RESPONSE,
FANMETER_LOG
);
print("[Execute Start Service]: $result");
}

//...
copied to clipboard


You should call the fanmeterStopService method to let the SDK disable sensor data collection for your client's device during a particular event. This returns 1, if success, otherwise an error code. For that, you must do as follows:
Future<void> executeStopService() async {
final result = await _fanmeterPlugin.fanmeterStopService(FANMETER_LOG);
print("[Execute Stop Service]: $result");
}
copied to clipboard


The method fanmeterIsServiceRunning is used to check the current status of the service. This returns 1, if the service is running, otherwise 0.
Future<void> isFanmeterRunning() async {
final result = await _fanmeterPlugin.fanmeterIsServiceRunning();
print("[Is Fanmeter Running]: $result");
}
copied to clipboard


Generics #
Other important methods are to request user permission to be able to send notifications and request GPS permission. Also, get the user token and listen for changes to get the user FCM_TOKEN and update it when it changes.
```
Future requestPermission() async {
FirebaseMessaging messaging = FirebaseMessaging.instance;
// Ask for push permissions
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}');
// Presentation for foreground push
await messaging.setForegroundNotificationPresentationOptions(
alert: true,
badge: true,
sound: true,
);
}

Future<void> setupToken() async {
// Get the token each time the application loads
FCM_TOKEN = await FirebaseMessaging.instance.getToken();
}
```
copied to clipboard
More info #


FCM via APNs does not work on iOS Simulators. To receive messages and notifications a real device is required. The same is recommended for Android.


For full compatibility, attention to the used versions of XCODE, SWIFT and COCOAPODS. Recommended versions are XCODE=15, SWIFT=5.9, and COCOAPODS=1.14.2.


For more info visit https://pluggableai.xyz/ or give us feedback to [email protected].