Flutter ACL Scoring SDK

1. Feature #

An Flutter Plugin for ACL Scoring feature which support Android SDK version 24+ (Android 7+) and iOS 14+

• Initialize service
• Register device
• Monitor data
• Utilities related to permission access (only available on Android)

2. Dependencies #

On Android, we're using following dependencies inside our SDK

• Room
• AdvertisingIdClient
• WorkerManager
• Desugaring

On iOS, we don't use any 3rd party dependencies inside our SDK

3. How to install #

3.1. Android: #

• Step 1: Install package

flutter pub add acl_sdk

• Step 2 (optional): Add ksp plugin into your /android/settings.gradle.kts. Please skip if your project already had this.

plugins {
  ...
  id("com.google.devtools.ksp") version "2.1.0-1.0.29" apply false
  ...
}

• Step 3: Add SDK into your app dependencies /android/build.gradle.kts

allprojects {
    repositories {
        ...
        maven {
            // [required] aar plugin
            // Access the 'acl_scoring' project
            val aclScoringProject = project(":acl_scoring")
            url = uri(aclScoringProject.layout.buildDirectory.asFile.get())
        }
    }
}

• Step 4 (optional): Add SDK dependencies and plugin into your android/app/build.gradle.kts at app level. Please if skip your project already had this.

plugins {
  ...
  id("com.google.devtools.ksp")
  ...
}

...

dependencies {
  ...
  // Desugaring
  coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.0.3")

  // Room
  implementation("androidx.room:room-ktx:2.7.2")
  implementation("androidx.room:room-runtime:2.7.2")
  annotationProcessor("androidx.room:room-compiler:2.7.2")
  ksp("androidx.room:room-compiler:2.7.2")

  // AdvertisingIdClient gms
  implementation("com.google.android.gms:play-services-ads-identifier:18.1.0")

  // Worker
  implementation("androidx.work:work-runtime-ktx:2.9.0")

  // Location
  implementation("com.google.android.gms:play-services-location:21.3.0")
  ...
}

• Step 5 (optional): Enable compile option for desugaring in android/app/build.gradle.kts app level. Please skip if your project already had this.

...
android {
  compileOptions {
    isCoreLibraryDesugaringEnabled = true
  }
}
...

• Step 6: Try to run gradle sync and wait until it done.
• Step 7: Add following code into your main.dart

// Import section
...
import 'package:acl_scoring/acl_scoring.dart';
import 'package:acl_scoring/schemas/acl_scoring_config.dart';
...

class _YourAppState extends State<YourApp> {
  ...
  // Add this line
  final _aclScoringPlugin = AclScoring();
  ...

  @override
  void initState() {
    super.initState();
    ...

    // Add following code
    await _aclScoringPlugin.initialize(
      ACLScoringConfig(
        partnerId: "<Your organization id>",
        apiEndpoint: "<Provided API Endpoint>",
        apiKey: "<Your API Key>",
        apiSecret: "<Your API Secret>",
      ),
    );
    final deviceId = await _aclScoringPlugin.registerDevice(); // You can use this deviceId later on (e.g. query for OGAI data)
    await _aclScoringPlugin.startMonitoring();
    ...
  }

  ...
}

• Step 8: Try to run your app. If everything config correctly, you will see following log in your Logcat window

Initializing OGAIService...
Done: Initializing OGAIService!!!
...
Start: registerDevice
Done: registerDevice

• Step 9: Setup for user's permission request to enable App Usage Stats and Bind Notification Listener. (Please refered to section Permissions required and utilities)

3.2. iOS #

• Step 1: Add following Capabilities to your app:

  • Push Notifications (optional - recommened)
  • Background Mode:
    • Background fetch
    • Remote notification (optional - recommened)
  • Access Wifi Information (optional - recommened)

• Step 2: Add com.uisys.ACLScoring.collectData into BGTaskSchedulerPermittedIdentifiers in your ios/Runner/info.plist file to register the BGRefreshTask (see below example)

...
<dict>
  ...
  <key>BGTaskSchedulerPermittedIdentifiers</key>
	<array>
		<string>com.uisys.ACLScoring.collectData</string>
	</array>
  ...
</dict>
...

• Step 3: Open your AppDelegate.swift at ios/Runner/AppDelegate.swift and add following code into application(_:didFinishLaunchingWithOptions:) function

...
import ACLScoring // Add this line
...

@main
@objc class AppDelegate: FlutterAppDelegate {
    override func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication
            .LaunchOptionsKey: Any]?
    ) -> Bool {
        ...

        ACLScoringService.general.startMonitoring() // Add this line

        ...
    }
}

• Step 4 (optional - recommened): Install firebase_core and firebase_messaging, and finish your app setup by following Firebase official docs

• Step 5 (optional - recommened): Add following code into the function handle new notification inside your app. In this example, we use handler function with name aclFCMOnReceiveHandler.

...
import 'package:acl_scoring/utils/firebase_messaging_utils.dart';
...

