Picto#
The public embedding facade — see Quick Start for the usual flow. Everything below is a static method; there's nothing to construct.
Picto.ensureInitialized#
| Parameter | Required | Meaning |
|---|---|---|
apiKey | Yes | The client app's API key — from the dashboard. |
appVersion |
Yes | Your app's version string, stored on every upload from here on. |
pendingUploadsDir |
No |
Where a failed-after-all-retries upload gets queued for a later retry. Defaults to
pending_uploads/
relative to the working directory.
|
There is no endpoint parameter: uploads go to https://api.picto.dev, which is compiled into the SDK.
Call once, before runApp(). Does not start recording — see Starting & Stopping.
Picto.startRecording()#
Turns recording on. The only way a session ever begins. A no-op if already recording.
Picto.isRecording#
Mirrors whether a recording is currently active.
Picto.endSessionAndUpload({metadata})#
Ends the current recording and uploads it — the manual-override path (backgrounding/terminating the app is the automatic one, see
Starting & Stopping). Returns false without doing anything if nothing is currently recording; throws if
ensureInitialized was never called. metadata is optional free-form tags merged into the upload — see
Tags.
Picto.setTag / Picto.recordEvent#
See Tags and Custom Events.
Picto.retryPendingUploads(metaFor)#
Retries every recording left over from a previous run that never made it past its own retries (offline, backend down, etc). Call on app start if that matters for your use case.
RecordingUploader#
The lower-level transport Picto wraps — reach for this directly only if you need more control than the facade gives you (e.g. a custom retry policy).
Constructor parameters:
| Parameter | Required | Meaning |
|---|---|---|
apiKey | Yes | The client app's API key — from the dashboard. |
endpoint |
No |
A
base
URL to upload to, overriding the compiled-in one for this instance only.
/db
is appended internally, don't include it yourself. Exists for tests and tooling that hold a handle on a specific server;
Picto.ensureInitialized
never sets it.
|
client |
No |
Inject your own
http.Client
(tests do this to mock network calls). Defaults to a real one.
|
pendingUploadsDir |
No |
Where a failed-after-all-retries upload gets queued for a later retry. Defaults to
pending_uploads/
relative to the working directory.
|
retryDelays |
No | Backoff delays between retry attempts. Defaults to [1s, 4s, 16s]. |
sendTimeout |
No | How long a single attempt waits for a response before treating it as a transient failure. Defaults to 30 seconds. |
apiKey is sent in the upload body and independently verified against the real client app record on the server — a spoofed or unrecognized value is rejected outright. The constructor takes no organization ID, client app ID, or account ID: all of that is fully determined by
apiKey alone (one client app per key, one organization/owner per client app), so the server resolves and records it for you — nothing to look up in the dashboard, nothing to wire up here.
RecordingUploader.upload#
| Parameter | Required | Meaning |
|---|---|---|
path |
Yes | The flushed recording file to upload — from PictoService.endSession/flush. |
platform | Yes | e.g. defaultTargetPlatform.name. |
appVersion | Yes | Your app's version string. |
formatVersion |
Yes |
The recording wire-format version — always
recordingFormatVersion
from
package:picto/recording/canvas_codec.dart
; never hand-pick this.
|
durationMs |
Yes | CanvasRecorder.elapsedMs at flush time. |
sessionId |
Yes | From the RecordingSegment returned by PictoService.endSession. |
metadata |
No | Free-form tags — see Tags. |
There's no multi-segment/sub-session support today — every recording is a single, complete upload, so there's nothing to number.
CanvasRecorder#
| Constructor parameter | Default | Meaning |
|---|---|---|
startActive |
true |
Pass
false
to defer recording until you call
startRecording()
explicitly —
Picto.ensureInitialized
always does this internally, so recording never auto-starts through the facade either way.
|
Reference app --dart-define values#
This repo's own reference app (apps/mobile/lib/main.dart) reads its API key from a --dart-define
at build time rather than hardcoding it — a reasonable pattern to copy, so a credential never ends up committed to source:
| Define | Maps to |
|---|---|
RECORDING_API_KEY |
Picto.ensureInitialized
's
apiKey
. Empty skips
Picto
entirely (see below).
|
flutter build apk --dart-define=RECORDING_API_KEY=oc_...
If RECORDING_API_KEY is empty, the reference app skips Picto entirely and falls back to the lower-level primitives it wraps (AppForwardingBinding/CanvasRecorder/PictoService
directly) — recording still works, it's just written locally with no credentials to upload under.