Skip to content
Valence is in beta. The bundle format and update protocol are meant to stay stable; the CLI, the generated code and the two runtime packages’ APIs may still change. What beta means

Remote push

Contracts section 6.4. New methods/events use since: 12; regenerate the schema and ship a store build. Remote push is an opt-in native dependency: install valence_push only in push hosts. valence alone has no Firebase dependencies; local notifications and badges remain in core. Removing the package and rebuilding the host removes its Firebase SDKs, unless another app dependency supplies them. A Dart flag or omitting push.* cannot remove installed native SDKs. Review the resolved package graph and final binary before completing store disclosures.

Android delivery is blocked: needs Firebase project for the device check. iOS/APNs and its rich-image extension are experimental and untested.

valence_push is an add-on, not a plugin: push.* is a core namespace, so the package supplies a ValencePushTransport rather than a schema fragment, and it needs no plugins entry, no namespace and no since stamp of its own. The plugin directory explains the difference between the two shapes and lists both.

The reserved since: 12 identifies this addition in Valence’s template. An app maintains its own additive schema history; gate calls and events with has() from its regenerated bridge rather than comparing app.info().bridge to 12. Update the generated bridge and @getvalence/bridge together: current generated code supplies both method and event availability tables.

Add valence_push: ^0.4.0-beta.1 to your host’s dependencies. For this unreleased checkout, use a path dependency to packages/valence_push and override valence to the matching core checkout. Keep firebase_core: ^4.14.0 and firebase_messaging: ^16.7.0 as direct dependencies when your Dart code imports them. These versions preserve the registration-token API used here; Messaging 17 moves to registration/Firebase Installation IDs. Adapt the API and your send backend together before upgrading that major version.

Use your Firebase project to register your exact Android application id, add google-services.json to android/app/, and apply the Google services Gradle plugin in your push host. The core example deliberately omits that plugin, so there is no copy of this wiring left in the repo to crib from — it takes two files. In android/settings.gradle.kts, declare it in the plugins block:

plugins {
// …the Flutter, Android and Kotlin plugins already there
id("com.google.gms.google-services") version "4.4.4" apply false
}

and in android/app/build.gradle.kts, apply it:

plugins {
id("com.android.application")
id("kotlin-android")
id("dev.flutter.flutter-gradle-plugin")
id("com.google.gms.google-services")
}

Miss either half and Firebase.initializeApp() throws on missing default options at launch, so the failure is loud rather than silent. Declare android.permission.POST_NOTIFICATIONS in the main Android manifest. The phone/emulator needs compatible Google Play services. Never put a service account key in the app, web output, or repository.

Copy push_background.dart to the host’s lib/push_background.dart. Before Valence.open:

WidgetsFlutterBinding.ensureInitialized();
await Firebase.initializeApp();
FirebaseMessaging.onBackgroundMessage(pushBackgroundMessage);
final push = createFirebasePush();
final valence = await Valence.open(valenceConfig, push: push);

Import package:valence_push/valence_push.dart alongside firebase_core, firebase_messaging, valence.dart, the generated config and your background callback. The core repository example deliberately includes no push dependency or initialization; its push methods return E_UNSUPPORTED. To enable push, add the package and native setup above and wire this initialization into your host. Setting VALENCE_PUSH=true on the core example no longer enables Firebase.

Existing unreleased push hosts replace ValencePush() with createFirebasePush(). Custom ValencePushTransport implementations now exchange ValencePushMessage instead of Firebase RemoteMessage; preserve hasNotification even for empty notification envelopes. That native-only flag is excluded from the bridge JSON.

hasNotification is required and has no default, so a transport cannot leave it out. false is the permissive answer: it is the half of the data-only check that lets a payload trigger a sync, and core used to work it out itself from the provider envelope. Now that the transport is yours, a default would mean a transport that never thought about the field turned every notification carrying {"valence":"sync"} into a background sync. Pass message.notification != null (or your provider’s equivalent); the compiler will not let you forget. ValencePushMessage.fromRemote moves into the adapter’s conversion; construct provider-neutral records directly in custom transports. The background callback’s ValencePush.handleBackground API and every bridge signature stay unchanged.

start captures notification taps without fetching a token or prompting. Keep the push object for the lifetime of the host; await push.dispose() stops its listeners when permanently discarding the host. It does not unregister the device.

Firebase native auto-init is separate from the bridge. Supplying a project config can enable SDK registration before Dart runs, independently of Android notification permission. For consent-sensitive apps, follow Firebase auto-init controls in the native setup guide; a passive permission check is not a global SDK privacy switch.

