celo-org / celo-org/docs

task: make the assistant's existing telemetry reportable (GA4 custom dimensions, gtag after GTM swap, unanswered-question review)

Open
#2,307 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
MDX
Stars
90
Forks
382
Avg merge
3d 9h
Merged PRs (30d)
35

Description

The docs assistant already emits GA4 events and already logs questions server-side. Neither is reportable yet, for two separate reasons. Both are configuration, not code.

## What already exists

**Client**, `widget.js` in `celo-org/docs-ai-assistant` — seven events through the page's existing `window.gtag`:

| Event | Parameters |
|---|---|
| `assistant_question` | `answered`, `escalated`, `truncated` |
| `assistant_error` | `from_api`, `status` |
| `assistant_citation_click` | `href` |
| `assistant_opened`, `assistant_escalate`, `assistant_new_chat`, `assistant_copy` | — |

**Server**, `app/api/chat/route.ts` — `logQuestion()` pushes `{question, model, citedUrls, answered, timestamp, refused}` onto the Upstash Redis list `docs-assistant:questions`, trimmed to the most recent 10,000.

## Gap 1: the event parameters are not registered as custom dimensions

GA4 drops event parameters that are not registered. The events arrive; `answered`, `escalated`, `truncated`, `from_api`, `status` and `href` cannot be broken out in any report until they are added as **event-scoped custom dimensions** in the GA4 property for `G-0CXEKQ81V2`.

`answered` is the one that matters — it is the share of questions the assistant could not answer from the docs, which is the docs-gap rate.

## Gap 2: `track()` is a silent no-op without `window.gtag`

```js
function track(name, params) {
if (typeof window.gtag === 'function') window.gtag('event', name, params || {});
}
```

`window.gtag` is provided today by `integrations.ga4` in `docs.json`. #2300 replaces that with `integrations.gtm`. GTM's Google tag should still define the global, but this exact configuration has already produced one silent failure — the container shipped with its own ID in the Tag ID field, so it loaded, fired, errored nowhere, and sent nothing to GA4. Verify rather than assume.

## Gap 3: nothing reads the Redis list

The list is the actual docs-gap signal — the uncited questions in it are the pages that need writing — and there is no routine for reading it. A monthly pull of entries where `answered: false` would close the loop that #2250 used to justify building the assistant instead of paying for Mintlify Pro.

## Acceptance criteria

- [ ] The six assistant parameters registered as event-scoped custom dimensions in GA4
- [ ] After #2300 merges, `typeof window.gtag === 'function'` confirmed on a published page, and one `assistant_question` event seen in GA4 Realtime
- [ ] A stated cadence and owner for reviewing `docs-assistant:questions` where `answered: false`
- [ ] ANALYTICS.md records whichever of these lands

Refs #2250, #2286, #2300.

Contributor guide

Open the contributing guide

Research direction

Review widget.js, app/api/chat/route.ts, docs.json, and the ANALYTICS.md requirements, then verify the post-#2300 published-page behavior in GA4 Realtime and inspect the docs-assistant:questions Redis list. Done means the six event parameters are registered, an assistant_question event is confirmed, unanswered questions have a stated review cadence and owner, and ANALYTICS.md records the results.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, redis, typescript
Domain
analytics, documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.