g3-native-plugins 0.4.5

Dioxus plugins for mobile permissions, auth, storage, purchases, media, notifications, over-the-air updates, deep links, and platform integration.
Documentation

g3-native-plugins

CI Crates.io docs.rs License

Dioxus wrappers for native clipboard/share, Apple and Google auth hooks, external URLs, notifications and push, over-the-air bundle updates, and deep-link metadata helpers.

The Cargo package is g3-native-plugins; the Rust crate name is g3_native_plugins.

Platform Support

Coverage is not uniform. Where a plugin has no implementation for the target, the calls compile to inert no-ops rather than failing the build — so a missing platform shows up as nothing happening at runtime, not as a compile error.

Feature Android iOS / macOS Web Notes
appearance yes not needed not needed The system's dark-mode setting, which an Android WebView reports wrongly. Elsewhere None: the page's own media query is right.
camera-microphone yes iOS only n/a Permission state, prompting, and the Settings escape hatch around getUserMedia. Not a capture API.
clipboard yes iOS only yes Copy plus a native share sheet on mobile. macOS is inert.
auth yes iOS only no Google Sign-In on Android, Sign in with Apple on iOS. macOS is inert.
external-url yes iOS only yes Opens the system browser. macOS is inert.
geolocation yes iOS only n/a Start-and-poll position requests and the runtime permission prompt. Web is inert on purpose: use navigator.geolocation.
back-button yes iOS only no The back event, whatever raises it: Android's system back, an iOS left-edge swipe.
deep-links yes iOS only n/a Receives the URL a universal link, App Link, or custom scheme opened the app with.
in-app-purchases yes iOS only n/a Products, purchases, subscriptions, and restore. Play Billing and StoreKit 2.
storage yes iOS only yes* Key-value storage. Keystore AES-GCM / Keychain. *Web is localStorage and not encrypted.
media yes iOS only no Background playback, lock-screen controls, and Now Playing metadata.
notifications yes iOS only no Local notifications: now or scheduled, buttons and replies, Android channels.
push-notifications yes iOS only no Remote push: FCM on Android, APNs on iOS. Turns on notifications.
updater yes iOS only no Signed over-the-air updates of the files the WebView loads, with rollback. Not of the Rust binary — see below.

The deep_links module's metadata builders are not feature-gated and build everywhere, including on the server. Only receiving a link needs the deep-links feature.

Install

Enable only the plugins your app uses:

[dependencies]
g3-native-plugins = { version = "0.4", features = ["clipboard", "auth", "external-url"] }

Provide Plugins

Create the provider once near your app root. The provider lazily constructs each native plugin the first time it is used.

use dioxus::prelude::*;
use g3_native_plugins::NativePluginsProvider;

#[component]
fn App() -> Element {
    rsx! { NativePluginsProvider { Outlet::<Route> {} } }
}

Clipboard and Share

use dioxus::prelude::*;
use g3_native_plugins::NativePlugins;

let mut plugins = use_context::<NativePlugins>();
plugins.clipboard.write().copy_to_clipboard("Invite copied".to_string())?;
plugins.clipboard.write().share("Join my game".to_string())?;

The web implementation uses the browser Clipboard and Web Share APIs. Android and iOS use the bundled Manganis FFI plugin sources under src/android and src/ios.

Auth

Enable the auth feature to expose platform auth helpers:

let mut plugins = use_context::<NativePlugins>();

#[cfg(target_os = "android")]
// The web client id from your own Google Cloud project.
plugins.auth.write().start_google_auth(GOOGLE_SERVER_CLIENT_ID)?;

#[cfg(target_os = "ios")]
plugins.auth.write().start_apple_auth(server_state, server_nonce)?;

// Both calls return as soon as the native account UI has been requested.
if let Some(credential) = plugins.auth.write().poll_auth_result()? {
    // Send the Google ID token or Apple credential JSON to your server.
} else if !plugins.auth.write().is_auth_awaiting() {
    // The flow ended without a credential: cancellation or refusal.
}

Sign-in is asynchronous on both platforms. Call poll_auth_result() from your UI flow until a credential arrives or is_auth_awaiting() becomes false. A successful Android poll consumes the credential, so it is returned only once. Android yields the Google ID token directly. Apple requires a fresh state and nonce issued and stored by your server before every request. Its result JSON contains identity_token, authorization_code, returned state, and, on the first authorization, any email and display name Apple supplied. Consume the stored challenge once, compare state, validate the token nonce, and exchange the authorization code with Apple before creating a local session.

