Quick Start

Wire Picto into your app's main(), start a recording, and let it upload itself.

This walks through the minimum needed to record a session and get it uploaded, using Picto, the SDK's public embedding facade. It mirrors exactly what this repo's own reference app does in apps/mobile/lib/main.dart — if anything here is unclear, that file is the complete, working version to read alongside it.

1. Initialize Picto#

One call, before runApp():

import 'package:flutter/material.dart';
import 'package:picto/picto.dart';

void main() {
  Picto.ensureInitialized(
    apiKey: 'oc_...',   // from your client app in the dashboard
    appVersion: '1.0.0',
  );

  runApp(const MyApp());
}

That's the entire backend configuration — no server URL, organization ID, client app ID, or account ID anywhere. Uploads go to picto's hosted backend (https://api.picto.dev), which the SDK already knows.

This swaps in the recording-capable WidgetsBinding the same way WidgetsFlutterBinding.ensureInitialized() normally would — it's the one call main() genuinely has to make, since the SDK needs to be the app's actual binding to see every canvas draw call. Nothing else about your app changes: no required UI, no behavior change, unless you opt into what's below.

Don't hardcode `apiKey` in source — the reference app reads it via `--dart-define` at build time instead (`RECORDING_API_KEY`), which keeps it out of version control. See [Configuration Reference](/recording/configuration-reference).

2. Start recording — explicitly, on your own terms#

Picto.ensureInitialized does not start a recording. Nothing does, until you call:

Picto.startRecording();

This is deliberate: Picto never records or uploads a session unless your own code decides to. Call it wherever makes sense for your app — unconditionally at launch, behind a consent screen, from a debug menu, after a user opts in to "help us improve the app," whatever fits. A no-op if already recording.

3. Uploading happens automatically from here#

Once a recording is active, you don't need to do anything else: if the app is backgrounded or terminated, Picto ends the session and uploads it on its own. Failures aren't lost — a failed upload is queued locally and retried automatically (see RecordingUploader in Configuration Reference).

4. (Optional) end and upload manually#

If you want an explicit trigger instead of waiting for the app to background — e.g. a "Send feedback" button, or ending the session on sign-out — call:

final ok = await Picto.endSessionAndUpload();

ok is true once the upload has actually succeeded (false means it's queued for retry, not lost). Pass metadata for any extra free-form tags you want stored alongside the recording — see Tags.

Watching the result#

Once the upload succeeds, sign in to the dashboard, select your organization and client app, and click Watch replay next to the recording — see Watching a Replay.