Flutter v1.0.1.x (Preview)

final config = TSBehavioralConfig(
  appId: 'your-app-id',
  baseUrl: 'https://your-base-url/api',
  metadataConfig: const MetaDataCollectionConfig(intervalMillis: 2000),
);

const config = TSBehavioralConfig(
  appId: 'your-app-id',
  baseUrl: 'https://your-base-url/api',
  bootstrapKeyId: 'your-bootstrap-key-id', // Provided by TrustVision
  bootstrapPublicKey: 'your-bootstrap-public-key', // Provided by TrustVision
  metadataConfig: MetaDataCollectionConfig(intervalMillis: 2000),
);

final initInfo = await plugin.initialize(config);
if (!initInfo.isRegistered) {
  final userDeviceId = await yourBackend.registerDevice(/* initInfo fields, cusUserId */);
  await plugin.markDeviceRegistered(
    isRegistered: true,
    customerUserDeviceId: userDeviceId,
  );
}
await plugin.startCollect();
await plugin.updateScreenTransition('login_screen');

final behavioral = TSBehavioral(
  config: config,
  registerDevice: (TSRegistrationRequired request) async {
    final response = await yourBackend.registerDevice(
      body: request.registerDeviceBody,
      headers: request.registerDeviceHeaders,
    );
    return TSRegistrationOutcome.fromResponse(
      statusCode: response.statusCode,
      body: response.json['data'],
    );
  },
  screenNameOf: (route) => route.settings.name,
);

MaterialApp(navigatorObservers: [behavioral.screenObserver]);

// After sign-in
await behavioral.signIn(cusUserId: signedInUserId);

dependencies:
  flutter_tv_behavioral_plugin:
    path: ./flutter_tv_behavioral_plugin # the 1.0.1.x package provided by TrustVision

flutter pub get

android {
    compileSdk = 36

    compileOptions {
        isCoreLibraryDesugaringEnabled = true
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    defaultConfig {
        minSdk = 24
    }
}

dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
}

<uses-permission android:name="android.permission.INTERNET" />

platform :ios, '13.0' # '15.0' with the Xcode 27 build

target 'Runner' do
  use_frameworks!
  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
end

cd ios && pod install

<key>NSBluetoothAlwaysUsageDescription</key>
<string>Used for device behavioral analysis</string>

<key>NSLocationWhenInUseUsageDescription</key>
<string>Used for device behavioral analysis</string>

import 'package:flutter_tv_behavioral_plugin/data/data.dart';

const config = TSBehavioralConfig(
  appId: 'your-app-id', // Your app's package name or bundle identifier
  baseUrl: 'https://your-base-url/api', // Provided by TrustVision
  bootstrapKeyId: 'your-bootstrap-key-id', // Provided by TrustVision
  bootstrapPublicKey: 'your-bootstrap-public-key', // Provided by TrustVision
  metadataConfig: MetaDataCollectionConfig(
    intervalMillis: 2000,
    canAskPermission: false,
    enabled: true,
  ),
  uploadBlockSize: 10,
  sensorConfig: SensorConfig(
    samplingIntervalMs: 20,
    sensorTypes: [
      SensorType.gyroscope,
      SensorType.accelerometer,
      SensorType.magnetometer,
      SensorType.light,
    ],
    enabled: true,
  ),
  keyboardConfig: KeyboardConfig(trackRawText: false, enabled: true),
  touchConfig: TouchConfig(enabled: true),
  screenTransitionBlockSize: 1,
  appStateBlockSize: 1,
  retryConfig: RetryConfig(),
);

const config = TSBehavioralConfig(
  appId: 'com.example.app',
  baseUrl: 'https://your-base-url/api',
  bootstrapKeyId: 'your-bootstrap-key-id',
  bootstrapPublicKey: 'your-bootstrap-public-key',
  metadataConfig: MetaDataCollectionConfig(intervalMillis: 2000),
  sslCertificates: [
    TSCertificate(name: 'my_server_cert', type: 'cer'),
  ],
);

import 'package:flutter_tv_behavioral_plugin/data/data.dart';
import 'package:flutter_tv_behavioral_plugin/session/ts_behavioral.dart';
import 'package:flutter_tv_behavioral_plugin/session/ts_behavioral_session.dart';

final behavioral = TSBehavioral(
  config: config,
  registerDevice: registerDevice, // see Device registration below
  screenNameOf: (route) => route.settings.name,
  typingScreens: {'login', 'payment_amount'},
);

MaterialApp(
  navigatorObservers: [behavioral.screenObserver], // or GoRouter(observers: [...])
  // ...
);