start_google_auth takes the web client id from your own Google Cloud project — the one ending .apps.googleusercontent.com, not the Android client id. It is a parameter rather than a crate constant because it names one project: Credential Manager checks it against an Android client registered in that same project for your package name and signing certificate, so an id belonging to another app cannot work however well formed it is. A wrong or unregistered id fails exactly like a missing account — no credential, no explanation — so check the registration first when sign-in returns None unexpectedly.

Appearance

An Android WebView tells the page prefers-color-scheme: light whenever the app's theme is a light one, which it is in a dx build, whatever the phone is set to. dark() asks the system instead, and answers None wherever the page already knows. Make the page follow it with color-scheme, which is what CSS light-dark() resolves against:

let mut plugins = use_context::<NativePlugins>();
if let Some(dark) = plugins.appearance.write().dark() {
    // e.g. set `color-scheme: dark` or `light` on the root element
}

External URLs

let mut plugins = use_context::<NativePlugins>();
plugins.external_url.write().open("https://example.com")?;

Storage

let mut plugins = use_context::<NativePlugins>();

plugins.storage.write().set("session", &token)?;
let token = plugins.storage.write().get("session")?;
plugins.storage.write().remove("session")?;

The type is KeyValueStore, not Storage, because dioxus::prelude already exports a Storage trait — an app glob-importing both would otherwise find the name ambiguous and fail to compile.

Synchronous, unlike most plugins here, because both stores are: a Keychain lookup and a SharedPreferences read are ordinary in-process work and there is nothing to poll for.

Values are held by the platform's own secret store — the Keychain on iOS, and on Android AES-GCM under a key generated in the hardware-backed Keystore, which will perform operations with it but never export it. That is what EncryptedSharedPreferences does underneath; doing it directly avoids pulling Tink in behind a library Google no longer maintains, and this module has no dependencies at all.

An iOS Keychain app must be signed with an application identifier supplied by its provisioning profile. A Dioxus 0.7.9 dx serve --ios simulator bundle is ad-hoc signed without that identifier, so Keychain calls fail with errSecMissingEntitlement (-34018) even though the same API is available in the simulator. Validate storage in a provisioned device build. Adding a Keychain access group to an ad-hoc simulator bundle after it is built is not a substitute for provisioning and can make iOS reject the app at launch.

Three things to know:

  • Key names are stored in the clear on both platforms. Only values are encrypted, so a key name is a label, not a hiding place.
  • The web build encrypts nothing. localStorage is plain text readable by any script on the origin. It is there so one call site works everywhere, not because it is equivalent — anything that would matter if it leaked does not belong in a web build of this.
  • macOS returns an error from every call, and is the one plugin here that does not compile to an inert no-op. A set that silently discarded and a get that always answered None would look like a working cache while losing data.

On Android a value can stop decrypting if the user adds or removes a device lock, which can invalidate the Keystore key. That surfaces as an error from get() rather than as a missing key, so the app can tell "signed out" from "something went wrong".

Camera and Microphone

Capture is ordinary web code. Call navigator.mediaDevices.getUserMedia from the page and it works on both platforms — wry already bridges the WebView permission callbacks. Its WebChromeClient asks Android for CAMERA and RECORD_AUDIO when the page requests capture, and its WKUIDelegate grants WebKit's request so iOS raises the system prompt. This plugin does not touch either, and neither should you: replacing those delegates takes wry's file chooser and JS dialogs with it.

What actually makes capture possible is declaring the permissions, which the Dioxus CLI writes into the manifest and Info.plist:

[permissions]
camera = { description = "Show your swing to your partner" }
microphone = { description = "Talk to your partner" }

# Required on Android for audio capture, and easy to miss.
[android.permissions]
"android.permission.MODIFY_AUDIO_SETTINGS" = { description = "Audio capture" }

Without those, Android refuses before any prompt appears and iOS terminates the app outright. If getUserMedia is failing, check this first — it is almost always the answer.

That last line is not optional, and its absence fails in a confusing way. wry's WebChromeClient asks Android for MODIFY_AUDIO_SETTINGS alongside RECORD_AUDIO when a page requests audio. Requesting a permission the manifest does not declare is denied instantly, and wry then denies the whole request — so getUserMedia fails with NotAllowedError even though RECORD_AUDIO shows as granted and the app never sees a prompt. It is an install-time permission, so no amount of asking at runtime substitutes for the manifest entry. Verified on an API 35 emulator: without the line, NotAllowedError; with it, two tracks.

