msos/docs/GA4-ASSISTANT-REPORT.md

Reading "Ask MSOS" questions in Google Analytics

The assistant sends one Google Analytics event every time someone asks a question (only if they accepted cookies). This guide shows how to see those questions — your real FAQs and, most valuably, the questions it couldn't answer (so you know what to add next).

Property: G-WVYV807VSS. You need Editor/Admin access to that GA4 property.

---

What gets sent

Event name	assistant_query
q	the question text (first 120 chars)
result	curated (great answer) · search (found pages) · none (no answer — a gap!)
q_lang	language of the question: en / mk / si
page_lang	language of the page they were on

---

Step 1 — Register the parameters (one-time, required)

GA4 hides custom parameters until you register them as custom dimensions. Do this once:

1. GA4 → Admin (gear, bottom-left) → Custom definitions → Create custom dimension.
2. Create four dimensions, all with Scope = Event:

   Dimension name	Event parameter
   Question	q
   Result	result
   Question language	q_lang
   Page language	page_lang

3. Click Save for each.

⚠️ Data only starts collecting into these dimensions from the moment you create them (it isn't retroactive), so set them up early. Reports take 24–48 h to populate — but you can verify instantly in Step 2.

---

Step 2 — Verify it's working right now (Realtime)

1. Open the live site, Accept the cookie banner, open Ask MSOS, ask a test question.
2. In GA4 → Reports → Realtime.
3. Scroll to "Event count by Event name" → you should see assistant_query. Click it to see the parameters coming in.

(If you don't see it: make sure you clicked Accept on cookies — the event is intentionally not sent otherwise.)

---

Step 3 — Build the "Top questions" report (Exploration)

1. GA4 → Explore (left menu) → Blank exploration.
2. Variables column → next to Dimensions click + → add Question, Result, Question language. → next to Metrics click + → add Event count.
3. In the Settings ("Tab Settings") column:
   • Rows → drag in Question.
   • Values → drag in Event count.
   • Filters → drag in the field, choose... actually add a filter: Event name exactly matches assistant_query. (If "Event name" isn't offered, add the dimension Event name first.)
4. You now have a ranked list of the most-asked questions. Sort by Event count (click the column).

---

Step 4 — The gold mine: unanswered questions

Duplicate the tab (or add a filter) and set:

• Rows: Question
• Values: Event count
• Filter: Result exactly matches none

This is the list of questions the assistant failed to answer. Each one is a prompt to either (a) add a curated answer in assistant.js, or (b) write/clarify a page. This is how the assistant gets smarter over time.

Tip: also break down by Question language to see if MK/SI users are being served as well as EN users.

---

Optional — a quick recurring check

Save the exploration (it autosaves). Once a week, open it and look at:

• Top 10 questions → your real FAQ list (consider promoting these on pages).
• result = none → your to-do list for new answers/content.
• result = search (not curated) → common questions worth turning into a polished curated answer (edit the INTENTS list in assistant.js).

---

Privacy note

The question text is user-typed, so avoid encouraging personal data in the prompt (the placeholder just says "Ask a question…"). Google's terms forbid sending personal identifiers (emails, names) to GA. Questions are truncated to 120 characters and only sent after cookie consent. If you ever want zero text stored, you can drop the q parameter in assistant.js and keep only the result/language counts.