TSBehavioral({
  required TSBehavioralConfig config,
  required TSRegisterDevice registerDevice,
  bool enabledByDefault = true,
  String? Function(Route<dynamic> route)? screenNameOf,
  Set<String> typingScreens = const <String>{},
  Set<String>? startScreens,
  TSBehavioralSessionListener listener = const TSBehavioralSessionListener(),
  void Function(String viewId)? onFieldTracked,
})

Future<void> initialize()

void setUserId(String cusUserId)
Future<void> signIn({String? cusUserId})

await behavioral.signIn(cusUserId: 'your-user-id');

Future<void> signOut()

typedef TSRegisterDevice = Future<TSRegistrationOutcome> Function(
    TSRegistrationRequired request);

Future<TSRegistrationOutcome> registerDevice(TSRegistrationRequired request) async {
  if (!yourAuth.isSignedIn) {
    return const TSRegistrationOutcome.skipped();
  }
  // Your backend forwards this to TrustVision's POST /v1/register_device
  final response = await yourBackend.post(
    'register-device',
    body: request.registerDeviceBody,
    headers: request.registerDeviceHeaders,
  );
  return TSRegistrationOutcome.fromResponse(
    statusCode: response.statusCode,
    body: response.json['data'], // the object holding customer_user_device_id
  );
}

import 'package:flutter_tv_behavioral_plugin/flutter_tv_behavioral_plugin.dart';

final plugin = FlutterTvBehavioralPlugin();

await plugin.initialize(config);
await plugin.setCusUserId('your-user-id');

switch (await plugin.getRegistrationStatus()) {
  case TSRegistrationRegistered():
    break;
  case TSRegistrationCoolingDown():
    return; // A registration was rejected less than 10 minutes ago
  case final TSRegistrationRequired request:
    try {
      final customerUserDeviceId = await yourBackend.registerDevice(request);
      await plugin.markDeviceRegistered(
        isRegistered: true,
        customerUserDeviceId: customerUserDeviceId,
        cusUserId: request.cusUserId,
      );
    } on YourHttpException catch (e) {
      await plugin.reportRegistrationFailed(
        statusCode: e.statusCode, // null when there was no answer
        cusUserId: request.cusUserId,
      );
      return;
    }
}

await plugin.startCollect();

Future<void> startFlow()

Future<void> endFlow()

class MyListener extends TSBehavioralSessionListener {
  const MyListener();

  @override
  void onSessionEnded(TSFinalizeResult result) {
    // POST /v1/behavior/score with result.challengeId, from your backend
    yourBackend.computeBehaviorScore(challengeId: result.challengeId);
    if (result.droppedBatchCount > 0) {
      debugPrint('Dropped ${result.droppedBatchCount} batches: ${result.lastUploadError}');
    }
  }
}

Future<void> switchJourney({String reason = 'switchJourney'}) // on behavioral.session

await behavioral.session.switchJourney();

final collected = {'home', 'login', 'payment_amount', 'payment_confirm'};

final behavioral = TSBehavioral(
  config: config,
  registerDevice: registerDevice,
  // Report only the routes you collect
  screenNameOf: (route) =>
      collected.contains(route.settings.name) ? route.settings.name : null,
);

final behavioral = TSBehavioral(
  config: config,
  registerDevice: registerDevice,
  screenNameOf: (route) => route.settings.name,
  startScreens: {'login', 'payment_amount'},
);

void showIn(Route<dynamic>? route, String? screen)
Future<T> showOver<T>(String screen, Future<T> Function() show)
Future<void> enterScreen(String screen)

// A tab change inside one route
onPageChanged: (index) => behavioral.showIn(ModalRoute.of(context), tabNames[index]),

// A page inside an unnamed bottom sheet
await behavioral.showOver('promo_list', () => showModalBottomSheet(
  context: context,
  builder: (_) => const PromoList(),
));

import 'package:flutter_tv_behavioral_plugin/session/ts_collect_scope.dart';

TSCollectScope(
  screen: 'onboarding_web',
  child: WebViewWidget(controller: controller),
)

Semantics(
  identifier: 'payment_amount',
  child: TextField(controller: amountController),
)

Future<void> setRemoteEnabled(bool enabled)
Future<void> enable()

remoteConfig.onUpdate((values) {
  behavioral.setRemoteEnabled(values.behavioralEnabled);
});

<exclude domain="sharedpref" path="behavior_sdk_flags.xml"/>

class LoggingListener extends TSBehavioralSessionListener {
  const LoggingListener();

  @override
  void onError(String operation, Object error) {
    if (error is PlatformException) {
      // For an HTTP-level networkError, details carries the server context.
      final details = error.details as Map?;
      debugPrint('Behavioral $operation failed [${error.code}] '
          'HTTP ${details?['httpCode']} / ${details?['serverCode']}: ${error.message}');
    }
  }
}

