Setting Up App Blackbox

Enterprise

What you'll learn

• Generating the App Blackbox session recorder with filesystem snapshots and optional screen recording
• Understanding the six-package structure and which packages are active per build flavor
• Configuring platform permissions for Android and iOS
• Using build_prepare to strip the recorder from non-production builds
• Capturing custom events and retrieving session archives

Prerequisites

• An existing Archipelago monorepo (see Monorepo Scaffolding)
• Enterprise subscription — App Blackbox is not available on Free or Pro tiers

App Blackbox vs App Debugger: App Blackbox is a production session recorder for diagnosing issues after they occur. App Debugger (Pro tier) is an in-app overlay for developers during active development. They serve different purposes and can be used together.

Step 1: Generate App Blackbox

archipelago generate app_blackbox

You will be prompted for:

• enableScreenRecording — true or false (default: false) — records screen frames alongside event data
• enableFilesystemSnapshots — true or false (default: true) — snapshots key app data directories at session start/stop

Or use a config file:

{
  "enableScreenRecording": false,
  "enableFilesystemSnapshots": true
}

archipelago generate app_blackbox --config blackbox_config.json

Step 2: Understand the Generated Structure

App Blackbox generates six packages to keep the recorder fully removable from debug builds:

features/app_blackbox/
├── app_blackbox_api/          # SessionRecorderSDK interface and event models
├── app_blackbox/              # Coordinator — wires sub-recorders, manages session lifecycle
├── app_blackbox_noop/         # No-op implementation for debug/staging builds
├── app_blackbox_filesystem/   # Filesystem snapshot recorder
├── app_blackbox_metrics/      # CPU, memory, and frame rate metrics collector
└── app_blackbox_recording/    # Screen recording (generated if enableScreenRecording: true)

app_blackbox_api defines the contract. Feature code imports only this package. build_prepare swaps app_blackbox (real) for app_blackbox_noop in non-production flavors, so no recorder code ships in debug APKs.

Step 3: Configure build_prepare

# build_prepare.yaml
build_prepare:
  mappings:
    - debug: app_blackbox_noop
      release: app_blackbox

Run before each build:

# Debug / development
dart run monorepo_toolkit build-prepare debug

# Release / production
dart run monorepo_toolkit build-prepare release

This rewrites the app_blackbox dependency in the shell app's pubspec.yaml at build time. No runtime if/else and no recorder code in your debug binary.

Step 4: Configure Platform Permissions

Android

Add to android/app/src/main/AndroidManifest.xml:

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

These are required when enableScreenRecording: true. If screen recording is disabled, only FOREGROUND_SERVICE is needed for the metrics collector service.

iOS

Add to ios/Runner/Info.plist:

<key>NSPhotoLibraryUsageDescription</key>
<string>App Blackbox saves session archives to your photo library.</string>

Enable the ReplayKit capability in Xcode under Signing & Capabilities for the Runner target. This is required regardless of the enableScreenRecording setting, as ReplayKit is used for the screen capture pipeline.

Step 5: Register the Feature

In your shell app's bootstrap.dart:

import 'package:app_blackbox/app_blackbox.dart';

FeatureRegistry.register(AppBlackboxImpl());

The noop variant registers automatically when build_prepare debug has run — no code change needed between builds.

Step 6: Record a Session

final recorder = getIt<SessionRecorderSDK>();

// Start a session — returns a unique session ID
final sessionId = await recorder.start();

// Capture a custom event at any point
recorder.captureCustomEvent(
  'checkout_initiated',
  properties: {'amount': 99.99, 'currency': 'IDR'},
);

// Stop the session and retrieve the archive
final archive = await recorder.stop();

archive is a file path to a compressed .blackbox archive containing the event log, metrics samples, filesystem snapshots, and (if enabled) screen recording frames.

Step 7: View a Session Archive

Upload or open the archive at the Blackbox Viewer:

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

The viewer renders the event timeline, metrics graphs, and screen replay side by side. Archives are processed locally in the browser — no data is sent to Archipelago servers.

Key Configuration Points

Customization	Where to Change
Snapshot directories	app_blackbox_filesystem — edit the path list in the snapshot config
Metrics sample rate	app_blackbox_metrics — adjust the collection interval
Auto-start on launch	bootstrap.dart — call recorder.start() during post-launch init
Upload archive to your backend	After recorder.stop(), POST the archive file via the Network SDK

Next Steps

• Set up App Debugger for in-development overlay tooling (Pro tier)
• Configure monitoring to correlate session IDs with crash reports