CircleBox
DocumentationPricing
Sign InGet Started
Docs

Flutter Quickstart

Use circlebox_flutter with optional cloud uploader and adapters.

Install From Git Tag

1) Add packages in pubspec.yaml

text
dependencies:
  circlebox_flutter:
    git:
      url: https://github.com/jeremiahseun/circle-box.git
      ref: v0.3.1
      path: flutter/circlebox_flutter
  circlebox_cloud_flutter:
    git:
      url: https://github.com/jeremiahseun/circle-box.git
      ref: v0.3.1
      path: flutter/circlebox_cloud_flutter
  circlebox_adapters:
    git:
      url: https://github.com/jeremiahseun/circle-box.git
      ref: v0.3.1
      path: flutter/circlebox_adapters

2) Fetch dependencies

text
flutter pub get

3) Link native CircleBox SDKs (required)

circlebox_flutter is a bridge. Host app must include native SDKs.

Android:

  1. Download release artifacts:
    • circlebox-sdk-release.aar
    • circlebox-cloud-release.aar (optional)
  2. Copy to android/app/libs/
  3. Add flatDir repo in android/settings.gradle
  4. Add AAR dependencies in android/app/build.gradle
  5. For cloud mode, add in android/app/src/main/AndroidManifest.xml:
text
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

iOS:

  1. Open ios/Runner.xcworkspace in Xcode
  2. File -> Add Package Dependencies...
  3. URL: https://github.com/jeremiahseun/circle-box.git
  4. Version: Up to Next Major 0.3.1
  5. Add products:
    • CircleBoxSDK (required)
    • CircleBoxCloud (optional)
  6. Run:
text
cd ios
pod install --repo-update

Core Setup

Initialize once in main() before runApp:

text
import 'package:flutter/widgets.dart';
import 'package:circlebox_flutter/circlebox_flutter.dart';
import 'package:circlebox_cloud_flutter/circlebox_cloud_flutter.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await CircleBox.start(config: const CircleBoxConfig(bufferCapacity: 200));

  // Optional cloud mode.
  await CircleBoxCloud.start(
    const CircleBoxCloudConfig(
      endpoint: Uri.parse('https://circlebox.seunjeremiah.workers.dev'),
      ingestKey: 'cb_live_your_key',
      flushIntervalSec: 15,
      immediateFlushOnHighSignal: true,
    ),
  );

  runApp(const MyApp());
}

Call startup once. Do not call CircleBox.start from frequently rebuilt widgets.

Then use APIs anywhere in app code:

text
await CircleBox.breadcrumb('checkout_started', attrs: {'flow': 'standard'});

Pending Crash Export

text
if (await CircleBox.hasPendingCrashReport()) {
  final files = await CircleBox.exportLogs(
    formats: {
      CircleBoxExportFormat.json,
      CircleBoxExportFormat.csv,
      CircleBoxExportFormat.jsonGzip,
      CircleBoxExportFormat.csvGzip,
      CircleBoxExportFormat.summary,
    },
  );
  print(files);
}

Optional Cloud Upload

text
await CircleBoxCloud.start(
  const CircleBoxCloudConfig(
    endpoint: Uri.parse('https://circlebox.seunjeremiah.workers.dev'),
    ingestKey: 'paste_ingest_key_from_control_plane',
    flushIntervalSec: 15,
    immediateFlushOnHighSignal: true,
  ),
);

Key rules:

  • ingestKey must be cb_live_*
  • usageBeaconKey must be cb_usage_* when usage beacon is enabled
Previous← Android Quickstart NextReact Native Quickstart →