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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
# g3-native-plugins

[![CI](https://github.com/g3techhq/g3-native-plugins/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/g3techhq/g3-native-plugins/actions/workflows/ci.yml)
[![Crates.io](https://img.shields.io/crates/v/g3-native-plugins.svg)](https://crates.io/crates/g3-native-plugins)
[![docs.rs](https://docs.rs/g3-native-plugins/badge.svg)](https://docs.rs/g3-native-plugins)
[![License](https://img.shields.io/crates/l/g3-native-plugins.svg)](#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:

```toml
[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.

```rust,ignore
use dioxus::prelude::*;
use g3_native_plugins::NativePluginsProvider;

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

## Clipboard and Share

```rust,ignore
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:

```rust,ignore
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:

```rust,ignore
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

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

## Storage

```rust,ignore
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:

```toml
[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:

```rust,ignore
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

```rust,ignore
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`:

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

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

```rust,ignore
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

```rust,ignore
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:

```rust,ignore
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:

```rust,ignore
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:

```rust,ignore
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

```rust,ignore
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

```rust,ignore
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

```rust,ignore
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

```rust,ignore
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:

```rust,ignore
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`:

```json
{
  "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`:

```json
{
  "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](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE) at your option.