Pluggable's Fanmeter Plugin for Flutter apps #

A Fanmeter Flutter plugin for Flutter apps. This plugins allows you to create fanmeter events. You have two ways of doing it:

1. 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 API). It accepts a set of parameters, including:

   • 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 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.

2. 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 and fanmeterStopService API. 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 (mandatory for fully autonomous events);
  • 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.

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. For iOS, note that the GPS permission is needed for the fans to participate in the event. Hence, you need to 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>	

Pre-conditions [Integrate with FCM] #

Before using this plugin you should guarantee that your app already integrates with Firebase Cloud Messaging (FCM). The steps are quite easy to follow.

1. First install FlutterFire, a tool which automatically configures your app to use firebase;
2. Then, install firebase_messaging, a cross-platform messaging solution;
3. Then, to start using the Cloud Messaging package within your project follow these steps;
4. 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.
5. 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)

didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [FIRApp configure]; //add this at the top
    // ...
}

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:

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.

Finally, this plugin exposes two methods which can be imported like this in your main.dart:

import 'package:fanmeter/fanmeter.dart';

NOTE: For Android, to customize the used notification icon, just add the desired icon in the Android's drawble folder and name it ic_push_app_icon. Otherwise, a default icon, not related to your app, will be used.

fanmeterStartService [Manual Event] #

If you want to integrate Fanmeter in your own UI, you can use the fanmeterStartService and fanmeterStopService 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.

This method fanmeterStartService is used to let the SDK enable sensor data collection for your client's device during a particular event. This returns 1, if success, otherwise an error code. The parameters userEmail, ticketNumber, stand, notificationClassResponse and log are nullable. To call this, you must do as follows:

final _fanmeterPlugin = Fanmeter();

final fanmeterStartService = await _fanmeterPlugin.fanmeterStartService(
    companyName, 
    licenseKey, 
    eventTitle, 
    externalUserId, 
    externalTokenId, 
    externalUserEmail, 
    ticketNumber, 
    stand, 
    notificationClassResponse, 
    log
);

Example:

Future<void> executeSDK() async {
    String companyName = "my_company";
    String licenseKey = "my_company";
    ...
    bool log = false;

    final fanmeterStartService = await _fanmeterPlugin.fanmeterStartService(
        companyName, 
        licenseKey, 
        eventTitle, 
        externalUserId, 
        externalTokenId, 
        externalUserEmail, 
        ticketNumber, 
        stand, 
        notificationClassResponse, 
        log
    );
}

fanmeterStopService #

This method fanmeterStopService is used 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:

final _fanmeterPlugin = Fanmeter();

final fanmeterStopService = await _fanmeterPlugin.fanmeterStopService(log);

Example:

Future<void> stopExecuteSDK() async {
    bool log = false;

    final fanmeterStopService = await _fanmeterPlugin.fanmeterStopService(log);
}

Request Push Permission #

You should also request for user permission to deliver push notifications:

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,
    );	
}

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].