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")
  ...
}

• 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" />

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)

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()

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_sdk plugin for Flutter is developed by Unified Intelligence