flutter_kalapa_bsdk 1.1.1

A Flutter plugin designed to capture a client’s digital footprint from both iOS and Android devices and upload it to the Kalapa service for future processing of scorecards and fragments. It provides a [...]

Flutter references v1.1.1

Requirements

Platform	Minimum	Bundled native SDK
Android	minSdk 21, compileSdk 34	vn.kalapa:behaviorsdk:1.1.1
iOS	iOS 11.0	KalapaScoreSDK 1.4.0

Core

Class KalapaBehaviorScoreFlutter

Represents the entry point to configure and interact with the Kalapa Behavior SDK from Flutter.

final klpBehaviorScore = KalapaBehaviorScoreFlutter();

---

Method addModule()

Adds a specific module to the behavior score configuration.

klpBehaviorScore.addModule(KLPApplicationModule());

Parameters

Name	Description	Type
module	Module to be added (see below)	IKLPModule

Supported Modules:

• KLPApplicationModule - Information about installed applications and permissions
• KLPCalendarModule - Calendar event metadata
• KLPContactsModule - Contact metadata (optionally full information)
• KLPMusicModule - Metadata from the device's music library
• KLPMediaModule - Audio and video files stored on the device
• KLPReminderModule - Reminder-related metadata
• KLPCoreModule - Device metadata like brand, OS, storage, network
• KLPLocationModule - Device location data (requires permissions)
• KLPBehaviorModule - Behavioral metadata based on user interaction

---

Method switchEnvironment()

Sets whether to use the development or production environment.

klpBehaviorScore.switchEnvironment(true); // true for dev, false for prod

Parameters

Name	Description	Type
isDevelopment	true for development, false for production	bool

---

Method build()

Initializes the SDK with your credentials and dataset ID.

klpBehaviorScore.build(appKey, datasetId);

Parameters

Name	Description	Type
appKey	Kalapa-provided application key	String
datasetId	A unique identifier associated with the dataset. Must be 16-128 characters in length and consist of letters, numbers, and hyphens (-).	String

---

Method startTracking()

Begins behavioral tracking.

BehaviorModule.startTracking(continuousTracking: true, isMasked: true);

Parameters

Name	Description	Type	Default
continuousTracking	If true, enables continuous tracking of user interaction	bool	false
isMasked	If true, keyboard input is normalized before it is stored or sent	bool	true

Keyboard masking

With isMasked: true (the default), every keystroke captured in a keyboard event is normalized before it leaves the widget tree: digits become 0, letters become a, and any other character is kept as-is. Typing Pass1234 is recorded as aaaa0000, so keystroke shape is preserved for scoring while the typed content is not retained.

Pass isMasked: false only when raw keyboard input is explicitly required for your use case.

---

Method stopTracking()

Terminates behavioral tracking.

BehaviorModule.stopTracking();

---

Method collect()

Collects device and behavioral data and returns a result. Should be called at the end of the user journey.

final result = await klpBehaviorScore.collect();

Returns

Type	Description
Future<KLPBehaviorScoreResult?>	Returns JSON dataset in compressed string format if collect action is succeeded

---

Class KalapaBehaviorWidget

Root widget used to capture tap, gesture, and screen interaction events across the widget tree.

This widget should wrap your application as early as possible, ideally directly inside runApp(...).

void main() {
  runApp(
    const KalapaBehaviorWidget(
      key: Key("root_layout"),
      startTracking: true,
      continuousTracking: true,
      child: MyApp(),
    ),
  );
}

Parameters

Name	Description	Type
key	Optional widget key for the root tracking container	Key?
startTracking	Automatically starts behavior tracking when the widget is mounted	bool
continuousTracking	Sends buffered events continuously instead of one by one	bool
child	Root app/widget tree to be tracked	Widget

Recommended integration flow

1. Wrap the root app with KalapaBehaviorWidget.
2. Set startTracking: true if you want tracking to begin as soon as the app starts.
3. Set continuousTracking: true if you want events to be flushed periodically during the session.
4. Call build(appKey, datasetId) before collecting data.
5. Call collect() at the end of the flow you want to score.

Manual start after app launch

If you initialize the root widget like this:

void main() {
  runApp(
    const KalapaBehaviorWidget(
      key: Key("root_layout"),
      startTracking: false,
      continuousTracking: false,
      child: MyApp(),
    ),
  );
}

then KalapaBehaviorWidget will be mounted but tracking will not start automatically.

Later, you can start tracking manually by calling the existing API:

BehaviorModule.startTracking();

or:

BehaviorModule.startTracking(continuousTracking: true);

Behavior details

