Duolith docs

0071. Consent gates analytics and crash reporting, by category, and honours Global Privacy Control

  • Status: Proposed
  • Date: 2026-11-14
  • Decided by: production adapters agent, pending the integrator
  • Planning item: Roadmap milestone 3, "consent screen and privacy declarations"

Context

An app must not send analytics or crash data before the person agrees, must remember the answer, and should respect the Global Privacy Control signal (navigator.globalPrivacyControl), which several jurisdictions treat as an opt-out of sharing.

Decision

  • Consent is state with categories: by default necessary (required, never asked), analytics (refused under GPC) and crashes. Apps may name their own. granted(category) and decided are reactive, so a banner and a settings screen follow them.
  • Nothing is recorded or sent while a category is not granted. Analytics drops events rather than holding them, and refusing drops whatever waits. Crash reports made before consent are not kept. When analytics is granted, the screen the person is on is counted.
  • The choice is kept on the device (localStorage, key duolith.consent) with a version; raising the version asks again.
  • GPC refuses its categories whatever is chosen: acceptAll() leaves analytics off, choosable("analytics") is false, and the banner says why.
  • The banner is a documented component, not a kit part (examples/production/components/ConsentBanner.duo), built from kit Buttons and tokens, because its words and categories belong to each app. A kit part can follow once two apps agree on its shape.

Alternatives considered

OptionWhy not
Queue events until consent, send them afterCollecting before consent is itself the problem the banner exists to prevent
GPC as only a default the person can override in the bannerGPC is a standing instruction; a banner tap should not quietly undo it
A kit ConsentBanner part nowIts text, categories and layout differ per app; a part would be mostly overrides

Consequences

  • The build writes the stores' privacy declarations into dist/privacy/: PrivacyInfo.xcprivacy for iOS and data-safety.json with the answers for Play's data safety form. They follow from what the pages start: startAnalytics declares product interaction (purpose Analytics), startCrashReporting crash data and other diagnostics (purpose App functionality), none linked to the person or used for tracking, since the adapters send only a random session id. Consent, the locale, the colour scheme and queued writes kept on the device declare UserDefaults with reason CA92.1. Each adapter is judged on its own: its data is optional in Play's terms only when every call that starts it passes a consent property (crash reporting without one is declared required even when analytics waits). httpTransport URLs written as text are the endpoints, with encryption in transit when none is http://; an absolute URL may be a third party's, so sharing is then left for the developer to answer, with a note naming the host. Crash data is declared linked when includePaths: true sends paths. The manifest holds only fixed text, so no file name or address can break its XML; a browser test parses the production example's manifest with Chromium's XML parser. A custom transport leaves the endpoints for the developer to answer, and the file says so.
  • An app that passes a user id in context, or sends to a tracking provider, must change the declarations by hand; the build cannot see that. - Platform effects are declared from the same analysis that writes their permissions. The analyzer's effects_used reads each page's @duolith/effects imports (not text that looks like one), and each name counts by its contract in spec/effects/effects.yaml, so mockStore is purchases and mockSignInBackend sign-in. Key-value storage declares UserDefaults with reason CA92.1. Secure storage keeps its values in the iOS Keychain or the Android Keystore: the Keychain is not a required-reason API, so the manifest names no reason for it, and data-safety.json lists it under keptSecurely with a note. Sign-in keeps the user in key-value storage and the credentials in secure storage, and declares an email address and a user id, linked to the person and required (a note says to mark them optional if the app works without signing in). The camera declares photos, push a device id (its token) and purchases the purchase history, each optional, and linked to the person when the app also signs people in; a note says to remove the photos entry if photos never leave the device. Permission declarations stay in dist/native/ (decision 0051).