btx 0.0.14

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.14

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(...), createThread(...), and dismiss() own messenger presentation and thread creation.
• 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.

Host-owned feedback forms can create a customer message thread directly without opening the SDK-owned messenger UI:

final thread = await Btx.messenger.createThread(
  subject: 'App feedback',
  body: feedbackText,
  launchContext: const BtxLaunchContext(
    entryPoint: 'feedback',
    sourceType: 'host_feedback_form',
  ),
);

Messenger Realtime Lifecycle

The public host API is unchanged. Internally, the Flutter SDK advertises the transportVisibility: "explicit_v1" capability and requires the backend to return server-owned reconnect delays for both messenger states:

• active: any BTX messenger surface is presented, including the thread list, compose screen, or an open thread.
• hidden: the host app is foregrounded but no BTX messenger surface is presented.
• background or disposed: no messenger SSE connection is retained.

Presenting the messenger or returning to the foreground performs one explicit reconciliation. A visibility change cancels the current SSE request and opens one replacement stream from the latest cursor using the matching server profile. In this first request-volume release, a clean stream rotation performs one single-flight reconciliation before the SDK waits the selected server delay and reconnects from that cursor. Hidden foreground sessions no longer run an independent five-second thread-sync poll, so Captify's current duty cycle reduces hidden full syncs from roughly 720 to 55 per app-hour. On iOS, push is the immediate attention path while the messenger is closed only when APNs is supported, authorized, registered, and correctly configured. Without working push, Captify's hidden SSE transport converges on the configured approximately 65-second stream-plus-reconnect cycle; that is the rollout freshness target, not an immediate-delivery guarantee. Android push remains unsupported.

Presented open threads temporarily retain their existing five-second catch-up watchdog. It protects visible conversation freshness until heartbeat-based stalled-stream detection ships separately; the thread list and compose screen do not start that watchdog.

Bootstrap fails explicitly if either reconnect profile is absent, malformed, or non-positive. This prevents a client-side hardcoded delay from silently overriding the backend policy.

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.