• When startTracking is false, KalapaBehaviorWidget does not call BehaviorModule.startTracking(...) during initState().
• Pointer and gesture listeners are still attached by the widget, but events are ignored until BehaviorModule.isTracking == true.
• Calling BehaviorModule.startTracking() later is enough to activate tracking without rebuilding the root widget.
• Calling BehaviorModule.stopTracking() will stop tracking again at any time.
• If you want buffered events to be sent periodically, call BehaviorModule.startTracking(continuousTracking: true).

Continuous upload details

• In continuous mode, buffered events are flushed to the native SDK every 8 seconds.
• A flush either hands the batch over to the native SDK or leaves it buffered; a batch the native side does not accept is put back at the front of the buffer and retried on the next tick, so no event is lost and none is uploaded twice.
• On iOS there is no session to attach events to until the first successful collect(). Flushes during that window are expected to be kept buffered and are not errors — they are not logged as failures.

Manual start example

import 'package:flutter/material.dart';
import 'package:flutter_kalapa_bsdk/kalapa_behavior_score_flutter.dart';

void main() {
  runApp(
    const KalapaBehaviorWidget(
      key: Key("root_layout"),
      startTracking: false,
      continuousTracking: false,
      child: MyApp(),
    ),
  );
}

class MyApp extends StatefulWidget {
  const MyApp({super.key});

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  final klpBehaviorScore = KalapaBehaviorScoreFlutter();

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

    klpBehaviorScore
        .addModule(KLPBehaviorModule())
        .addModule(KLPCoreModule())
        .switchEnvironment(true)
        .build("<<YOUR_APP_KEY>>", "<<YOUR_DATASET_ID>>");
  }

  void startBehaviorTracking() {
    BehaviorModule.startTracking(continuousTracking: true);
  }

  void stopBehaviorTracking() {
    BehaviorModule.stopTracking();
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        body: Center(
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              ElevatedButton(
                onPressed: startBehaviorTracking,
                child: const Text("Start Tracking"),
              ),
              ElevatedButton(
                onPressed: stopBehaviorTracking,
                child: const Text("Stop Tracking"),
              ),
            ],
          ),
        ),
      ),
    );
  }
}

Full integration example

import 'package:flutter/material.dart';
import 'package:flutter_kalapa_bsdk/kalapa_behavior_score_flutter.dart';

void main() {
  runApp(
    const KalapaBehaviorWidget(
      key: Key("root_layout"),
      startTracking: true,
      continuousTracking: true,
      child: MyApp(),
    ),
  );
}

class MyApp extends StatefulWidget {
  const MyApp({super.key});

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  final klpBehaviorScore = KalapaBehaviorScoreFlutter();

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

    klpBehaviorScore
        .addModule(KLPBehaviorModule())
        .addModule(KLPCoreModule())
        ...
        .switchEnvironment(true)
        .build("<<YOUR_APP_KEY>>", "<<YOUR_DATASET_ID>>");
  }

  Future<void> submit() async {
    final result = await klpBehaviorScore.collect();
    debugPrint("collect result: ${result?.toJson()}");
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        body: Center(
          child: ElevatedButton(
            onPressed: submit,
            child: const Text("Collect"),
          ),
        ),
      ),
    );
  }
}

Notes

• Based on example/lib/main.dart, KalapaBehaviorWidget is the recommended place to enable global behavior tracking.
• If startTracking: true is already set on KalapaBehaviorWidget, you usually do not need to call BehaviorModule.startTracking(...) again unless you intentionally want to restart tracking later in the app flow.
• Important: KalapaBehaviorWidget.didUpdateWidget(...) currently reacts only when startTracking changes. If only continuousTracking changes while startTracking stays the same, the tracking mode is not restarted automatically. In that case, call BehaviorModule.startTracking(continuousTracking: ...) manually with the mode you want.

---

Class KLPBehaviorScoreResult

KLPBehaviorScoreResult states for successful operation and contains a value.

Field Name	Type	Description
datasetId	String	Returns datasetId so you can get dataset from server
code	String	Returns code value if the operation failed
message	String	Returns message value if the operation failed

Error codes table

Code	Description
1010	Invalid datasetId. datasetId must be between 16 and 128 characters in length and may consist solely of numbers, letters, and "-" characters
1020	idList parameters of setId() method must be an array of strings and has more than one element
1021	fieldTypeparameters of setId() method is invalid,
1030	Tracking has already been started
1031	Tracking has not been been started
1040	Unauthenticated, token is invalid or expired
1050	Something went wrong with Kalapa server
1090	Unexpected error