btx 0.0.9

BTX Flutter SDK for customer app telemetry, feature flags, messaging, and native integrations.

BTX Flutter SDK

btx is the BTX Flutter SDK for customer-app telemetry, feature flags, messaging, and native integrations.

Install

dependencies:
  btx: ^0.0.8

Quickstart

import 'package:btx/btx.dart';

await Btx.configure(
  BtxConfiguration(
    publishableClientKey: 'cfk_...',
  ),
);

await Btx.identify(
  const BtxCustomer(
    externalId: 'customer_123',
    name: 'Taylor',
    email: '[e-mail]',
  ),
);

Btx.log(
  'checkout_started',
  level: BtxLogLevel.info,
  message: 'Customer started checkout.',
  properties: <String, Object?>{'cartId': 'cart_123'},
);

Btx.messenger.present();

BTX derives app version, build number, platform, bundle ID, and package name from the host app by default.

Mount BtxHost inside your MaterialApp so the SDK can present messenger UI and foreground notification surfaces:

MaterialApp(
  home: BtxHost(
    child: MyAppHome(),
  ),
);

Facade Surface

• Btx.configure(BtxConfiguration) configures the SDK once.
• Btx.identify(BtxCustomer?) binds or clears the active customer.
• Btx.ready() waits for pending configure/identity work to settle.
• Btx.log(...) enqueues host telemetry. The SDK flushes logs automatically after enqueue, on app lifecycle transitions, and when batches fill.
• Btx.refreshFeatureFlags() refreshes the active customer flag snapshot.
• Btx.isFeatureEnabled(...) reads the current flag snapshot synchronously.
• Btx.featureFlagEnabled(...) waits for pending SDK work and optionally refreshes before reading a flag.
• Btx.featureFlagsListenable lets host UI rebuild when refreshed flag values change.
• Btx.messenger.present(...), presentThread(...), presentCompose(...), and dismiss() own messenger presentation.
• Btx.flush() is available for rare lifecycle/debug waits; normal host apps should not call it for routine telemetry.
• Btx.dispose() supports teardown and test cleanup.

Configuration

await Btx.configure(
  BtxConfiguration(
    apiBaseUrl: Uri.parse('http://localhost:3000'),
    projectId: 'project_123',
    publishableClientKey: 'cfk_...',
    features: const <BtxFeature>{
      BtxFeature.logs,
      BtxFeature.messenger,
    },
  ),
);

For apps with multiple build variants, provide the key set once and let BTX resolve the current platform/package key:

await Btx.configure(
  BtxConfiguration.withPublishableClientKeys(
    publishableClientKeys: const BtxPublishableClientKeys(
      defaultKey: 'cfk_ios_prod',
      iosBundleIds: <String, String>{
        'com.example.app.beta': 'cfk_ios_beta',
      },
      androidPackageNames: <String, String>{
        'com.example.app': 'cfk_android',
      },
    ),
    features: const <BtxFeature>{BtxFeature.logs},
  ),
);

Use appContext only for app-specific low-cardinality attributes or explicit version/build overrides:

await Btx.configure(
  BtxConfiguration(
    publishableClientKey: 'cfk_...',
    appContext: const BtxAppContext(
      attributes: <String, String>{
        'releaseRing': 'beta',
      },
    ),
    features: const <BtxFeature>{
      BtxFeature.logs,
      BtxFeature.messenger,
    },
  ),
);

Use features: {BtxFeature.logs} for telemetry-only integrations such as the current Captify use case.

Android

Android messenger UI is in scope for the Flutter SDK. Android push is explicitly unsupported until a real FCM implementation is added; the SDK reports that unsupported state instead of silently no-oping.

Advanced Surfaces

The package still exposes lower-level controller/runtime types for tests, custom embedded views, and advanced host ownership. New app integrations should prefer the Btx facade first. See doc/advanced.md for worker-mode telemetry, direct controller ownership, and native push details.