The plugin covers what JavaScript cannot reach:

use g3_native_plugins::{NativePlugins, PermissionState};

let mut plugins = use_context::<NativePlugins>();

let state = plugins.camera_microphone.write().check_permissions()?;
match state.camera {
    // Ask at a moment you chose, not mid-stream.
    PermissionState::Prompt | PermissionState::PromptWithRationale => {
        plugins.camera_microphone.write().request_camera()?;
    }
    // Neither platform will prompt again. Settings is the only way back.
    PermissionState::Denied => plugins.camera_microphone.write().open_settings()?,
    PermissionState::Granted => { /* start the stream from JS */ }
}

Prompt results arrive on a callback a library cannot hook, so poll check_permissions() after requesting, the same as geolocation.

One interaction worth knowing: if the app also uses the media feature, that plugin claims a .playback audio session, which has no input — a microphone opened under it returns silence. Call set_capturing(true) around capture to move the session to .playAndRecord, and set_capturing(false) after. It is a no-op on Android and unnecessary on iOS for an app that only captures, since WebKit configures the session itself when nothing else has claimed it.

In-App Purchases

let mut plugins = use_context::<NativePlugins>();

// At startup. Not at the point of sale — see below.
plugins.in_app_purchases.write().prepare()?;

plugins.in_app_purchases.write()
    .start_products_request(&["pro.monthly".to_string()])?;
if let Ok(Some(products)) = plugins.in_app_purchases.write().poll_products() { /* show */ }

plugins.in_app_purchases.write().start_purchase("pro.monthly", None)?;
if let Ok(Some(entitlements)) = plugins.in_app_purchases.write().poll_entitlements() {
    for entitlement in entitlements {
        // Verify entitlement.purchase_token on your server, then grant.
        if entitlement.needs_finishing {
            plugins.in_app_purchases.write().finish(&entitlement.transaction_id, false)?;
        }
    }
}

poll_entitlements() is the only place ownership arrives from, whether it came from a purchase, a restore, or the background listener. Poll it for the life of the app, not only around a purchase: both stores deliver transactions that completed while the app was closed — an interrupted payment, a family-shared buy, a renewal, a purchase a parent approved hours later — and only a listener already running catches them. That is why prepare() belongs at startup.

Finish every purchase. finish() is the store's record that the user got what they paid for. Android refunds anything left unacknowledged for three days. Pass consume: true only for a consumable, so it can be bought again.

Verify server-side. purchase_token carries the signed JWS on iOS and the purchase token on Android, both meant to be checked against Apple's or Google's servers. Everything else on an Entitlement is display state read off a device, and a device is not a thing to take financial claims from. This crate deliberately does no verification.

Three places the platforms genuinely differ, none of which are papered over:

iOS Android
expires_at_ms filled in always None — Play does not tell the device, so subscription expiry has to come from the Play Developer API server-side
ProductKind real, from StoreKit one-time products always report NonConsumable; Play doesn't distinguish, the app decides by passing consume
offer_id ignored — StoreKit applies an introductory offer itself, and a promotional one needs a signature this crate can't produce selects a base plan or offer; a subscription can't be bought without one

Play Billing is a real implementation dependency, unlike the compileOnly androidx ones elsewhere here: the host app already carries androidx but has no reason to carry billing, and unlike the location case there is no alternative to weigh — Play billing is only reachable through that library. It is pinned to 7.1.1, the floor Google currently requires; check the deadline before shipping, because they move it.

Geolocation

Declare the permission in Dioxus.toml — the Dioxus CLI maps it to ACCESS_FINE_LOCATION and NSLocationWhenInUseUsageDescription:

[permissions]
location = { precision = "fine", description = "Find courses near you" }

Then ask at runtime, which Android requires separately from declaring it:

use g3_native_plugins::{NativePlugins, PermissionState, PositionOptions};

let mut plugins = use_context::<NativePlugins>();

// Prompt, then poll check_permissions for the answer.
plugins.geolocation.write().request_permissions()?;

// Ask once...
plugins.geolocation.write().start_position_request(PositionOptions::default())?;

// ...and poll wherever the UI updates.
if let Ok(Some(position)) = plugins.geolocation.write().poll_position() {
    println!("{}, {}", position.coords.latitude, position.coords.longitude);
}