import { call, connect, has, on } from '#lib/valence/bridge.g';
await connect();
if (has('push.initial')) {
const stop = on('push.tapped', ({ message }) => showMessage(message));
const initial = await call('push.initial');
if (initial) showMessage(initial);
// Call stop() when this root subscription is discarded.
}

showMessage is your app’s display handler, not a native command. Render title, body and data as text. Never evaluate scripts, insert raw HTML or blindly navigate to a URL in a push. Nothing in a payload grants access to the bridge or selects a sync server. Use your router only after validating the app’s own route identifier.

Call Behavior
push.permission() Checks without prompting. Returns notDetermined, denied, authorized, or provisional.
push.permission({request: true}) Requests alert/badge/sound permission. Call from an explicit user action.
push.token() Returns an FCM installation registration token, or null without authorization/provisional permission, or before iOS has an APNs token. Does not request permission.
push.initial() Consumes the latest pre-subscription tap, then enables live push.tapped. A second call returns null.

push.received and push.tapped carry {message}. The message is {id, data, title, body, image}; all fields except data can be null. push.tokenChanged carries {token}. Foreground received events and live token events are best effort. Check push.token after resume/reconnect as well as subscribing to rotations. Send registrations to your own authenticated backend; the token is an installation address, not a login credential. Unlink it on logout in your backend and honor provider invalid-registration responses. Do not log it.

An Android permission denial may need the user to visit system settings; repeated requests cannot override the OS. Permission status is separate from network availability and does not promise delivery.

Send an FCM HTTP v1 notification from your trusted server with android.notification.image set to an HTTPS image URL. The Android FCM SDK displays it in the background notification tray; expanding the notification may be needed to see the image. On the foreground path Valence delivers metadata to the page for an in-app presentation; it does not create a second system alert. Image loading and delivery can fail independently. HTTPS image metadata crosses the bridge, not image bytes. The signed page’s CSP still governs web image loads.

Push hosts installing valence_push need an iOS deployment target of 15.0 or later for Firebase. Raise Runner and extension target settings in those hosts. Core-only hosts no longer inherit that Firebase requirement; other plugins still set their own minima.

On iOS, upload the APNs key to Firebase, add the Firebase project plist to Runner, enable Push Notifications plus Remote notifications/Background fetch, and keep Firebase method swizzling enabled. Add a Notification Service Extension target, link Firebase Messaging into that target, and use the supplied NotificationService.swift. Set the extension’s principal class to $(PRODUCT_MODULE_NAME).NotificationService and extension point to com.apple.usernotifications.service. Send aps.mutable-content: 1 and apns.fcm_options.image with a URL including a supported file extension. A minimal extension plist is supplied next to the Swift template. Provision both targets in Xcode. These paths have not been built or tested on Apple hardware.

Send a data-only FCM HTTP v1 message:

{
"message": {
"token": "installation-registration-token",
"data": {"valence": "sync"},
"android": {"priority": "high"},
"apns": {
"headers": {"apns-push-type": "background", "apns-priority": "5"},
"payload": {"aps": {"content-available": 1}}
}
}
}

Only that exact one-field data map and no notification object triggers sync. Other messages and extra configuration fields are ignored as commands. The top-level entry-point callback uses Valence.backgroundSync(valenceConfig) with the host’s compiled config and stored bearer token. It does not call Valence.open, start a WebView/server, activate an update, close SQLite, or commit a trial. The existing sync lease and normal cursor/outbox rules still apply.

Delivery is best effort. The OS may delay or drop the hint, especially after force-stop, under battery restrictions, or after high-priority abuse. Background work must finish within the provider’s execution window (roughly 30 seconds). Normal resume/periodic sync remains the correctness path. A busy lease means no sync was attempted; never display it as “up to date.”

With a maintainer-owned Firebase project: deny then grant permission; register; send a foreground notification; background the app and send an image notification; tap it both warm and after process death; send a data-only sync hint and verify a known server row/outbox acknowledgement without any bundle-state transition; check token persistence/rotation and normal offline launch. Do not use force-stop as a test of guaranteed silent delivery. Until those pass, R5 is blocked for device validation, not ready to merge as a completed roadmap item.

Primary references checked 2026-10-22: Flutter message handling, native setup, Messaging 16.7, image payloads.

Host-to-page push events are capped at 256 KiB including script escaping. Successful and error replies count Unicode separator escapes before enforcing their JSON byte cap. An oversized error returns E_TOO_LARGE with a finite numeric correlation id, or null for an invalid/oversized id.

Last updated: