app_blackbox Free (session recorder/viewer: Enterprise)

Session capture SDK for Archipelago debug builds. Captures device metrics (battery, CPU, memory, network, FPS), filesystem events, custom in-app events, and optionally screen recordings into a .bbx bundle for post-session analysis in the Blackbox Viewer.

Tier note

The brick itself installs for free — the generated packages and build_prepare swap are available on all tiers. The Blackbox session-recorder and viewer (the SessionRecorderSDK runtime + app_blackbox_recording capability + online Blackbox Viewer) are Enterprise-sold capabilities. Free and Pro projects receive the scaffold and noop stub but cannot activate recording without an Enterprise subscription.

Version: 1.0.0

Variables

Variable	Type	Default	Description
enableScreenRecording	boolean	false	Enable screen recording capture. Requires Android MediaProjection permission + iOS ReplayKit entitlement.
enableFilesystemSnapshots	boolean	true	Enable periodic filesystem snapshots of the app sandbox.

Generated Packages

Package	Purpose
app_blackbox_api	SessionRecorderSDK contract + bundle models
app_blackbox	Debug orchestrator + debugger panel page
app_blackbox_noop	Release stub — all methods inert
app_blackbox_filesystem	Native filesystem watcher + snapshotter
app_blackbox_metrics	Native metrics collector (EventChannel)
app_blackbox_recording	Native screen recorder

The _filesystem, _metrics, and _recording packages are capability packages — they are internal to the debug implementation. Reference them in app-blackbox.md; do not generate them independently.

Usage

Interactive

archipelago generate app_blackbox

Non-interactive (CI)

archipelago generate app_blackbox --config my_config.json

Generated Structure

features/
└── app_blackbox/
    ├── app_blackbox_api/
    │   └── lib/src/
    │       ├── bundle/
    │       └── models/
    ├── app_blackbox/
    │   └── lib/src/
    │       └── di/
    ├── app_blackbox_noop/
    │   └── lib/src/
    │       └── di/
    ├── app_blackbox_filesystem/     # internal capability package
    │   └── lib/src/
    │       └── di/
    ├── app_blackbox_metrics/        # internal capability package
    │   └── lib/src/
    │       └── di/
    └── app_blackbox_recording/      # internal capability package
        └── lib/src/
            └── di/

Platform Requirements

Android

Add to AndroidManifest.xml (inside <manifest>):

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

Obtain a MediaProjection grant before starting a session with screen recording:

val mediaProjectionManager = getSystemService(MEDIA_PROJECTION_SERVICE) as MediaProjectionManager
startActivityForResult(mediaProjectionManager.createScreenCaptureIntent(), REQUEST_CODE)

iOS

• Add NSPhotoLibraryUsageDescription to Info.plist (ReplayKit saves temporary files to the photo library).
• Enable ReplayKit capability in Xcode: target → Signing & Capabilities → + Capability → ReplayKit.
• On first use, ReplayKit will prompt the user for permission.

Runtime API

// Start recording
final sessionId = await getIt<SessionRecorderSDK>().start();

// Capture a custom event
getIt<SessionRecorderSDK>().captureCustomEvent(
  'checkout_initiated',
  properties: {'amount': 99.99, 'currency': 'IDR'},
);

// Stop and obtain the bundle archive
final archive = await getIt<SessionRecorderSDK>().stop();
// archive.bytes contains the .bbx ZIP, archive.filename is a suggested filename

Viewing Sessions

Open the .bbx file in the Blackbox Viewer:

https://archipelago.banuacoder.com/blackbox-viewer/

The viewer renders metric charts, filesystem diff trees, event timelines, and (if enabled) a synchronized screen recording. The viewer is a Vue web app — no installation required.

build_prepare Integration

dart run monorepo_toolkit build-prepare release  # before release builds
dart run monorepo_toolkit build-prepare debug    # restore for development

The brick automatically adds the app_blackbox ↔ app_blackbox_noop swap to build_prepare.yaml.

Known Limitations

• Screen recording on iOS is limited by ReplayKit — the user must grant permission on each app launch in some iOS versions.
• Filesystem snapshots on iOS are sandbox-restricted; only the app sandbox is observable.
• .bbx files can grow large for long sessions with screen recording enabled — set a session time limit or clear old sessions regularly.