btx 0.0.23

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

BTX Flutter SDK

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

Install

dependencies:
  btx: ^0.0.23

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

To expose the SDK-owned knowledge base viewer, opt in to messenger and the knowledge base, then identify the customer:

await Btx.configure(
  BtxConfiguration(
    publishableClientKey: 'cfk_...',
    features: const <BtxFeature>{
      BtxFeature.logs,
      BtxFeature.messenger,
      BtxFeature.knowledgeBase,
    },
  ),
);

await Btx.identify(
  const BtxCustomer(externalId: 'customer_123'),
);

Btx.knowledgeBase.present();

The default feature set is logs plus messenger. Btx.knowledgeBase.* throws a StateError until the host app enables both BtxFeature.knowledgeBase and BtxFeature.messenger, then identifies a customer. The SDK resolves the project from the publishable client key through messenger bootstrap.

BTX derives app version, build number, platform, bundle ID/package name, OS name and version, client-device model/manufacturer, physical-device status, and BTX SDK name/version from the host app by default. Android also reports the API level and security-patch version when available.

The SDK does not collect persistent phone identifiers, user-assigned device names, phone serial numbers, storage readings, or memory readings. Runtime metadata collection is best effort and never blocks SDK configuration.

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.sdkName and Btx.sdkVersion expose the SDK identity reported in app context for support diagnostics.
• 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.status and Btx.statusListenable expose whether telemetry is active, inactive, disabled, or disposed. Disabled states include a typed reason such as invalidPublishableClientKey or appContextMismatch.
• Btx.messenger.present(...), presentThread(...), presentCompose(...), createThread(...), and dismiss() own messenger presentation and thread creation.
• Btx.knowledgeBase.present(...), openArticle(...), search(...), and dismiss() own knowledge base viewer presentation after the host opts in with messenger and knowledge base features and identifies a customer.
• Btx.push.bindAndroidSource(...), setAndroidToken(...), handleAndroidNotificationOpen(...), and unregisterAndroidDevice() own Android BTX push lifecycle once the host supplies a Firebase-neutral source.
• 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.

Messenger Behavior

The packaged messenger renders URLs in message bodies as tappable links and opens them with the platform's external URL handler. Customers can long-press a message bubble to copy the message text.

Knowledge base articles

The packaged knowledge base viewer renders the hydrated article HTML returned by BTX. Host apps must opt in with BtxFeature.knowledgeBase and BtxFeature.messenger, then identify a customer before calling Btx.knowledgeBase.*. The SDK authenticates the publishable client key through messenger bootstrap and uses the returned project context for public KB reads. The default feature set remains logs plus messenger only. KB stays in the main btx package for a single host-app install path, so WebView and video-player dependencies are present at build time even when the runtime feature is disabled.

The host integration path is:

await Btx.configure(
  BtxConfiguration(
    publishableClientKey: 'cfk_...',
    features: const <BtxFeature>{
      BtxFeature.logs,
      BtxFeature.messenger,
      BtxFeature.knowledgeBase,
    },
  ),
);

await Btx.identify(
  const BtxCustomer(externalId: 'customer_123'),
);

Btx.knowledgeBase.present();

Supported media includes:

• Images with alt text, dimensions, and captions.
• MP4 videos with play, pause, scrubbing, and playback-speed controls. MP4 metadata and native controllers are created only after the user taps Play video. The first tap queues playback during initialization and starts the video once metadata is ready. Each block owns and disposes its own controller; the viewer does not prewarm videos or coordinate controllers across blocks.
• Embedded YouTube videos in a narrow in-app WebView adapter. The viewer uses the privacy-enhanced www.youtube-nocookie.com host, the official YouTube IFrame Player API, autoplay=0, playsinline=1, and sanitized start offsets. The WebView shell uses the SDK-owned HTTPS origin https://btx.secondcontext.com for both origin and widget_referrer. This nonempty client identity is required by YouTube mobile WebViews and avoids the configuration error 153 path. See the YouTube IFrame Player API reference.

Media blocks use themed surfaces. Opening an article creates no MP4 controller or YouTube WebView. MP4 activation initializes and queues playback on its first tap, so one tap is enough to start the video. YouTube's idle surface uses a validated video ID to load the thumbnail directly from i.ytimg.com; it does not create a WebView until activation. Media state and teardown are local to each mounted block, with generation checks protecting against late native callbacks after replacement or dismissal. Backgrounding pauses local MP4 playback and does not trigger automatic reinitialization.

Images, MP4 videos, and attachment links are rendered only when their linked asset publicUrl points to the BTX public asset route on the configured API origin: /apps/btx/knowledge/v1/assets/<assetId>. Raw src values in hydrated HTML are ignored when they disagree with the linked asset. YouTube remains a separate narrow exception for validated /embed/<11-character-id> URLs. Project logos are rendered only through the BTX public project-logo route on the configured API origin: /apps/btx/knowledge/v1/projects/<projectId>/logo. During backend rollout, the SDK also accepts existing uploaded Supabase Storage object URLs for the exact project-icons/<projectId>/icon object. Development HTTP is accepted only when it is the configured apiBaseUrl origin and the URL still matches one of these BTX public KB routes.

MP4 videos provide a fullscreen action through a local SDK route that reuses the same Chewie and native video controller. This does not create another media controller or backend request. The route closes before the widget disposes its controllers, including when the article is dismissed or replaced. The SDK does not call SystemChrome, force portrait or landscape orientation, hide system UI, or change the host app's navigation policy. The host app remains authoritative for orientation, system UI, and platform navigation behavior. YouTube remains inline in v1 and does not expose an external browser/app fallback.

Loading uses a themed skeleton. A real image, video, or WebView failure moves that block to a local fallback with a bounded, user-triggered retry action; there are no retry timers. Media failures do not remove article text, headings, lists, or other media. The hydrated HTML field is authoritative when it contains renderable content, and plainText is used only as a fallback. Linked assets marked attachment are kept in the separate attachments section and are not rendered inline when referenced by article media. Linked inline images must use the inline or hero asset use and an image MIME type; linked MP4 media must use the video asset use and video/mp4.

KB media and project-logo requests are limited to BTX public KB routes on the configured API origin. On Android, declare the host app's internet permission:

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

For local HTTP development, add only the narrowly scoped App Transport Security exception required for the configured local API origin. Production should use HTTPS so no ATS exception is needed. The SDK's iOS podspec requires iOS 13.0 or newer; WebView-based media also requires Android API 21 or newer. The SDK keeps its declared Dart 3.5 and Flutter 3.24 minimums.

MP4 playback depends on the native platform codec. Unsupported codecs, broken files, and offline media produce an inline fallback instead of an app-level error and can be retried manually. Article dismissal disposes mounted media resources. YouTube playback depends on an available platform WebView, JavaScript, network access, and YouTube's embed availability.

The viewer coalesces identical in-flight article and search requests and ignores responses that belong to an older article, search query, cleared search, dismissed viewer, or disposed controller. It does not add a persistent response cache. Logo loading makes one validated BTX-route attempt and never blocks article or category rendering. A real failure resolves to the existing initials fallback without retry timers.

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(
    conversationPurpose: BtxConversationPurpose.feedback,
    entryPoint: 'feedback',
    sourceType: 'host_feedback_form',
  ),
);

BtxConversationPurpose.support is the default for normal messenger threads. Feedback threads remain replyable, but BTX operator surfaces can label and prioritize them separately.

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. Push is the immediate attention path while the messenger is closed when the host platform is configured end to end: APNs on iOS, or Android FCM after the host binds the BTX push bridge, notification permission is granted, the Android package matches the configured client, and backend Firebase credentials are present. Without working push on the current platform, 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.

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'),
    publishableClientKey: 'cfk_...',
    features: const <BtxFeature>{
      BtxFeature.logs,
      BtxFeature.messenger,
      BtxFeature.knowledgeBase,
    },
  ),
);

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 app-version/build-number overrides. Platform, OS, client-device, and BTX SDK attributes are SDK-owned so one host cannot accidentally report stale runtime metadata:

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. Omit BtxFeature.knowledgeBase unless the host app intentionally exposes the KB viewer.

Telemetry delivery preserves queued logs across runtime recreation. A rejected publishable key or app-context mismatch pauses delivery without retrying every two seconds; update the platform/package key configuration and recreate the runtime to resume delivery. Network, rate-limit, and server failures remain queued and retry with bounded exponential backoff.

Android

Android messenger UI is supported. Android push is Firebase-neutral in the core package: host apps own Firebase initialization and dependencies, then bind plain Dart token/open callbacks into BTX. Android push is scoped to the messenger feature; BtxFeature.messenger and enablePushBridge=true are both required for BTX registration and tap routing.

final messaging = FirebaseMessaging.instance;

await Btx.push.bindAndroidSource(
  BtxAndroidPushSource(
    firebaseProjectId: messaging.app.options.projectId,
    getToken: messaging.getToken,
    tokenRefreshes: messaging.onTokenRefresh,
    getInitialNotification: () async {
      final message = await messaging.getInitialMessage();
      return message == null
          ? null
          : BtxAndroidNotificationOpen(
              data: Map<String, Object?>.from(message.data),
              handleIfUnhandled: () => handleHostNotification(message),
            );
    },
    notificationOpens: FirebaseMessaging.onMessageOpenedApp.map(
      (message) => BtxAndroidNotificationOpen(
        data: Map<String, Object?>.from(message.data),
        handleIfUnhandled: () => handleHostNotification(message),
      ),
    ),
  ),
);

The btx package does not depend on FlutterFire, declare a Firebase receiver or service, or delete/change host Firebase tokens. Android notification permission is requested by BTX on first messenger presentation when an Android source or token is available.

Advanced Surfaces

The package exposes lower-level non-knowledge-base controller and runtime types for tests, custom embedded views, and advanced host ownership. Knowledge-base controller, mount, and view implementation types are intentionally internal; new app integrations should use the Btx.knowledgeBase facade. See doc/advanced.md for worker-mode telemetry, direct controller ownership, and native push details.