# Native and mobile app onboarding

Use this adapter for Expo, React Native, Flutter, and native iOS or Android
projects. The common setup-session contract remains in `connect.md`.

## Completion contract

- GA4 or Firebase Analytics is present in production builds.
- A production environment property excludes internal, simulator, debug, and
  TestFlight traffic from product metrics.
- GA4 Daily and Streaming BigQuery export is active.
- The correct iOS and Android streams are pinned when a property contains more
  than one app.
- App Store Connect and RevenueCat are connected when requested.
- Every configured source passes `doctor --as-cron`.
- The scheduled refresh is loaded.
- The Metricsjar dashboard has no red pipe.

## 1. Detect before changing code

Identify the framework, bundle identifiers, Firebase projects, analytics SDK,
release channels, and store configuration. Reuse existing analytics rather than
adding a second SDK.

Treat Search Console as belonging to the product's marketing website. Do not
create a Search Console property for a native binary.

## 2. Instrument production analytics

Create or reuse one GA4/Firebase stream per native app. Add the provider's
supported SDK through the framework's normal configuration path.

Set a stable environment property, for example `env=prod`, on every production
event. Record the exact key and value in the Metricsjar app configuration.
Verify that release traffic passes the filter and development traffic does not.

Define an initial event taxonomy from real product actions. Start with lifecycle
and value-bearing events; do not send email addresses, names, free-form user
content, or internal identifiers to GA4.

Build and exercise the app through its normal simulator, emulator, or device
workflow. Verify events in GA4 Realtime before enabling the export.

## 3. Enable the BigQuery export

Link the GA4 property to the confirmed GCP project. Enable Daily and Streaming
export, select only the correct app streams, and record the enablement date.
There is no backfill.

Register the expected `analytics_<property-id>` dataset before its first tables
appear. A verified link with no tables is yellow/warming.

## 4. Optional store and revenue sources

### App Store Connect

Collect the key id, issuer id, readable `.p8` path, and vendor number. Store the
key outside the repository. Verify it in the scheduler environment.

Metricsjar may create an ongoing Analytics Report Request. Apple can take 1–2
days to prepare the first reports; report that as warming.

### RevenueCat

Store the secret key in `~/.config/metricsjar/.env`. Discover the project from
the key rather than asking the user for an internal project id. Verify product
and app scope before displaying money metrics.

## 5. Register and finish

Add the app block to the site configuration, refresh, install the scheduler,
and run:

```sh
bun ~/.metricsjar/cli.ts onboard verify <slug>
```

The dashboard may launch while GA4 or App Store reports are warming. Correct
yellow sources satisfy completion; red sources do not.