Requests are started and polled rather than awaited, because a fix takes seconds and arrives on a platform callback. Blocking the caller would stall a Dioxus effect thread for the duration, and on iOS it would not work at all: CLLocationManager delivers on the main queue, which a blocked worker thread is not. Permission results are polled for the same reason — the answer comes back through onRequestPermissionsResult, an Activity callback a library cannot override from outside, so check_permissions() is the way to read it.

Android fixes come from the platform LocationManager, not Google's fused provider. The fused provider gives better results for less battery, but only by forcing play-services-location on everyone depending on this crate, which is not a trade a library should make for its consumers. An app that wants it can still use it directly.

The web build is inert rather than wrapping navigator.geolocation: a page can call that itself, and routing it through here would put a browser permission prompt behind an API shaped for native asynchrony. macOS is inert too.

Deep Links

Deep linking takes three pieces, and this crate is two of them.

  1. Declaring the links. The Dioxus CLI already does this — [deep_links] in Dioxus.toml writes CFBundleURLTypes and the associated-domains entitlement on iOS, and the intent filters on Android. Nothing here duplicates it.
  2. Proving the claim. Both platforms fetch a file from the site the app says it owns. The deep_links builders below generate them.
  3. Receiving the URL. The deep-links feature. Neither platform hands the link to the WebView, so without this the app opens and the URL is lost.

Receiving

use g3_native_plugins::DeepLinks;

fn main() {
    // As early as possible: see the cold-start note below.
    let mut deep_links = DeepLinks::new();
    let _ = deep_links.prepare();
    dioxus::launch(App);
}

Then drain the queue wherever routing decisions are made:

let mut plugins = use_context::<NativePlugins>();

use_future(move || async move {
    loop {
        while let Ok(Some(url)) = plugins.deep_links.write().take_link() {
            // Route on the URL however the app wants to.
        }
        gloo_timers::future::TimeoutFuture::new(200).await;
    }
});

Links are queued and polled rather than pushed at a listener, which is the opposite of the back-button contract above and deliberately so: a back press is a live gesture that is meaningless once missed, while a deep link is a value that arrives before the app has rendered anything able to receive it. The queue lives on the native side and is shared across plugin instances, so preparing early and reading later from the provider both see the same links.

Cold start on iOS is the one timing-sensitive case. A link that starts the app is delivered before any plugin exists, so it is recovered from the launch options via UIApplication.didFinishLaunchingNotification — which only works if prepare() ran before launching finished. Preparing from a component effect is usually too late for that one case; preparing in main is not. Android has no such constraint: the launch Intent stays readable on the Activity, so timing does not matter there.

Android needs singleTask or singleTop as the host Activity's launch mode for links to arrive while the app is already running. Under the default standard mode Android starts a second Activity rather than calling onNewIntent, and the link shows up as that Activity's launch Intent instead. Observed on an emulator: a link sent to a running app restarted it under a new pid and arrived through the launch-Intent path, which is the fallback working as designed rather than the onNewIntent path. Dioxus.toml has no launch_mode key as of CLI 0.7.9, so setting it needs [android.raw] manifest injection.

On the web the browser hands the app its URL directly and the router already routes it; macOS delivers nothing here. Both are inert, so callers need no cfg of their own.

The iOS implementation adds application(_:continue:restorationHandler:) and application(_:open:options:) to the live app delegate's class at runtime, because the delegate belongs to the windowing layer Dioxus runs on and implements neither. It only ever adds: a delegate that already implements one keeps its own, and the plugin logs instead of displacing it.

Serving the well-known files

The deep_links module is always available — including on the server — and generates the .well-known JSON values:

g3_native_plugins::ios_app_site_association_route! {
    team_id: "TEAMID",
    bundle_id: "com.example.App",
    paths: ["/games/*/join"],
}

g3_native_plugins::android_asset_links_route! {
    package_name: "com.example.app",
    sha256_cert_fingerprints: ["AA:BB:CC"],
}

System Back

This is about the back event, not the button. What raises it differs by platform — Android's system back gesture or hardware key, an iOS swipe in from the left screen edge — and neither reaches a WebView-hosted web app on its own. Android delivers back to the Activity, never to the WebView, so the app exits on the first press however it is written. iOS gives the edge swipe meaning only inside a UINavigationController, which a bare WKWebView is not, so the swipe lands on nothing.