@pragma('vm:entry-point')
Future<void> aclFCMOnReceiveHandler(RemoteMessage message) async {
  // Your code goes here

  FirebaseMessagingUtils.handleFCMMessage(message.data); // Add this line
  
  // Your code goes here
}

/// The aclFCMOnReceiveHandler will be passed to `FirebaseMessaging.onBackgroundMessage` and `FirebaseMessaging.onMessage.listen`
/// See below example:
FirebaseMessaging.onBackgroundMessage(aclFCMOnReceiveHandler);
FirebaseMessaging.onMessage.listen(aclFCMOnReceiveHandler);

• Step 5: Same as Step 7 in Android setup section
• Step 6: Same as Step 8 in Android setup section. However, the log only show up when you use

4. Permissions required and utilities #

4.1. Permission required #

4.1.1. Android #

In this SDK, we will use following permission

<!-- Permission for accessing the internet -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!-- Permission to get ADID from gms (Optional) -->
<uses-permission android:name="com.google.android.gms.permission.AD_ID" />

<!-- Permission to access Bind Notification Listener Service -->
<uses-permission
        android:name="android.permission.BIND_NOTIFICATION_LISTENER_SERVICE"
        tools:ignore="ProtectedPermissions" />

<!-- Permission to access App Usage Stats -->
<uses-permission
        android:name="android.permission.PACKAGE_USAGE_STATS"
        tools:ignore="ProtectedPermissions" />

<!-- Permission to access Location -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

4.1.2. iOS #

As mentioned ealier in the 3. How to install > 3.2. iOS, we will need following Capabilities:

• Push Notifications (optional)
• Background Modes
  • Background fetch
  • Remote notification (optional)
• Access Wifi Information (optional)

In addition, since we also need to get the location in the background, you will need to request Location access within your app. We recommend requesting the "Always Usage" level.

4.2. Permission utilities (Android only) #

In this SDK, we also provide some utilities function allow easy way to request for permission (App Usage Stats, and Bind Notification Listener Service) and also check grant status on those permission. Those function is available inside PermissionUtils class

• To check if the Bind Notification Listener Service is allowed

await PermissionUtils.isBindNotificationListenerAllowed()

• To open Bind Notification Listener permisison setting

await PermissionUtils.openBindNotificationSetting()

• To check if the App Usage Stats is allowed

await PermissionUtils.isAppUsageAllowed()

• To open App Usage Stats permission setting

await PermissionUtils.openAppUsageSetting()

4.3. Utilities #

• You can trigger load device risks manually using below code:

...

final _aclScoringPlugin = AclScoring();

...

await _aclScoringPlugin.loadDeviceRisks();

5. iOS Technical notes and limitations #

5.1. Limitations #

• In order to calculate device insights data, we need to run our processing data in the background so it will not affect user's experience on your application. However, as you already known, Apple very strict on background processing process. There're only 2 options to enable it by using:

  1. Background processing framework provided by Apple
  2. Remote push notification

• By default, we has the 1st option in place. However, the background processing will depend on how OS schedule it. Therefore, it can be allow to run few times or don't even run. We can't manage this. So we recommend you to enable also the 2nd option. Eventhough, it will take more time when you integrate this framework. If you decide to go with the 2nd option, please refered to the 5.2. Notes

5.2. Notes #

5.2.1. Enable remote notification

• Step 1: Subscribe to a topic on using firebase_messaging. In this example, we use firebase_messaging and topic with name trigger_monitor

FirebaseMessaging.instance.subscribeToTopic('trigger_monitor');

• Step 2: Create a cronjob inside your backend system. Which will push a message to the topic in the interval of 30 minutes (for silient message). DO NOT push more than 2 silent messages in an hour because Apple might banned your service and your notificaiton will not send to device. If you're using normal notification then you can ignore this rate limit.

• Step 3: Add a function handle when receive FCM message. If you already have your own handler, you can just call FirebaseMessagingUtils.handleFCMMessage(message.data); inside it with an if statement to check the topic trigger.

import 'package:acl_scoring/utils/firebase_messaging_utils.dart';

@pragma('vm:entry-point')
Future<void> aclFCMOnReceiveHandler(RemoteMessage message) async {
  FirebaseMessagingUtils.handleFCMMessage(message.data);
}

• Step 4: Register the handler function to firebase_messaging by adding below code into your app

FirebaseMessaging.onBackgroundMessage(aclFCMOnReceiveHandler);
FirebaseMessaging.onMessage.listen(aclFCMOnReceiveHandler);

5.2.2. Silent notifications

If you prefer to use the silent notification, remember to do following things:

• Enable flag content-available
• Set apns-priority to 5
• Set apns-push-type to background

Issues & Contribute #

Please file any issues, bugs or feature requests as an issue on our GitHub page. Commercial support is available, you can contact us at [email protected]

Author #

This acl_scoring plugin for Flutter is developed by Unified Intelligence