NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
pub.dev
pub.dev
amba SDK for Flutter — the full 4.0 surface (auth, users, sessions, sync, leagues + 29 more namespaces) for the agent-native backend-as-a-service.
Latest stable
4.2.1
Last release 1 months ago
23 Oct 2026
Release timing varies
gaps range from 8 days to 5 months
Nearly every release is documented
notes for 15 of 15 stable releases
Nothing withdrawn
no release was ever pulled
6 months old
15 releases · first in 2026
Drag across the ruler to compare, or tap a release to open it.
A refused session token no longer breaks every call. When Amba refuses the session token a call carried (INVALID_SESSION_TOKEN: the token expired, or
INVALID_SESSION_TOKEN: the token expired, or Amba rotated the key that signs session tokens), the SDK refreshes the session with the refresh token and sends the call once more. Calls refused at the same moment share one refresh, a call is sent again at most once, and onAuthStateChange hears the refreshed session. Until now every call failed with INVALID_SESSION_TOKEN until the app called auth.refresh().onAuthStateChange fires with null and the call fails with its INVALID_SESSION_TOKEN error. A network failure or server error during the refresh keeps the session.auth.refresh() waits for a refresh already in flight, so the single-use refresh token is never sent twice.Amba.configure(configDefaults: {...}): the remote config values your app ships with, keyed by config key.
Amba.configure(configDefaults: {...}): the remote config values your app ships with, keyed by config key.Amba.config.getCached<T>(key, defaultValue) returns a config value with no request, so the first frame can read config: the last fetch, else the value cached on the device from an earlier launch, else configDefaults, else defaultValue. A value of another type than defaultValue returns defaultValue; JSON integers read as double too, and arrays and objects read as typed lists and maps (List<String>, Map<String, int> and the like) when every element fits.Amba.flags.isEnabled(key, defaultValue: false) and Amba.flags.getCached(key) read flags the same way. isEnabled reads a bool configDefaults entry under the flag's name before defaultValue.app_info channel answers the new cacheDir call; AmbaClient.initialize(cacheDir:) overrides it.config.fetch(), flags.fetch() and flags.get(key) update the cache. A key the server leaves out (a config switched off with its kill switch, a disabled flag) leaves the cache, so lookups fall back to configDefaults and then the caller's default. Sign-out deletes the signed-out user's cached values.AmbaBindings gains configGetCached(String key), flagsGetCached(String key) and flagsIsEnabled(String key). A class that implements AmbaBindings (a custom transport or a test fake) adds all three; a mocktail Mock needs no change.Amba.flags.get(key) returns the flag's assignment, and null for an unknown or disabled flag. It returned null for every enabled flag and threw for an unknown one.Your coding agent can read these notes before it upgrades. Set up the MCP server →
One column per month.
Amba.experiments.getVariant(key) assigns the signed-in user to experiment key and returns an ExperimentAssignment (experimentKey, variant, bucketingId
Amba.experiments.getVariant(key) assigns the signed-in user to experiment key and returns an ExperimentAssignment (experimentKey, variant, bucketingId). The assignment is sticky: later calls return the same variant. bucketingId is the user id the server hashed to pick the variant. Amba.experiments.trackExposure(key) records that the user saw it.Amba.onExperimentAssigned(listener) calls the listener once per experiment per user session (a sign-out starts a new session). An error the listener throws is caught and logged; it never reaches the getVariant caller. Returns a function that unsubscribes.X-App-Version (the app's version, which the plugin reads from the native app info; Amba.configure(appVersion: ...) overrides it), X-Device-Region and X-Device-OS when known. Segments can target these values. Call WidgetsFlutterBinding.ensureInitialized() before Amba.configure so the plugin can answer.AmbaBindings gains experimentsGetVariant(String key) and experimentsTrackExposure(String key). A class that implements AmbaBindings (a custom transport or a test fake) adds both; a mocktail Mock needs no change.After linkAccount adds an Apple or Google identity, the SDK adopts the anonymous_id the server returns for the user. Since 2026-10-15 the server gives
linkAccount adds an Apple or Google identity, the SDK adopts the anonymous_id the server returns for the user. Since 2026-10-15 the server gives the account a new anonymous id on such a link, and events tracked afterwards now carry it; they carried the pre-link id./cargo/ for dependencies and at the package for the SDK's own code.amba-core/4.0.15, in the X-SDK-Version header and as each event's sdk_version.Crash reports symbolicate the SDK's native frames. The package ships the iOS device framework's debug symbols as ios/Frameworks/amba_core.dSYMs/amba_c
ios/Frameworks/amba_core.dSYMs/amba_core.framework.dSYM. CocoaPods copies them into the app's build, so an archive carries them in dSYMs/ (with either pod linkage): App Store Connect and crash reporters show function names, files and lines for the SDK's frames, and the upload no longer warns about a missing dSYM for amba_core.framework. The dSYM covers the device (arm64) binary. On an Intel Mac, a simulator build that builds x86_64 only logs CocoaPods' standard warning that this vendored dSYM's architecture doesn't match the build; the build itself is unaffected.ios/amba.podspec reads it from pubspec.yaml (it said 1.0.1).4.0.14, as amba-core/<version> in the X-SDK-Version header and as each event's sdk_version (it said 4.0.2).inventory.purchase(storeId: ...) buys through that store's listing, with its override price, per-user limit and segment. An item an active store limit
inventory.purchase(storeId: ...) buys through that store's listing, with its override price, per-user limit and segment. An item an active store limits per user is sold only this way; without storeId the purchase answers 409 STORE_PURCHASE_REQUIRED. The core used to drop store_id, so such an item couldn't be bought with inventory.purchase.These ship with the API, so apps on earlier versions get them without an upgrade.
segment_id is listed, read and sold only to users the segment's last evaluation recorded as members (a user it has not evaluated yet sees it after the next evaluation), and answers 404 NOT_FOUND to everyone else. An item only segment-targeted stores list is sold from the catalog to their members only (403 STORE_ACCESS_REQUIRED).price_cents that stores.getPurchaseOptions now shows.iOS apps can call the SDK. The package ships its native core as ios/Frameworks/amba_core.xcframework, a dynamic framework that CocoaPods embeds in the
ios/Frameworks/amba_core.xcframework, a dynamic framework that CocoaPods embeds in the app, and the Dart layer opens it with DynamicLibrary.open('amba_core.framework/amba_core'). Earlier versions shipped a static library (libamba_core.xcframework), and the app's linker kept none of its functions, because nothing in the app refers to them by name. The first call, Amba.configure, then threw Invalid argument(s): Failed to lookup symbol 'amba_init'.ios-arm64_x86_64-simulator slice next to the ios-arm64 device slice. Earlier versions had the device slice only, so flutter build ios --simulator and flutter run on a simulator failed with Library 'amba_core' not found.amba.podspec declares (arm64 simulators start at iOS 14.0).PrivacyInfo.xcprivacy), the same one the Swift SDK ships.use_frameworks!, which flutter create writes, or use_frameworks! :linkage => :static. Apps change nothing in their Podfile or Xcode settings.-force_load or -l"amba_core" in OTHER_LDFLAGS or a Podfile post_install hook) removes them; libamba_core.a is gone, so those flags now fail the link.Friendship has requesterId and addresseeId: a pending row is incoming when addresseeId equals userId and outgoing when requesterId does.
Friendship has requesterId and addresseeId: a pending row is incoming when addresseeId equals userId and outgoing when requesterId does.These ship with the API, so apps on earlier versions get them without an upgrade.
reviews.create works: POST /v1/client/reviews reads the target_type / target_id the SDK sends (it read only item_type / item_id and failed with a 500), and reviews.create / reviews.update come back with author_id, target_type and target_id. target_type is content_item or custom, and rating is a whole number from 1 to 5, such as 4.0; other values answer 400 INVALID_ITEM_TYPE / 400 INVALID_RATING. The core checks the rating before sending.friends.list() returns the accepted friendships, then the pending requests in both directions; it returned the accepted ones only. friends.friends() still returns the accepted ones. Blocked rows stay out of both, and a list holds at most 1000 rows.inventory.purchase with a quantity other than 1 answers 400 QUANTITY_NOT_SUPPORTED and charges nothing. It used to charge for and grant one item whatever the quantity; call it once per item to buy several.inventory.purchase returns InventoryPurchase (purchased, currencyCode, price, balanceAfter). It was typed as an InventoryItem, which the route never r
inventory.purchase returns InventoryPurchase (purchased, currencyCode, price, balanceAfter). It was typed as an InventoryItem, which the route never returned; read the bought item with inventory.items().ReferralClaim.referrerId is nullable: a code no user owns has no referrer.These ship with the API, so apps on earlier versions get them without an upgrade.
config.fetch() evaluates each key's segment and percentage conditions for the signed-in user. Before sign-in, or with an expired session token, it returns each key's default value as before.deepLinks.get, inventory.getItems / getItem / consume, content.library / item / createItem / updateItem, every friends method and referrals.getReferralCode / claimReferral return their typed results. Earlier these calls failed reading the response, after the server had already made the change. Claiming a code no user owns needs this version.inventory.consume({ item_id }) takes the catalog item id or the id of a row from inventory.getItems().inventory.purchase response also carries the inventory row it added to, so earlier versions read it without failing; a bundle purchase needs this version.401 NONCE_REUSED.DELETE /v1/client/users/me/push-token deactivates only the signed-in user's own tokens.Ids, keys, short codes and names placed in a request path are percent-encoded, so /, ? and # stay part of the value and the request keeps its route. A
/, ? and # stay part of the value and the request keeps its route. An id of ., .. or the empty string fails with VALIDATION_ERROR before any request is sent.402 FREE_TIER_LIMIT_REACHED from the sign-in request calls (magic link, email OTP, SMS OTP) once the project's daily sign-in budget is spent, and from email sends, which are a paid feature on those projects. The error's details.limit names the limit and details.upgrade carries the one-call upgrade. Projects created before the free-tier limits keep their previous behavior, and no SDK upgrade is needed.403 SANDBOX_CLAIM_REQUIRED once it has spent 14 days in that account, until the account is claimed.Amba.offerings([offeringId]) / AmbaClient.offerings — subscription
offerings (the packages your paywall renders, provider-neutral). Pass an
offering id for one offering; omit it for all. Parity with Web/Node and the
iOS/Android 4.1.0 SDKs.Amba.entitlements.restore() — Restore Purchases: re-syncs the user's
owned entitlements server-side and returns the active set (the App Store
3.1.1 requirement). Fails without changing access when the validation
engine is unreachable.Both methods are generated from the same single-source surface manifest that drives every other Amba SDK, so the Flutter surface can no longer silently lag the rest of the family.
Removed from the package family in this release: the deprecated @layers/amba-functions and @layers/amba-client packages were unpublished from npm. Amb…
Version-alignment release across every published Amba package. Brings
the infra-tier packages (@layers/amba, @layers/amba-shared,
@layers/amba-mcp — previously on 1.x) onto the same 4.x track as the
SDKs so customers can pin a single version everywhere. No surface or
behavior changes in this SDK.
Removed from the package family in this release: the deprecated
@layers/amba-functions and @layers/amba-client packages were
unpublished from npm. Amba functions are plain ES modules with the
standard export default { async fetch(req, env, ctx) } shape — no
wrapper. See docs.amba.dev/functions/runtime
for the full contract.
Version-alignment release across every Amba SDK. No surface or behavior changes — bumps every SDK (web, node, react, react-native, expo, core, kotlin,
Version-alignment release across every Amba SDK. No surface or behavior
changes — bumps every SDK (web, node, react, react-native, expo, core,
kotlin, swift, flutter, unity) to 4.0.1 so customers can pin to a single
version across stacks. See sdks/CANONICAL_API.md
for the 4.0 surface.
Amba.diagnostics.ping() — wire-verify primitive. Call once after Amba.configure(...) to confirm the SDK is talking to the right project with the right
Amba.diagnostics.ping() — wire-verify primitive. Call once after
Amba.configure(...) to confirm the SDK is talking to the right
project with the right API key in the right environment. Returns a
PingResult whose fields (serverProjectId, environment,
keyFingerprint, latencyMs) are all server-decided, so comparing
serverProjectId against the configured project id catches
"wrong key in .env" silent failures on the spot. Mirrors the
TypeScript SDKs' Amba.diagnostics.ping() shape (added in 1.0.0).dart:developer log() calls from the SDK now use name: "amba-sdk",
so Flutter DevTools / flutter logs filtering on that name surfaces
amba's own diagnostics without dragging in app-side log noise. The
SDK never calls print().Bundled prebuilt native binaries for Android (arm64-v8a, armeabi-v7a, x86_64, x86) and iOS device (arm64) so flutter build apk and flutter build ipa s
flutter build apk and
flutter build ipa succeed without any local build step.android/src/main/kotlin/com/layers/amba/AmbaPlugin.kt and
ios/Classes/AmbaPlugin.swift plugin stubs required by Flutter's plugin
registration mechanism.android/build.gradle, android/src/main/AndroidManifest.xml,
and ios/amba.podspec needed for Flutter to discover and link the plugin.Amba.version constant to match the published package version.prepare_command that downloads the matching slice on pod install.
iOS device builds, App Store archives, and Android (all four ABIs)
are fully supported out-of-box.Initial public release of the amba Flutter SDK on pub.dev.
Initial public release of the amba Flutter SDK on pub.dev.
Amba client class wrapping the Amba backend API for Flutter apps:
configure with project id + client key; track events; anonymous sign-in;
authenticated sign-in via magic link; collection CRUD; AI prompt
invocation.test/integration/ exercising the public
surface against a live tenant.