Both plugins take the gesture and dispatch the same cancelable g3nativeback event on the WebView's window, so one web-side listener serves both. Neither calls browser history.back(): Dioxus keeps native-app route history in Rust rather than in WebView history.

g3-route-transitions provides the standard integration. Enable its native-back feature and call use_native_back_navigation::<Route>() once in a routed layout; it manages interception and invokes the animated Dioxus pop. No application-specific event bridge is needed.

Interception is off until asked for, because only the app knows whether there is anywhere to go back to. Leaving it on at the root of the stack means the user cannot leave on Android, and swallows edge swipes that should do nothing on iOS. Higher-level integrations can call fall_through() to pass one intercepted press to Android's next Back handler without recursion; on iOS there is no default handler to pass it to — an app may not exit itself — so the call is accepted and the gesture dropped.

For lower-level use without g3-route-transitions, interception remains available directly:

use dioxus::prelude::*;
use g3_native_plugins::NativePlugins;

let mut plugins = use_context::<NativePlugins>();
let navigator = use_navigator();

// Re-run wherever the route changes.
use_effect(move || {
    let _ = plugins.back_button.write().set_intercepting(navigator.can_go_back());
});

On the web the browser owns back, and macOS has no equivalent gesture, so both are inert — callers need no cfg of their own.

The Android implementation resolves its Kotlin bridge through the Activity's application class loader. This matters because Dioxus effects run on a native thread, where JNI's default FindClass otherwise sees only the system loader.

The iOS implementation attaches a UIScreenEdgePanGestureRecognizer to the WKWebView and requires the WebView's scroll pan to fail before it, the way UIKit gives a navigation controller's pop gesture priority over content. It commits on release, past a short distance or a throw, so a stray touch near the bezel does not navigate. WebKit's own back/forward swipes are turned off for the same reason the plugin avoids history.back().

Media

let mut plugins = use_context::<NativePlugins>();
plugins.media.write().prepare()?;
plugins.media.write().set_playback_active(true, "Episode 4")?;
plugins.media.write().enter_picture_in_picture(16, 9)?;
plugins.media.write().set_orientation("landscape")?;

Both native implementations keep a WebView <video> playing once the app stops being frontmost and give it lock-screen controls, by the means each platform requires: a foreground service and picture-in-picture actions on Android, a .playback AVAudioSession with MPNowPlayingInfoCenter metadata and MPRemoteCommandCenter commands on iOS. Controls on either platform drive the same player element through the same script.

Two things iOS can only ask for, not enforce, so the host app has to allow them: picture-in-picture needs the WKWebView built with allowsPictureInPictureMediaPlayback (the configuration is immutable once the WebView exists), and set_orientation is honored only within the orientations the Info.plist and root view controller permit. The enter_picture_in_picture dimensions are ignored on iOS, where AVKit takes the aspect ratio from the video track itself; they are kept in the signature for a call site shared with Android.

Notifications

use g3_native_plugins::{Notification, NotificationEvent, PermissionState, Schedule};

fn main() {
    // Early: a tap that launched the app is delivered during launch, and only
    // to a listener already in place.
    let _ = g3_native_plugins::Notifications::new().prepare();
    dioxus::launch(App);
}

let mut plugins = use_context::<NativePlugins>();

if plugins.notifications.write().check_permissions()? != PermissionState::Granted {
    plugins.notifications.write().request_permissions()?;
}

plugins.notifications.write().show(&Notification::new(1, "Round saved").body("18 holes, 72"))?;
plugins.notifications.write().show(
    &Notification::new(2, "Tee time in 30 minutes")
        .extra("route", "/games/7")
        .schedule(Schedule::At { at_ms: tee_time_ms - 1_800_000, allow_while_idle: true }),
)?;

// Wherever the app polls:
while let Ok(Some(event)) = plugins.notifications.write().take_event() {
    if let NotificationEvent::Action { action_id, notification, .. } = event {
        // action_id is "tap" for the notification itself, else a button id.
    }
}

The counterpart of Tauri's notification plugin: permission, immediate and scheduled notifications (once, or every N minutes/hours/days/weeks), pending and delivered lists, buttons with optional text replies (ActionType), and Android channels. Taps and foreground deliveries are queued natively and polled, the same contract as deep links, so nothing is lost for want of a listener.

