# Google Analytics 4

CLItrail sends each attributed install to GA4 through the Measurement Protocol, on the client ID the visitor's browser had, so the install lands on the same GA4 user.

## Set it up

1. Create an API secret
  In Google Analytics, open **Admin → Data collection and modification → Data streams**, choose your web stream, then **Measurement Protocol API secrets → Create**. Copy the secret value.
2. Add the destination
  In CLItrail, open **Destinations → Add destination → Google Analytics 4**. Enter the measurement ID (`G-…`) and the API secret. Set the session timeout to match your GA4 tag settings (1 to 240 minutes, default 30).
3. Prepare the property
  Mark `cli_install_completed` (or `cli_first_run`) as a key event. Register `acquisition_url_id` as an event-scoped custom dimension to report on the install page.
4. Test, then go live
  GA4 needs no terms confirmation or domain verification.

## What is sent

```json
{
  "client_id": "1864235781.1790171840",
  "timestamp_micros": 1790172131000000,
  "events": [{
    "name": "cli_install_completed",
    "params": {
      "event_id": "6f2da9610246dec311f2b793f7c32902",
      "acquisition_url_id": "url_96f86d390b35cfa7",
      "attribution_method": "opfs_marker",
      "attribution_policy": "latest_visit",
      "session_id": 1790171840
    }
  }]
}
```

The measurement ID and API secret travel as URL parameters, as the Measurement Protocol requires. The URL is built at send time and never stored or logged. `attribution_method` is `opfs_marker`, `explicit_handoff` or `reconstructed`; installs matched by the network matching of earlier versions say `network_match`.

- **Client ID.** From the touch your attribution policy points to among those where the SDK captured a client ID for this measurement ID: the most recent under latest visit, the earliest under first visit. No client ID, no event.
- **Parameter length.** GA4 documents a 100-character limit for parameter values, so a longer `event_id` or URL-ID is sent as its first 59 characters, a dot and 40 hex characters of its SHA-256: still unique and recognisable.
- **Session.** `session_id` is included only when the install arrives within 24 hours of the session's start and within the session timeout of the visit. The 24-hour limit is checked again at send time. Otherwise the event carries the client ID alone.
- **Time.** The real install time. GA4 accepts events up to 72 hours old; older queued events expire.
- **No retries.** The Measurement Protocol has no exactly-once guarantee, so a request with an unknown outcome is marked `uncertain` and never resent. `submitted` means GA4 answered with success, not that it processed the event.
- No engagement time is invented, so Realtime engagement reports are not promised.