import 'package:flutter/material.dart';
import 'package:flutter_tv_behavioral_plugin/data/data.dart';
import 'package:flutter_tv_behavioral_plugin/session/ts_behavioral.dart';
import 'package:flutter_tv_behavioral_plugin/session/ts_behavioral_session.dart';
import 'package:flutter_tv_behavioral_plugin/session/ts_collect_scope.dart';

// 1. Configure the SDK — compile the bootstrap key into the app
const config = TSBehavioralConfig(
  appId: 'your-app-id',
  baseUrl: 'https://your-base-url/api',
  bootstrapKeyId: 'your-bootstrap-key-id',
  bootstrapPublicKey: 'your-bootstrap-public-key',
  metadataConfig: MetaDataCollectionConfig(intervalMillis: 2000),
);

// 2. Receive session results and errors
class AppBehavioralListener extends TSBehavioralSessionListener {
  const AppBehavioralListener();

  @override
  void onSessionEnded(TSFinalizeResult result) {
    // Your backend calls POST /v1/behavior/score with the challenge id
    yourBackend.computeBehaviorScore(challengeId: result.challengeId);
  }

  @override
  void onError(String operation, Object error) {
    debugPrint('Behavioral $operation failed: $error');
  }
}

// 3. One instance for the whole app
final behavioral = TSBehavioral(
  config: config,
  registerDevice: (TSRegistrationRequired request) async {
    if (!yourAuth.isSignedIn) {
      return const TSRegistrationOutcome.skipped();
    }
    try {
      final response = await yourBackend.post(
        'register-device',
        body: request.registerDeviceBody,
        headers: request.registerDeviceHeaders,
      );
      return TSRegistrationOutcome.fromResponse(
        statusCode: response.statusCode,
        body: response.json['data'],
      );
    } catch (_) {
      return const TSRegistrationOutcome.failed(); // no answer: no cooldown
    }
  },
  screenNameOf: (route) => route.settings.name,
  startScreens: {'login', 'payment_amount'},
  typingScreens: {'login', 'payment_amount'},
  listener: const AppBehavioralListener(),
);

void main() {
  WidgetsFlutterBinding.ensureInitialized();

  // 4. Feed the kill switch whenever remote config answers
  remoteConfig.onUpdate((values) {
    behavioral.setRemoteEnabled(values.behavioralEnabled);
  });

  runApp(const MyApp());
}

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      // 5. Screens are reported from navigation
      navigatorObservers: [behavioral.screenObserver],
      initialRoute: 'login',
      routes: {
        'login': (_) => const LoginPage(),
        'payment_amount': (_) => const PaymentAmountPage(),
        'onboarding': (_) => const OnboardingPage(),
      },
    );
  }
}

class LoginPage extends StatelessWidget {
  const LoginPage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Column(
        children: [
          // 6. A stable viewId for keyboard tracking
          const Semantics(identifier: 'username', child: TextField()),
          ElevatedButton(
            onPressed: () async {
              final userId = await yourAuth.signIn();
              // 7. Hand the user over; registers if needed and starts collection
              await behavioral.signIn(cusUserId: userId);
              if (context.mounted) {
                Navigator.pushNamed(context, 'payment_amount');
              }
            },
            child: const Text('Sign in'),
          ),
        ],
      ),
    );
  }
}

class PaymentAmountPage extends StatelessWidget {
  const PaymentAmountPage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Column(
        children: [
          const Semantics(identifier: 'amount', child: TextField()),
          ElevatedButton(
            onPressed: () async {
              await yourBackend.submitPayment();
              // 8. The journey ends: finalize and upload
              await behavioral.endFlow();
            },
            child: const Text('Pay'),
          ),
          TextButton(
            // 9. Sign-out finalizes the session and forgets the user
            onPressed: behavioral.signOut,
            child: const Text('Sign out'),
          ),
        ],
      ),
    );
  }
}

class OnboardingPage extends StatelessWidget {
  const OnboardingPage({super.key});

  @override
  Widget build(BuildContext context) {
    // 10. A journey inside a shared WebView route
    return TSCollectScope(
      screen: 'onboarding_web',
      child: WebViewWidget(controller: onboardingController),
    );
  }
}

POST {baseUrl}/v1/register_device
Content-Type: application/json
Authorization: TV {accessKeyId}:{signature}
X-TV-Timestamp: {ISO8601 UTC timestamp}

{
  "data": {
    "customer_user_device_id": "server-assigned-id"
  }
}