Effects on iOS and Android: sign-in, push, purchases and the camera
Every effect in @duolith/effects works in a native build. A page imports it as it does for the web, and the build gives it the shell's platform. This page covers what an app has to set up for the four that need more than an import. examples/effects shows them all on the web; its native build is refused while the shells cannot receive links (below) and because it uses two mocks. The fixture packages/engine/test/fixtures/native-effects builds for native:
duolith build packages/engine/test/fixtures/native-effects --target native
Decisions: 0048 (the bridge), 0051 (declarations), 0110 (these four on native).
Sign-in
Configure the backend and the providers once, in the root layout, as on the web:
// pages/_layout.duo
signIn.useBackend(myBackend);
signIn.configure("apple", { clientId: "com.example.app", redirectUri: "https://example.com/auth/apple" });
signIn.configure("google", { clientId: "1234.apps.googleusercontent.com", redirectUri: "com.example.app:/callback" });
| Provider | iOS | Android |
|---|---|---|
Apple, with no authorizationEndpoint | Sign in with Apple's system sheet | Apple's page in a Custom Tab |
Google, with no authorizationEndpoint | Google's page in ASWebAuthenticationSession | Credential Manager's account sheet |
Either, with an authorizationEndpoint | That page in ASWebAuthenticationSession | That page in a Custom Tab |
Apple's sheet on iOS and Credential Manager on Android hand the backend an ID token rather than a code. exchangeCode gets idToken and nonce, with codeVerifier "" (Apple's also carries a code). Check the token's signature, audience and nonce claim against authorization.nonce. Every other flow returns a code with PKCE to redirectUri, as on the web. The app's own scheme works everywhere. An https redirect needs iOS 17.4, or an app link on Android.
To pretend to be a provider with no network, as examples/effects does, write the endpoint and the redirect as paths of the app:
signIn.configure("google", { clientId: "demo", redirectUri: "/callback", authorizationEndpoint: "/mock-provider" });
Links back to the app: not yet on native (E0402)
A magic link opens the app from an email, and on Android a provider's page in a Custom Tab returns to redirectUri as a link that opens the app. Both finish only when the shell hands that link to sign-in, which the iOS and Android shells do not do yet. So a native build fails with E0402 at:
- each
signIn.sendMagicLink,completeMagicLinkandconfirmMagicLink; signIn.configure("apple", …)with Apple's own endpoint (a Custom Tab on Android);signIn.configure(provider, { authorizationEndpoint })with an endpoint that is not a path of the app.
Settings the page's text does not show fail on the phone with E0402 when the sign-in starts, before anything opens. In a native build, sign in with Google and no authorizationEndpoint (Credential Manager on Android, the browser sheet on iOS, which needs no link), with a password, or with a provider at a path of the app. The web build signs in every way.
Once the shells deliver links, a magic link that opens the app and carries magic-link= finishes the sign-in by itself, when it opens the screen it was sent from: no page has to handle it.
Push
Push on Android needs the app's Firebase configuration. Download google-services.json from the Firebase console (Project settings, Your apps) and put it at the project's root. The build turns it into Android resources. Without the file, duolith build --target native fails with E0400 at each import of push. With a file that is not Firebase's, or one with no Android app whose package name is the app's application id (dev.duolith.shell until the app has an id of its own), it fails with E0401. On iOS, the build writes the aps-environment entitlement as development. An App Store export signs it with the distribution profile's value instead.
push.subscribe() gives { endpoint }, which is the device's APNs token (hex) or its FCM token. Send it to your server. A notification shown with push.notify(title, { screen }), or a remote one whose payload has screen, opens that screen when tapped. That includes the tap that launched the app. On Android a tap counts only for a push the app received itself, so another app cannot start it with a made-up tap.
Purchases
purchases.load(ids) loads the products from the App Store (StoreKit 2, iOS 15 and later) or Google Play (Play Billing). buy and restore work as on any target. Each purchase is finished (iOS) or acknowledged (Android), so the store does not refund it. Use purchases.useStore(mockStore(...)) to run the flow without a store account, on the web (a native build refuses a mock, E0432). Only one-time products are supported.
On Android a purchase counts only once it is checked. Give the app its Google Play licence key (Play Console, Monetization setup, Licensing), as the Gradle property duolith.playLicenceKey; each purchase's signature is checked against it. A shell can pass a PurchaseVerifier of its own instead, such as one that asks the app's server to check the purchase token. Without either, purchases.available is false and unavailableReason says why. A purchase Play does not acknowledge fails with E0229 and is not granted; "already owned" counts only when Play's list of purchases holds it; and a second buy while one is open fails with E0229.
The camera and the photo library
camera.capture({ facing, maxWidth }) opens the system camera. It resolves a JPEG in the app's cache, as a file: address that <Image> shows, or undefined when cancelled. Leaving the screen closes the camera. The photos last while the app runs; the next launch clears an earlier run's.
A photo from the library comes through picker.pick({ kind: "image" }), which opens the system's picker and needs no permission. There is no "photos" permission.
What still needs a device
The Kotlin is compiled and unit-tested, and the TypeScript is tested in Lynx for Web. The Swift has not been compiled, and none of it has run on a phone. The checks are in native/DEVICE-CHECKLIST.md.