Things each platform imposes:

  • Android 13+ asks for POST_NOTIFICATIONS at run time, which is what request_permissions() raises. The plugin's manifest declares it.
  • Android 8+ takes sound and importance from the channel, not the notification. Create channels with create_channel and post to them with Notification::channel. A default channel is created on first use.
  • Android scheduling uses AlarmManager, re-armed after reboot and app update. Alarms are exact only if the app holds SCHEDULE_EXACT_ALARM, which this crate deliberately does not declare — Play restricts it to alarm and calendar apps. Without it Android may deliver a few minutes late.
  • Android's status-bar icon must be a white silhouette. Name a drawable with Notification::icon; the app icon fallback renders as a white square.
  • iOS refuses repeats more often than once a minute, and has no channels — the channel calls do nothing there.
  • The plugin sets the host Activity's launch mode to singleTask, as the media feature does, because a notification tap otherwise starts a second Activity, which wry cannot host.

Push Notifications

use g3_native_plugins::{FirebaseOptions, PushEvent, PushNotifications};

fn main() {
    let _ = g3_native_plugins::Notifications::new().prepare();
    let _ = PushNotifications::new().prepare();
    dioxus::launch(App);
}

// From the Firebase console, or the app's google-services.json.
let firebase = FirebaseOptions {
    application_id: "1:1234567890:android:abc123".into(),
    api_key: "AIza...".into(),
    project_id: "my-project".into(),
    sender_id: "1234567890".into(),
};

plugins.notifications.write().request_permissions()?;
plugins.push_notifications.write().register(Some(&firebase))?;

while let Ok(Some(event)) = plugins.push_notifications.write().take_event() {
    match event {
        PushEvent::Token(token) => { /* send token.service + token.token to your server */ }
        PushEvent::Message { data, title, body } => { /* arrived in the foreground, or data-only */ }
        PushEvent::Opened { data, .. } => { /* the user tapped a push */ }
        PushEvent::RegistrationFailed(error) => { /* usually a missing entitlement */ }
    }
}

Remote push through Firebase Cloud Messaging on Android and APNs on iOS. The token is tagged with the service it belongs to, so the server knows which API to send through.

  • Android needs a Firebase project with the app registered. Firebase is normally configured by the google-services Gradle plugin, which a generated Dioxus Gradle project cannot run, so the four values are passed to register() and Firebase is initialized from them at run time. The firebase-messaging dependency lives in its own Gradle module, which is why push is a separate feature: an app with only local notifications does not carry Firebase.
  • iOS needs the Push Notifications capability: an aps-environment entitlement from a provisioning profile that has push enabled, plus the remote-notification background mode for data-only pushes. Without the entitlement, APNs refuses and the refusal arrives as RegistrationFailed. The token callbacks are added to the app delegate at run time, the same technique as deep links, and only where the delegate has none of its own.
  • Neither platform displays a push that arrives while the app is in the foreground — Android never does, and iOS is told not to so the two match. It arrives as PushEvent::Message; show it with Notifications::show if it should be seen.
  • Seeing a push needs the notification permission; receiving a data-only push does not.

Over-the-Air Updates

The Tauri updater's model — signed releases from an update server, checked against a public key compiled into the app — applied to what a mobile store permits.

What can and cannot be updated

The Rust side of a Dioxus app cannot be updated over the air, by this or any updater. It is native machine code signed as part of the app. iOS will not execute a native library that was not signed with the app, and both stores' rules forbid an app replacing its own native code outside review. React Native's JS bundle is different in kind, not degree: it is interpreted by a JavaScript engine, and Apple's guideline 3.3.1(B) and Play's device and network abuse policy both carve out exactly that — code run by WebKit or a JavaScript engine, that does not change what the app is for.

So updater updates files the WebView loads or the app reads: HTML, CSS, JavaScript, WebAssembly run by the WebView, images, fonts, JSON, content. How much of an app that covers depends on where its logic lives:

  • Styles, images, copy, and configuration: any Dioxus app.
  • Logic: only what runs in the WebView — a web page, script, or a WebAssembly build shown in an iframe — not the components in the native binary.

A native change still needs a store release. The runtime version (below) makes sure a bundle built for one native release is never served by another.

Setup

use g3_native_plugins::{Updater, UpdaterConfig, UpdaterState};

// `minisign -G` or `tauri signer generate`. Only the public half ships.
const UPDATER_PUBLIC_KEY: &str = "RWQ...";

