V- Modal AI: Visual Video / Image Search - Flutter Video SDK
Flutter app integration recipes
Use this guide to add VModal to an existing Android/iOS app. Start with a verified host user, resolve that user's allowed library, discover existing collections and jobs, and then attach a screen controller. Upload and index only when the user needs new content.
The recipes target the local 1.3.0 session API, Flutter 3.44.0+, and
Dart 3.12.0+. The repository pins Flutter 3.44.6. Public package/tag
availability is not established by this guide: use the local dependency below
to reproduce these recipes. Before shipping, select an immutable public source
revision containing these symbols or a verified published compatible package.
An older 1.2.3 dependency cannot run the session recipes.
Find the recipe you need
| Goal | Read / reuse |
|---|---|
| Choose sessions or tenant-scoped access | API choice |
| Connect real sign-in and issuer adapters | Activation |
| Add a search screen without a state-management dependency | Complete controller and widget |
| Upload with progress and cancellation | Upload recipe |
| Wait for an accepted index job | Pipeline and polling |
| Recover from a failed operation | Error table |
| Switch accounts or rotate credentials | Transition recipe |
| Restore jobs and owner files after restart | Storage recipe |
| Handle picker files, pause, and process death | Mobile lifecycle |
| Verify the host app before release | Acceptance recipes |
Canonical contracts remain in sdk_contract.md and manage_api_key.md. Component diagrams are in diagrams.md. The complete working app is Framebase; its auth and issuer implementations are mocks unless the host replaces them.
Choose authentication first
Choose authentication puts the two quickstarts together. The existing recipes below demonstrate direct keys with local app-user policy. For server-issued exact user grants, replace that setup with:
final backend = await VModal.connectWithBackend(
expectedAppUserId: verifiedHostUser.id,
expectedProjectId: 'framebase',
loadToken: () async => ScopedTokenEnvelope.fromJson(
await authenticatedDeveloperApi.createVmodalSession(),
),
);
final collections = await backend.session.listCollections();
final library = backend.scope('my_library');
Inject library into the same session-bound search controller. BackendConnection
owns the manager/source lifecycle and confirms delegated binding/grants through
auth/me before return. The callback uses current host identity, maps failures
to BackendAuthException, and returns no master key. The separate
backend-auth reference demonstrates
generation fencing and mandatory verified backend adapters, preserving Framebase.
Scope actions determine usable recipes. Initial scoped reads support discovery, search and media; upload/index/metadata/delete recipes require enforced server handler support and enabled grants. Direct scope instances keep their existing resource contract. Mobile action sets do not enable server capabilities.
Close the backend connection at the start of account switch/logout, clear host view/player/cache state, and activate another after authorization. Observe state at the account owner. Temporary failure preserves host login; identity/policy invalidation retires scopes. Same-policy rotation preserves handles/storage, and project participates in backend owner identity.
1. Choose the API and own its lifetime
| Integration | Use when | Host responsibility |
|---|---|---|
BackendConnection → UserSession → UserScope |
Backend issues exact server-enforced user grants | Own host login/callback; close connection and clear UI on transition |
UserSessionManager → UserSession → UserScope |
A signed-in user has an exact allowed library policy | Verify host identity/policy; clear app-owned UI, players, caches, and navigation on transition |
VModalProject → VModalScope |
Tenant-scoped evaluation or an app that implements its own complete isolation | Own identity fencing, cancellation, storage partitions, and every low-level resource lifecycle |
VmodalClient resources |
Advanced tenant operations outside the restricted session interface | Own all isolation and selector contracts; never mix these calls into a feature claiming session guarantees |
A direct VModal API-key bearer authenticates the tenant. Its auth.me() reports that tenant
principal. It cannot determine which app user is signed in or which content
that user may access. Local session isolation does not establish server-side
app-user authorization under a shared tenant key; the deployment must enforce
that boundary independently where required.
Ownership table
| Object | Lifetime | Creates / disposes it | Responsibilities |
|---|---|---|---|
| Host auth adapter and issuer client | Host connection | App composition root | Verify identity, acquire trusted credentials/policy, classify expiry/temporary failure |
TenantCredentialSource |
One service/tenant/principal connection | App connection owner; call close() |
Coordinate accepted key revisions and renewal; remain available across user sessions |
UserSessionManager |
One active identity flow | Session coordinator; await close() |
Activate, switch, invalidate, and close session transports |
UserSession |
One activation | Manager | Immutable app identity/policy; fresh runtime sessionId |
UserScope / feature gateway |
One session and exact mapping | Session coordinator / feature owner | Retain provenance across search, uploads, jobs, metadata, and media |
Screen ChangeNotifier |
One page or retained feature | Page or feature owner | Own debounce, tokens, query generations, progress subscriptions, and local waits |
| Widget / player | View lifetime | Owning widget | Render; dispose view resources and players |
| Archive / cache adapter | Validated stable owner/scope | Host storage owner | Validate restore, partition paths, commit through captured storage lease |
An injected shared dependency belongs to its injector. A page may dispose its own notifier, but must not close an injected manager, source, or session that other features use. The manager does not close the shared credential source; the connection owner closes both when their lifetimes end.
Provider, Riverpod, or BLoC can implement the same table. None is an SDK
dependency. Keep the gateway/session out of tile constructors and network work
out of build().
2. Activate a verified user and discover content
Install for local integration
From your app, point to the SDK checkout with a relative path appropriate to your directory layout:
dependencies:
flutter:
sdk: flutter
vmodal_sdk_flutter:
path: ../vmodal_sdk_flutter
Run flutter pub get using a compatible toolchain. Within the SDK checkout,
bash install.sh flutter_bin locates its pinned Flutter executable. A path
dependency is a development arrangement; replace it with the verified immutable
release dependency before distributing the app.
Define the host handoff
| Trusted input | Meaning / validation |
|---|---|
| Stable app-user ID | Subject verified by your host auth system; never inferred from the tenant key or user-entered collection |
| Service namespace, tenant ID, expected principal | Connection binding validated by the issuer client |
| Tenant bearer and expiry/revision | Runtime credential returned by the trusted issuer; kept out of archives |
| Exact content mapping | Logical project/collection or opaque collection ID, exact stream and mode |
| Actions and collection-wide flag | Allowed policy; write permission does not automatically grant deletion or aggregate discovery |
| Policy revision | Trusted revision, or SDK fingerprint of immutable grants/selectors |
For a concrete envelope parser and injection interfaces, reuse vmodal_credential.dart, auth_adapter.dart, and user_session_controller.dart. Those are example app components, not SDK APIs. Implement the host auth adapter and issuer transport; the example supplies no production verifier or issuer URL. The issuer verifies the host token and derives its subject server-side.
Construct TenantCredentialSource as shown in
manage_api_key.md, then inject
it into UserSessionManager. Use openResolvedSession when policy resolution
is asynchronous: it retires outgoing SDK state before awaiting the resolver.
Also fence the host resolver with an activation generation so late issuer
responses cannot install credentials or update host state for another user.
The following helper receives an already trusted resolver and a mapping from that same policy. It performs discovery before returning the feature scope:
import 'package:vmodal_sdk_flutter/vmodal_sdk_flutter.dart';
Future<UserScope> activateLibrary({
required UserSessionManager manager,
required Future<UserSessionPolicy> Function() resolve,
required ContentMapping mapping,
}) async {
final session = await manager.openResolvedSession(resolve);
final scope = session.scope(mapping);
await session.listCollections();
if (!session.isActive) throw const SessionInvalidated();
await scope.collectionInfo();
if (!session.isActive) throw const SessionInvalidated();
if (scope.mapping.actions.contains(UserAction.indexation)) {
await scope.listIndexJobs();
if (!session.isActive) throw const SessionInvalidated();
}
return scope;
}
Preconditions: grant discover for collection discovery, search for the next
recipe, and media for previews. Grant indexation only when permitted. A
scope uses the session's frozen grants even if the supplied mapping attempts to
replace them. Do not manufacture a broader mapping after a denied call.
Use ContentMapping.logical for a host-defined project and logical collection;
the SDK encodes projectId__collectionName. Use ContentMapping.opaque for an
issuer's exact backend collection ID; leave it unchanged. Both retain stream,
mode, and representation through every operation.
Interpret discovery before enabling actions
| Result | UI / next action |
|---|---|
| No discoverable collections | Show “No available library”; resolve host provisioning/access before offering search |
collectionInfo() or latestVersion() is null |
Show “Search index unavailable”; investigate stream-specific metadata and policy |
| Existing scoped job | Show current work; monitor the live handle rather than submit another job |
| Search returns zero retained rows | Show an empty result for this query/filter; no automatic upload/index creation |
| Auth/access failure | Route to identity, tenant recovery, or denied state; not an empty library |
Aggregate collection versions require collectionWide: true unless discovery
returns an exact stream row. An absent stream version is not permission to
request a broader collection. Host policy controls that choice.
3. Copy a session-bound search screen
Copy this complete block into an app file. It uses only Flutter and public SDK
types. Pass a live UserScope after activation. For vid_file, pass a paired
offset-aware date range in ScopedSearchOptions; keep all selectors in the
scope. This screen displays typed filenames/distances. The media recipe below
adds images without exposing signed URLs.
import 'dart:async';
import 'package:flutter/material.dart';
import 'package:vmodal_sdk_flutter/vmodal_sdk_flutter.dart';
enum SearchPhase { idle, loading, empty, ready, error, canceled }
class SearchState {
const SearchState(this.phase, {this.result, this.message});
final SearchPhase phase;
final SessionSearchResponse? result;
final String? message;
}
class LibrarySearchController extends ChangeNotifier {
LibrarySearchController(this.scope, {required this.options});
final UserScope scope;
final ScopedSearchOptions options;
SearchState state = const SearchState(SearchPhase.idle);
Timer? _timer;
CancellationToken? _token;
int _generation = 0;
bool _disposed = false;
bool _current(int gen) => !_disposed && gen == _generation;
void _publish(SearchState next) {
if (_disposed) return;
state = next;
notifyListeners();
}
void queryChanged(String text) {
if (_disposed) return;
final gen = ++_generation;
_timer?.cancel();
_token?.cancel();
final query = text.trim();
if (query.isEmpty) {
_publish(const SearchState(SearchPhase.idle));
return;
}
_publish(const SearchState(SearchPhase.loading));
_timer = Timer(const Duration(milliseconds: 300), () {
unawaited(_search(query, gen));
});
}
Future<void> _search(String query, int gen) async {
if (!_current(gen)) return;
final token = CancellationToken();
_token = token;
try {
final result = await scope.search(
query, options: options, cancellation: token,
);
token.throwIfCanceled();
if (!_current(gen)) return;
_publish(SearchState(
result.assets.isEmpty ? SearchPhase.empty : SearchPhase.ready,
result: result,
));
} on SessionInvalidated {
if (_current(gen)) {
_publish(const SearchState(SearchPhase.canceled));
}
} on OperationCanceled {
if (_current(gen)) {
_publish(const SearchState(SearchPhase.canceled));
}
} on SdkException catch (error) {
if (_current(gen)) {
_publish(SearchState(SearchPhase.error, message: error.message));
}
} on Object {
if (_current(gen)) {
_publish(const SearchState(
SearchPhase.error, message: 'Unexpected search failure',
));
}
} finally {
if (identical(_token, token)) _token = null;
}
}
void cancel() {
if (_disposed) return;
++_generation;
_timer?.cancel();
_token?.cancel();
_publish(const SearchState(SearchPhase.canceled));
}
@override
void dispose() {
_disposed = true;
++_generation;
_timer?.cancel();
_token?.cancel();
super.dispose();
}
}
class LibrarySearchPage extends StatefulWidget {
const LibrarySearchPage({
super.key, required this.scope, required this.options,
});
final UserScope scope;
final ScopedSearchOptions options;
@override
State<LibrarySearchPage> createState() => _LibrarySearchPageState();
}
class _LibrarySearchPageState extends State<LibrarySearchPage> {
late final LibrarySearchController controller;
@override
void initState() {
super.initState();
controller = LibrarySearchController(widget.scope, options: widget.options);
}
@override
void dispose() {
controller.dispose(); // This page owns only its notifier.
super.dispose();
}
@override
Widget build(BuildContext context) => Scaffold(
appBar: AppBar(title: const Text('Search library')),
body: Column(children: [
TextField(onChanged: controller.queryChanged),
TextButton(onPressed: controller.cancel, child: const Text('Cancel')),
Expanded(child: ListenableBuilder(
listenable: controller,
builder: (context, child) {
final state = controller.state;
switch (state.phase) {
case SearchPhase.idle:
return const Center(child: Text('Enter a query'));
case SearchPhase.loading:
return const Center(child: CircularProgressIndicator());
case SearchPhase.empty:
return const Center(child: Text('No matching moments'));
case SearchPhase.error:
return Center(child: Text(state.message ?? 'Search failed'));
case SearchPhase.canceled:
return const Center(child: Text('Search stopped'));
case SearchPhase.ready:
final hits = state.result!.videoHits;
return ListView.builder(
itemCount: hits.length,
itemBuilder: (context, index) => ListTile(
title: Text(hits[index].fileName ?? 'Unnamed asset'),
subtitle: Text('Distance: ${hits[index].distance ?? "unknown"}'),
),
);
}
},
)),
]),
);
}
Mount contract: key the page by runtime session identity and the exact
scope/options identity, so changed dependencies recreate its state. For example,
a parent that rebuilds on activation can use a ValueKey derived from
scope.sessionId, scope.scopeKey, and a host options revision. This recipe's
late final controller deliberately captures dependencies once. Replace the
route/key on account or filter-policy changes; do not update its scope in place.
Auth/tenant states belong above this feature: signed out, resolving, ready,
recoverable connection, denied, and identity expired. A production gateway can
report 401/403 to that coordinator as
SearchGateway
does, preserving the feature's failure instead of turning it into empty data.
Why cancellation and generations both exist
The SDK session guard rejects work from an inactive session. The controller's generation rejects older queries inside the same active session. The timer reduces dispatch; the token requests local cancellation; the generation prevents late success and late errors from replacing a newer state. Guard after every await, including media loads, renewal callbacks, and host storage writes.
Load a preview through its live asset
import 'dart:typed_data';
import 'package:vmodal_sdk_flutter/vmodal_sdk_flutter.dart';
Future<Uint8List> loadPreview(
UserScope scope,
SessionAsset asset,
CancellationToken token,
) async {
final bytes = await scope.imageBytes(
asset, maxBytes: 2 * 1024 * 1024, cancellation: token,
);
token.throwIfCanceled();
return bytes;
}
The 2 MiB limit is an app choice. Use Image.memory(bytes) only after checking
the originating query/view generation. Load a bounded number of visible tiles;
own their cancellation and cache entries. Some hits have no usable basename or
frame time, so media can be unavailable: show a placeholder and preserve the
search hit. Never obtain an arbitrary URL through a low-level client to bypass
that failure. The restricted session API keeps signed capabilities private.
Distance is nullable and lower-is-better; do not label it confidence or convert it to a percentage. Playback offset is nullable elapsed milliseconds, not an absolute recording timestamp. Resolve a hit to an owner-local clip by canonical asset ID; differing non-null IDs must not match merely because filenames agree.
4. Upload with owned progress and cleanup
Use this helper inside a controller that owns one active task. The callback
provides the task for a cancel button before awaiting completion. onProgress
must check the controller's current session/view generation before publishing.
The helper releases its subscription on every exit and preserves the failure
for the owning controller to classify.
import 'package:vmodal_sdk_flutter/vmodal_sdk_flutter.dart';
Future<SessionUploadResponse> uploadClip({
required UserScope scope,
required UploadSource source,
required void Function(UploadTask<SessionUploadResponse>) onStarted,
required void Function(UploadProgress) onProgress,
}) async {
final task = scope.upload(source);
final progress = task.progress.listen(onProgress);
try {
onStarted(task);
return await task.result;
} finally {
task.cancel(); // Also ends unfinished work if a host callback failed.
await progress.cancel();
}
}
Controller sequence: publish uploading → retain the started task → publish
guarded byte progress → await result → check generation → record completion →
clear task reference in finally. Publish canceled for local cancellation and
unknown completion when a dispatched mutation has an ambiguous outcome. A
subscription callback should update state synchronously; route callback failures
through your app's error reporting rather than throwing from a stream listener.
Keep feature state immutable: phase, progress, nullable uploaded identity, pending job, and user-facing message. Suggested pipeline phases are picking, uploading, uploaded, indexing, ready, canceled, failed, and completionUnknown. Keep auth recovery separate. Progress reaching 100% is not finalization success and upload success is not index readiness.
Choose one navigation policy:
| Policy | Owner / page behavior |
|---|---|
| Screen-owned foreground upload | Page disposal calls task.cancel(); controller awaits/handles the result and cleans subscription |
| Retained foreground feature | App feature owner retains task/controller; page detaches only its view; explicit stop/logout still cancels |
| Platform background transfer | Host implements scheduling and durable recovery; a Dart Future alone supplies no process-death guarantee |
Signed single upload is the default for every size. Multipart requires explicit
VideoUploadOptions(multipart: true) and remains experimental; unavailable route
families fail with FeatureDisabled. Inject a persistent checkpoint store at the
manager if needed. Per-task stores and custom transcoders are rejected by the
restricted session interface; only PassthroughVideoTranscoder is supported.
5. Orchestrate upload, index, and search
Keep one immutable scope through the entire pipeline:
verified activation → collections → existing jobs/version
→ upload when requested → completion + nullable asset
→ metadata on live proven asset when needed
→ reuse suitable job or submit index → accepted job
→ bounded local polling → discover usable version → search
SessionUploadResponse.asset is nullable. Even an asset handle may have a null
canonical assetId. Preserve those nulls; filenames/frame IDs do not synthesize
asset identity. Metadata/add/update calls require live scoped provenance. JSONL
metadata is bounded to 8 MiB and uses the allowlisted scalar/string-list fields
described in the contract.
Index submission returns acceptance, not search readiness. Reuse a suitable job
from scope.listIndexJobs() when policy and product behavior allow it. Creating
an index automatically on every empty search can duplicate work and widen the
feature's responsibilities.
Bounded, cancelable local wait
The helper below uses the terminal-state classifications already used by the Framebase gateway. Confirm the backend states used by your deployment in live contract checks. Unknown states keep polling until the app's deadline.
import 'dart:async';
import 'package:vmodal_sdk_flutter/vmodal_sdk_flutter.dart';
Future<IndexationStatusResponse> waitForIndex(
UserScope scope,
SessionJob job,
CancellationToken token, {
Duration maxWait = const Duration(minutes: 2),
}) async {
final clock = Stopwatch()..start();
while (clock.elapsed < maxWait) {
token.throwIfCanceled();
final status = await scope.indexStatus(job, cancellation: token);
token.throwIfCanceled();
final state = status.status.toLowerCase();
if (const {'success', 'succeeded', 'done', 'completed', 'ok'}.contains(state)) {
return status;
}
if (const {'failed', 'failure', 'error', 'cancelled', 'canceled'}.contains(state)) {
throw ApiException('Index job ended: $state');
}
// Short slices bound local cancellation latency between HTTP reads.
for (var n = 0; n < 20; n++) {
token.throwIfCanceled();
if (clock.elapsed >= maxWait) break;
await Future<void>.delayed(const Duration(milliseconds: 100));
token.throwIfCanceled();
}
}
throw TimeoutException('Stopped waiting locally; the server job may continue');
}
The deadline bounds the polling loop; a currently running status request is
additionally bounded by SdkConfig.timeout and its read retry budget. Thus a
request already in progress can finish after maxWait. If your UI needs a hard
deadline, its owner must also cancel the token with a timer and cancel that timer
in finally. Canceling local polling does not cancel the accepted server job.
After success, rediscover latestVersion() with the same scope. If unavailable,
show “Index finished; search metadata unavailable” and investigate discovery;
do not assume a nullable version means ready. Pass the discovered version and
paired dates for vid_file in ScopedSearchOptions. The host controller checks
its operation generation after the wait and discovery before enabling search.
Resolve ambiguous mutations
| Stage / failure | Retained fact | Permitted recovery |
|---|---|---|
| Local validation before SDK dispatch | No operation accepted by this attempt | Correct input/policy and deliberately start again |
| Dispatched upload/finalization times out | Completion unknown | Reconcile using documented scoped service data / supported multipart status protocol; do not infer failure from local cancel |
| Index submission response lost | Acceptance unknown | Rediscover exact scoped jobs; offer deliberate reconciliation before another submission |
| Local polling canceled/times out | Known accepted job can continue | Save durable reference; rediscover/rebind and resume waiting |
| Cloud success, archive commit failed | Remote completion known, local persistence failed | Report both stages; repair local record without replaying the remote mutation |
The generic TransportException alone does not prove a request was never sent.
No documented once-only upload guarantee comes from filename, hash, checkpoint,
or source ID. Do not offer a blind automatic “retry upload” for unknown completion.
Collection deletion is a separate feature
Require UserAction.delete and collectionWide: true. Preview with
ScopedDeleteCollectionOptions(dryRun: true), show collection-wide consequences,
obtain explicit host UI confirmation, then commit with
ScopedDeleteCollectionOptions(dryRun: false, confirm: true). Capture the same
session and scope across preview/confirmation; recheck them before commit.
Cloud deletion does not delete owner-local MP4s. No individual remote-video
deletion API is exposed. Reconcile unknown outcomes; 409 is not permission to
replay a commit immediately. See Framebase's deletion flow for UI and archive
handling.
6. Map failures to UI and permitted recovery
Catch SessionInvalidated before OperationCanceled because it subclasses
cancellation. Catch credential failures before the generic SdkException.
Preserve the original failure for controller/repository callers, and always
release task subscriptions and timers in finally.
| Public failure | UI state | Next action |
|---|---|---|
SessionInvalidated |
Retire feature; clear old results | Recreate feature only after fresh activation; never reuse handles |
OperationCanceled |
Normal stopped state | Explicit user restart where outcome is known; accepted mutations may continue |
TenantAuthException / AuthException |
Tenant connection recovery | Renew through trusted source; retain host user unless host identity itself is invalid |
ApiException |
Context-specific failure | Classify status and operation stage; preserve unknown write outcome |
ValidationException |
Input/policy problem | Fix contract or grant; do not repeat unchanged input |
TransportException |
Read failure or unknown mutation completion | Manual read retry; reconcile mutations |
FeatureDisabled |
Feature/media unavailable | Hide unsupported action or show placeholder; no low-level bypass |
ResponseTooLarge |
Resource exceeds app/SDK limit | Reduce result count/media size; avoid unbounded buffering |
MalformedResponse |
Service-contract failure | Record safe classification; correct contract before replaying writes |
| Status | Meaning depends on stage | Recovery rule |
|---|---|---|
401 |
Tenant bearer rejected or connection blocked | Eligible GET/HEAD can recover once within bounded attempt budget; write is not replayed |
403 |
Access/policy denied | Resolve policy; no generic credential refresh or broader-key fallback |
404 |
Missing collection/job/media or unavailable resource | Refresh allowed discovery or show missing media; do not mint ownership from a bare ID |
409 |
Conflicting/busy operation | Reconcile/wait; destructive commit is not blindly repeated |
429 |
Service rate limiting | Gate actions and use verified service retry guidance; SDK promises no generic automatic 429 recovery |
500/502/503/504 |
Eligible read server failure | GET/HEAD may retry within configured budget; writes still require reconciliation |
Search uses POST even though the user perceives it as a read. Do not assume it receives GET/HEAD retry or auth-recovery behavior. Request retry snapshots retain their credential revision; eligible auth recovery reconstructs headers under the coordinator. Other statuses/transport failures are not a blanket retry promise.
Diagnostics should record operation stage, elapsed time, exception class, status, and runtime generation. Use a request identifier only when the actual response contract exposes it. Do not invent a universal request-ID header or log raw response bodies, API keys, signed URLs, or issuer envelopes. Restricted session errors already remove raw tenant bodies and underlying capabilities.
7. Handle logout, account switch, and rotation
Execute this order in the host session coordinator:
- Advance host activation/view generations and stop accepting feature actions.
- Call
manager.logout()or startopenResolvedSession(...)immediately; outgoing SDK invalidation occurs before asynchronous cleanup/resolution. - Detach and dispose old feature controllers, cancel local tokens/tasks, stop players, clear displayed images/search/history, and replace private routes and restoration state. Perform these host changes before publishing new user data.
- Retire archive writers; finish captured storage cleanup for the old owner.
- Resolve and validate the new identity/issuer envelope under the new host generation; activate the exact policy, discover content, restore validated owner data, then publish ready.
An invalidation callback must clean up resources captured for the outgoing session, not whatever manager session happens to be current later. Delayed A cleanup must not dispose B's controller/player. A→B→A creates three runtime session IDs; old A handles and callbacks do not become valid on return to A.
TenantCredentialSource.install(...) or renewCredential() replaces credentials
without changing session identity when service/tenant/principal/policy remain
equal. A changed policy requires fresh activation; a changed tenant/principal
requires a correctly bound fresh source and sessions. Host identity expiry needs
host sign-in; tenant renewal cannot repair it. A temporary tenant failure should
not automatically sign out the app user.
At final connection shutdown, await manager cleanup and close the source in a
finally block so a transport cleanup failure cannot leave the coordinator open.
Dispose host auth/issuer/archive components according to their ownership. Do
not close shared credentials when only one page leaves.
8. Persist owner data and rebind jobs
| Value | Persistent use |
|---|---|
session.context.ownerKey |
Stable service/tenant/app-user namespace |
scope.scopeKey |
Exact representation/collection/stream/mode namespace |
policyRevision |
Required restore validation; include it in result cache identity |
sessionId |
In-flight generation/dedup guards only; not a stable archive directory |
| API-key bytes/revision | Credentials; never an owner partition |
SessionAsset, SessionJob, UserScope |
Live capabilities; never serialize/reuse after activation ends |
Persist a job with job.toDurableReference(): allowlist jobId, ownerKey,
scopeKey, and policyRevision. After verified activation for that same owner
and policy, construct the durable reference from validated manifest data and
call newScope.rebindJob(reference). Rebinding checks ownership and performs
fresh exact scoped discovery bounded to 1000 rows. A reference is not proof;
missing jobs fail closed. There is no durable asset/raw upload ID rebinding API.
Use the existing
ArchiveController
for the filesystem recipe: immutable captured destinations/payloads, validated
owner metadata, paths constrained to the owner directory, staged writes, and
atomic replacement through scope.storageLease.run(...). Call lease check()
immediately before publishing a staged file. Retire a host writer when its
feature ends; do not reopen a retired writer under the same session.
SDK owner commit coordination fences older writers, including A→B→A, within one isolate. Shared multi-isolate/process storage needs one owner isolate or transactional locking. Never assume independent in-memory queues synchronize it.
Cache identity adds current policy and every result-affecting parameter:
query, dates, version, pagination, search sources, and media variant. In-flight
dedup also includes sessionId. Quarantine legacy records with unknown ownership;
do not assign them to whoever next signs in. Sign-out can preserve partitioned
files for a later verified restoration while immediately hiding them from UI.
9. Set mobile file and interruption policies
The SDK targets Android/iOS; Web is outside this contract. Toolchain minimums above are package constraints, not a claim about a particular app's Android API level or iOS deployment target. Preserve your app's native targets and check its plugin/build requirements on device. The SDK has no picker/camera UI and does not justify broad photo/storage/camera permissions by itself.
Picker/camera → reopenable upload
- Obtain the file through the host's chosen picker/camera adapter and its actual
platform permission flow. A
content://URI is not automatically a Dart path. - If access is temporary, copy it into an app-owned owner-partitioned location while permission is valid. Keep filename, length, and contents stable.
- Pass the readable
FiletoUploadSource.fromFile. The SDK can reopen ranges; do not pass a one-shot stream as though it supports replay/resume. - Keep the file until the owning task and supported resume policy release it. Record temporary-file ownership and clean only files this feature owns.
- After restart, validate owner, source existence/contract, and checkpoint envelope before offering continuation. Process death does not settle a Dart Future or prove that remote finalization failed.
Adopt an explicit lifecycle policy
| Event | Framebase policy to reuse | Host decision |
|---|---|---|
| Brief inactive interruption | Keep foreground work | Avoid unnecessary cancellation for transient system UI |
| Paused/hidden/detached | Cancel upload/local job wait and invalidate search view | Choose retained work only with explicit host ownership |
| Resume | No mutation/search replay | Rediscover current state; offer explicit resume/retry |
| Page pop | End view work | Cancel screen-owned work or detach from retained feature |
| Process death | Runtime session/controllers gone | Reauthenticate, restore validated records, rebind jobs, reconcile unknown mutations |
Hook these decisions into the app's lifecycle observer; keep them outside widget
build(). Do not claim a Dart upload survives termination. Background scheduling
and operating-system transfer semantics are host responsibilities.
Set image byte/count limits and bound concurrent loads. Dispose players on view/session transitions and profile real devices. See performance.md for streaming and timeout budgets. transcode_360.md describes a tenant-scoped custom reducer: it cannot be injected into the restricted session upload API. A host adopting that advanced path must own native success checking, output validity, cache identity, concurrent destinations, temporary cleanup, and isolation.
10. Test and release the host integration
Use the SDK's existing injected transport factories and example fixtures; do not introduce a second fake networking stack. Manager transport factories must return distinct gateway/signed transports for each session. Start with session_fixture.dart, user_session_controller_test.dart, and search_gateway_test.dart. Keep fake keys/envelopes clearly marked as fixtures.
| Arrange / act | Assert |
|---|---|
| Fake verified user and allowed envelope | Activation discovers collections before index/search; exact opaque ID unchanged |
| Empty discovery, missing version, empty search | Three distinct UI states; no implicit index submission |
| Query 1 finishes after query 2 | Only query 2 changes state; late errors also ignored |
| Dispose during debounce/media await | No dispatch after debounce disposal, no late UI publish, owned subscriptions end |
| Denied action or policy | Local failure before transport; no broader mapping fallback |
| Identity expiry vs tenant renewal failure | Sign-in required only for identity failure; connection recovery retains host user |
| A→B→A with delayed responses/progress/store writes | B never displays A; new A rejects old handles; old writer cannot overwrite new owner's state |
| Upload result lost / index acceptance lost | Unknown completion retained; no automatic duplicate mutation |
| Accepted job + restart | Durable owner fields restored; fresh rebind required; changed policy rejects old reference |
| Cloud success + local commit failure | Remote success retained; local repair does not re-upload/delete again |
| Widget account transition | Old players, decoded images, navigation/restoration, and controller references removed |
From the SDK checkout, use the pinned tools to verify SDK contracts and the reference app. These commands are existing offline tests, not backend checks:
flutter_bin="$(bash install.sh flutter_bin)"
"$flutter_bin" test test/user_session_test.dart test/session_lifecycle_test.dart \
test/session_storage_test.dart test/tenant_credentials_test.dart \
test/user_provenance_test.dart
cd example/05_framebase_userlogin
"$flutter_bin" analyze
"$flutter_bin" test
For a host app, run its own analyzer/controller/widget tests and Android/iOS device acceptance. Separate these from live service checks proving discovery, date filters, actual terminal states, multipart availability, and any server app-user authorization. Offline tests cannot prove server access isolation.
Migration and app release checklist
- Choose a verified dependency containing the public APIs used; resolve the lockfile and inspect the actual package, not only a README version example.
- Replace project/client selectors with a trusted
UserScope; replace raw IDs and signed media URLs with live handles andimageBytesin session features. - Move key replacement to the tenant source; move account/policy changes to the manager. Preserve canonical nullable IDs and typed distance/offset semantics.
- Validate or quarantine legacy cache/archive ownership; persist durable job metadata rather than old live handles.
- Inject real host auth/issuer adapters; verify exact allowed mappings and backend features on the intended service.
- Exercise cancellation, pause/resume, restart, account switch, renewal failure, and unknown mutation completion on Android/iOS devices.
- Confirm foreground/background/file-retention policy and diagnostics in the app. SDK publication steps remain in release.md.
Common implementation mistakes
| Mistake | Apply this pattern |
|---|---|
Call search in build() or create clients per tile |
Inject one scope, start work from controller actions |
| Keep a scope across account/policy change | Recreate session-bound feature; key/replace the route |
| Use query cancellation without latest-result guard | Advance generation on query/cancel/dispose and check after await |
| Cancel token and report remote write rolled back | Record accepted/unknown outcome; reconcile |
| Treat tenant auth failure as host logout | Separate connection and identity state machines |
| Save API keys or runtime session IDs as archive identity | Use validated stable owner/scope/policy metadata |
| Show low-level signed URLs in a session feature | Use live SessionAsset and scoped media bytes |
| Treat upload complete or job accepted as searchable | Wait for terminal result and rediscover usable index version |
Documentation basis: local source and existing Framebase implementation reviewed on 2026-10-02. This guide describes reusable app patterns; it does not claim a production issuer, public package publication, device certification, or live backend acceptance has been supplied by the example.