Journey storyboards
Call create-journey-canvas once. Never build the canvas by hand with
create-design, generate-design or create-file per card: the action lays out,
sizes and persists the whole tree in one transaction.
Flow
get-onboarding-journey(Analytics) returns the cohort tree. Pass it through unchanged astreeunless you are adding a separately observed visual-reference chain.- Capture a frame for each example you want shown. Each frame is
{ nodeKey, exampleIndex, width, height, capturedAt }plus exactly one ofimageUrl,attachmentRef, orstagedFrameId.exampleIndexindexesnode.examples;widthandheightare the image's real pixels. The card uses the matching example's event timestamp and recording id from the tree, separately from the screenshot'scapturedAttime. PassrecordingStartedAtand the actualscreenshotOffsetMswhen known; replay observation time is derived only from those exact recording values. Analyticsexample.offsetMsincludes a settle interval and is shown as a nominal checkpoint seek target, never used to infer recording start or replay observation time. For staged frames, passrouteas the verified current route or explicitnullwhen the replay export does not establish it. Never substitute the initial Meta href or derive the route from the journey node key. PasscaptureSourceFingerprintwhen available and explicitnullwhen it was not captured; its absence does not block an otherwise valid private screenshot. When a frame has reviewed context, add it to that frame'scaption(observedStatefor the UI actually visible,outputTitle, recordedactorandactorSource,dateLabel,evidenceStatus, optionalevidenceAtfor a distinct source event time, andpromptwhen captured). The card shows the UTC timestamp, actor, and prompt preview; the full prompt opens in place. If the prompt is absent, say so withpromptUnavailableReasoninstead of inferring it. Use the acting identity from recording metadata, never a storage-owner email. A card with multiple frames has keyboard-accessible numbered controls to switch examples without leaving the screen. A manually added chain observed in a separate session is not cohort data: mark each of its step nodesreferenceOnly: trueand omitn,pctOfRoot,pctOfParent,dropoffN, anddropoffPct. The card saysObserved session reference; its cohort counts and percentages, incoming edge percentages, and drop-off stub are suppressed. Keep examples and frames paired byexampleIndexso chronological screenshots retain their event, recording, replay-offset, and capture-time provenance. To label observed order between two frames, useobservedContinuationsonly for a direct parent edge whose destination is reference-only. The source may be a canonical cohort node only whenfromExampleIndexselects that exact node example; this anchors the observed replay sequence without changing cohort counts or adding a cohort transition. Otherwise the source is also a reference-only node. Both private frames must bind to their selected examples from the same session and recording, with the same recording start and strictly increasing actual screenshot seek offsets. The dashed edge reads “Same recording” and has no cohort percentage. It describes replay order, not a causal transition. For exact examples from distinct recordings in the same session and app, useobservedRecordingGapsinstead ofobservedContinuations:{ type: "recording-gap", fromNodeKey, fromExampleIndex, toNodeKey, toExampleIndex, gapDurationMs? }. The destination must be a direct reference-only child. Bind both endpoints to private frames with exactrecordingStartedAtvalues and actualscreenshotOffsetMsseeks. TheirsessionIdvalues must match and their recording IDs must differ; when anonymous identity hashes are present, theanonymousIdHashvalues must match. The source frame must includerecordingEndedAtbefore the target recording start, proving a recording gap even when duration is omitted. PassgapDurationMsonly when it exactly equals target recording start minus source recording end; values are bounded to 30 days. The edge is dashed and visibly says “Recording gap,” optionally with the duration. It preserves reference-only semantics and adds no cohort count, percentage, conversion, signup success, or authentication outcome. If authentication completion was not directly observed, keep it unknown. Unsupported or mismatched provenance is rejected. For large native-PNG imports, create the Design once, then callstage-journey-canvas-frameswith a stableimportIdand batches of up to eight frames. Use the same stableframeKey(nodeKey, NUL,exampleIndex) and unchanged PNG bytes when retrying a batch; the action returns astagedFrameIdfor each frame, and the final canvas call consumes those Design-owned blobs without copying them again. Keep each request below 5 MiB and split batches when the action reportsjourney_stage_batch_too_large. If an import is abandoned, calldiscard-journey-canvas-frame-importwith its exactdesignIdandimportId; promoted storyboard frames are preserved. create-journey-canvas { title, tree, frames, locale }returns{ designId, url, nodeCount, frameCount, skippedNodes, collabSyncPending }. Openurl. A non-emptycollabSyncPendingmeans those files are saved but an open editor could not be updated live and may still show (and re-save) the previous version; call again with the samedesignIdto retry the live sync.
Options: designId (refresh that design), cardWidth (default 360),
maxExamplesPerNode (default 3, at most 6), includeScreenshotless (default false).
Each call accepts at most 2,000 journey nodes and 900 frame entries, with a
256 MiB total screenshot-byte limit.
For independent app trees on one board, set layoutMode: "appBands",
tree.app: "all", app-prefixed node keys such as clips::..., and
tree.appRootN to the root denominator for each app. Multiple cohorts from one
app can share the board with keys such as design::credits::...; their root
denominators are keyed by cohort instead. The first key segment stays the real
source app, so frame sourceApp remains design. Each app or cohort gets its
own side-by-side band, edges stay within that band, and root percentages use
that band's denominator. The layout never adds app or cohort populations
together. The main role/setup path is placed at the top of its band before
independent route components; edges and cohort counts remain unchanged. The
default layoutMode: "tree" draws one tree or forest as before.
App-band percentages must match n / appRootN[band]; do not pass a global
denominator for separate bands.
locale selects the translated labels inside each standalone storyboard card;
it defaults to en-US.
allowEncryptedPublicUploadFallback defaults to false; set it to true only
when this call is approved to store encrypted screenshot ciphertext with the
configured public-upload provider.
Images
imageUrlmust behttps://.data:URLs, other schemes and embedded credentials are rejected.attachmentRefis a personal private attachment. It is copied into opaque, encrypted private blob storage and served only to people who can view the design. A configured private blob provider is used by default. The encrypted public-upload fallback is used only whenallowEncryptedPublicUploadFallback: trueis passed and the fallback is configured; otherwise the call fails withprivate_blob_provider_required.stagedFrameIdmust be returned bystage-journey-canvas-framesfor the same Design. It consumes the existing private blob handle and rejects missing, cross-Design, or mismatched-provenance rows.
What you get
- Card height follows each frame's real aspect ratio (clamped to 0.5 to 2, letterboxed, never stretched or cropped). Extra examples stack behind the front card.
- Cards keep the event/replay UTC date, recorded actor, observed state, and prompt preview visible. Technical replay, source, route, capture, actor-source, and evidence metadata lives in a keyboard-accessible disclosure; the full prompt opens separately in place.
- A step with no frame is left off and listed in
skippedNodes; its children re-attach to the nearest drawn ancestor with a dashed arrow and a recomputed percent. Tell the user which steps are missing instead of calling the storyboard complete. - A neutral "No later step observed" stub shows the session count and
percentage of that step for sessions whose last observed step is the node.
This does not confirm that those sessions exited.
othernodes are also neutral, screenshotless stubs. When Analytics providesotherBranches, the stub lists up to 20 root-to-branch label paths per node and 200 entries / 64 KiB of serialized branch detail per tree, with each branch's count and direct-parent percentage.otherBranchCountgives the full total, andotherBranchSummariesPartialmarks producer-side omissions so a partial list says how many branches are shown. A bounded tree with no remaining detail reports zero shown; older trees without branch detail and without the partial marker say that names are unavailable. Do not reconstruct or invent them. Incoming edge labels wrap the full skipped-branch name and percentage on separate lines. - Passing
designIdagain replaces only what this action drew (ids startjc_, board objectsjc-) and redraws in place. Other screens and board objects are untouched. A first draw goes below existing screens; board objects are not measured, so check for overlap on a board that already has shapes. - If every node lacks a frame the call fails with
journey_canvas_emptyand lists them. - If the design's board was edited while the call ran, it writes nothing and fails with
journey_board_changed; call it again. - Omitting
designIdcreates a new design on every call, so do not blindly retry a call whose response was lost: look for the design first.