fn main() {
    let config = UpdaterConfig::new(UPDATER_PUBLIC_KEY, "1.4.0") // the embedded content's version
        .endpoint("https://updates.example.com/{{target}}/{{runtime_version}}/{{current_version}}");
    // Before anything reads a bundle file: this is where a downloaded update
    // is installed, or a broken one rolled back.
    let _ = Updater::new().launch(config);
    dioxus::launch(App);
}

// Once the app is up on the new bundle, say so. Skip this and the next launch
// rolls back.
plugins.updater.write().notify_ready()?;

plugins.updater.write().start_check()?;
// ...then poll:
match plugins.updater.write().state() {
    UpdaterState::Available(update) => plugins.updater.write().start_download()?,
    UpdaterState::Downloading { progress, .. } => { /* progress.bytes_done / bytes_total */ }
    UpdaterState::Ready(update) => { /* active next launch, or apply_now() */ }
    UpdaterState::Failed(error) => { /* nothing was installed */ }
    _ => {}
}

Serve the active bundle to the WebView from a Dioxus asset handler, falling back to the embedded copy when no bundle is active or it lacks the file:

use dioxus::mobile::{use_asset_handler, wry::http::Response};
use g3_native_plugins::{bundle_content_type, Updater};

use_asset_handler("bundle", |request, responder| {
    let path = request.uri().path().trim_start_matches("/bundle/").to_string();
    let bytes = Updater::new()
        .resolve_asset(&path)
        .and_then(|file| std::fs::read(file).ok())
        .or_else(|| embedded_asset(&path)); // e.g. from include_bytes!
    let response = match bytes {
        Some(bytes) => Response::builder()
            .header("Content-Type", bundle_content_type(&path))
            .body(bytes),
        None => Response::builder().status(404).body(Vec::new()),
    };
    responder.respond(response.unwrap());
});
// Then reference files as "/bundle/app.css", "/bundle/index.html", ...

Server format

The endpoint answers 204 No Content for "nothing new", or a release in the same shape a Tauri update server returns — a per-platform table, or a single url and signature for a server that already chose the platform from the URL. Platform keys are ios-aarch64, android-aarch64, and so on, falling back to plain ios or android:

{
  "version": "1.4.1",
  "notes": "Fixes the scorecard layout",
  "pub_date": "2026-09-24T12:00:00Z",
  "platforms": {
    "ios": { "url": "https://cdn.example.com/1.4.1/manifest.json", "signature": "..." },
    "android": { "url": "https://cdn.example.com/1.4.1/manifest.json", "signature": "..." }
  }
}

Where Tauri's url points at an installer, here it points at a bundle manifest: every file in the bundle and its SHA-256. The signature is over the manifest's exact bytes, and the hashes carry that guarantee to each file. Files are fetched relative to the manifest unless an entry gives its own url or the manifest a base_url:

{
  "version": "1.4.1",
  "runtime_version": "1.4.0",
  "files": [
    { "path": "index.html", "sha256": "ff2e...7118", "size": 13 },
    { "path": "css/app.css", "sha256": "8dfb...1e3d", "size": 21 }
  ]
}

Sign it with minisign -S -s updater.key -m manifest.json and put the contents of manifest.json.minisig in signature, or use tauri signer sign and its base64 output as is. Both key and signature formats are accepted either way.

What is checked, and when

  • The manifest is verified against the public key before it is parsed.
  • Its version must match what the release advertised (the release JSON is unsigned; the manifest is the authority), and be newer than what is running.
  • Its runtime_version must equal the app's. It defaults to the app's version (CFBundleShortVersionString, versionName), so every store release starts clean; pin it with UpdaterConfig::runtime_version to keep bundles across native releases that did not change what the bundle relies on. When it changes, every downloaded bundle is discarded.
  • Every file must match its hash and size. Files unchanged since the active bundle are copied rather than downloaded.
  • Paths are relative and cannot climb out of the bundle directory.
  • The bundle is staged, then moved into place and installed at the next launch — never under a running app, unless it asks with apply_now().
  • A new bundle launches on trial. If that launch ends without notify_ready(), the next launch goes back to the previous bundle and that version is never offered again.
  • A downloaded bundle no newer than the embedded content (after a store update that shipped it) is discarded in favor of the embedded copy.

Downloads use the platform's HTTP stack (URLSession, HttpURLConnection), so App Transport Security, network security config, and system proxies apply as they would to anything else in the app. Bundles live in storage excluded from backup.

License

Licensed under either of MIT or Apache-2.0 at your option.