POST /api/analytics/track

Forward a client-driven engagement event (or app_install) to GA4 — either a single event or a batch. Public endpoint — accepts both anonymous callers (needed for pre-login events like app_install) and authenticated ones (the request is attributed to req.user.id when a valid session is present).

Headers:

Content-Type: application/json
Authorization: Bearer <access_token>   # optional

Request Body — single event:

{
    "eventName": "content_search",
    "gaClientId": "GA1.2.123456789.1234567890",
    "platform": "ios",
    "gclid": "Cj0KCQiA...",
    "params": {
        "searchTerm": "grace"
    }
}

Request Body — batch (up to 25 events):

{
    "gaClientId": "GA1.2.123456789.1234567890",
    "platform": "ios",
    "gclid": "Cj0KCQiA...",
    "events": [
        { "eventName": "scripture_view", "params": { "book": "John", "chapter": 3 } },
        { "eventName": "content_search", "params": { "searchTerm": "grace" } }
    ]
}

gaClientId/platform/gclid are shared across the whole batch — GA4 Measurement Protocol accepts only one client_id (+ optional user_id) per call, so a batch is inherently scoped to one client/device. Each batch item may also carry an optional timestampMicros (Unix epoch microseconds) to report when the event actually occurred, forwarded to GA4 as a per-event timestamp_micros override.

eventName allowlist: app_install, session_active, content_search, book_navigation, scripture_view, topical_index_view, outline_view. Any other value is rejected — event names are not forwarded to GA4 free-form. Applies to both the single-event eventName and every item's eventName in a batch.

Limits:

• events array: 1–25 items (GA4's own hard limit per call) — larger batches are rejected with a 400, not silently chunked
• params string values: 100 characters or fewer (GA4 silently truncates/drops longer values — rejected here instead so the client can fix it)

Response (202 Accepted):

{
    "message": "Event accepted"
}

Error Responses:

// 400 - Validation error (bad eventName, missing gaClientId/platform, batch too large,
//        param value too long, or neither eventName nor events provided)
{
    "message": "Validation error",
    "code": "VALIDATION_ERROR",
    "errors": [ ... ]
}

// 429 - Rate limited
{
    "error": "Too many analytics events",
    "message": "Too many analytics events from this IP, please try again later.",
    "code": "RATE_LIMIT_EXCEEDED"
}

Notes:

• Always returns 202 once validation passes, regardless of whether the downstream GA4 call actually succeeds — a GA4 outage or missing credentials (e.g. the web Measurement Protocol secret, not yet configured) is never surfaced to the client
• Rate limited to 60 requests per 15 minutes per IP
• gaClientId and platform are required; gclid is optional; exactly one of eventName or a non-empty events array is required
• session_active is listed in the allowlist for completeness but is not normally sent via this endpoint — it fires server-side from /api/auth/refresh instead
• A batch mixing app_install with engagement events costs one GA4 call, not two — app_install is just another allowlisted event name
• As an alternative to this endpoint, a batch can be attached directly to a token refresh call (POST /api/auth/refresh) — see that endpoint's docs for the shape