# Events, consent, attribution, and privacy

## Consent states

| State | Collection behavior |
| --- | --- |
| `unknown` | No events or anonymous identity are created |
| `granted` | Allowlisted events can be queued and delivered |
| `denied` | Queued events and attribution are cleared |

Revoking consent aborts active delivery. `reset()` also erases the anonymous
install and session identity.

## Convenience events

| API | Emitted event | Added property |
| --- | --- | --- |
| `trackScreen(name)` | `screen_viewed` | `screen_name` |
| `trackTap(target)` | `tap_recorded` | `target` |
| `trackRide(action)` | `ride_<action>` | none automatically |

Custom event names must match `^[a-z][a-z0-9_]{0,63}$`.

Recommended ride events are `ride_requested`, `ride_matched`, `ride_started`,
`ride_completed`, and `ride_cancelled`.

## Canonical properties

| Property | Value type |
| --- | --- |
| `eta_minutes`, `match_seconds`, `query_length`, `result_count` | Integer from 0 through 1,000,000 |
| `entry_kind`, `screen_name`, `target`, `place_kind`, `vehicle_class`, `estimated_fare_bucket`, `duration_bucket`, `stage`, `reason_code` | Lowercase categorical string |

Categorical values match `^[a-z0-9][a-z0-9_-]{0,63}$` and cannot contain a run
of seven digits. Unsupported keys and invalid values are discarded before local
persistence. The backend validates the same allowlist again.

Never submit names, email addresses, phone numbers, postal addresses, precise
coordinates, free-form search text, passwords, tokens, advertising identifiers,
device fingerprints, customer or driver IDs, tenant/offer/affiliate IDs, payout,
revenue, amount, or currency.

## Attribution

The SDK reads only a UUID `click_id` from a URL. A click captured while consent
is unknown stays in memory and is persisted only after consent is granted. Each
event snapshots the current click; a later click never retroactively changes an
older queued event.

The backend accepts attribution only when the click belongs to the write key's
tenant and offer and the event time is inside the offer attribution window. The
backend derives the affiliate; the application cannot choose it.

## Local identity and server storage

The SDK creates random install and session UUIDs after consent. Sessions rotate
after 30 minutes of inactivity by default. The ingestion service stores HMAC
pseudonyms of those identifiers, not the raw client identifiers.

Analytics events are behavioral evidence. They cannot approve conversions,
calculate payouts, or replace the authenticated server-to-server `/pb` flow.