fansunited-frontend-components 0.0.74 → 0.0.76

package/README.md

@@ -237,6 +237,179 @@ import { ClassicQuizPlay } from "fansunited-frontend-components";
 />
 ```
 
+## Analytics
+
+`Predictor` emits a typed event for every meaningful step of the user journey — viewed, started a
+prediction, submitted, joined a private league, clicked an odd. Use them for funnels, conversion
+goals and remarketing audiences.
+
+> Currently `Predictor` only. The bus is component-agnostic, so other components can join without a
+> breaking change. This is separate from the `onFinish` / `onShare` callbacks above.
+
+### Two ways to consume
+
+Both receive the identical stream, and can be used together.
+
+**1. The `callbacks` prop** — for when you own the JSX:
+
+```tsx
+<Predictor
+  entityId="predictor-template-123"
+  sdk={sdk}
+  language="en"
+  callbacks={{
+    onEvent: (event) => analytics.track(event.name, { ...event.params, ...event.context }),
+  }}
+/>
+```
+
+**2. The `componentEvents` bus** — for when you don't: a tag manager, a separately-bundled script,
+anything that loads after the component mounts.
+
+```ts
+import { componentEvents } from "fansunited-frontend-components";
+
+const unsubscribe = componentEvents.subscribe((event) => {
+  console.log(event.component, event.name, event.params);
+});
+```
+
+`subscribe` returns an unsubscribe function, and **replays recent events** to a new subscriber (the
+last 50, within the last 5 minutes) — so a listener that attaches after mount still sees
+`widget_view` and anything else it missed. Without that, funnel denominators under-count.
+
+The bus is subscribe-only by design. There is no public way to emit, so nothing else on the page can
+forge events into your analytics.
+
+### Event shape
+
+```ts
+type ComponentEventParams = Record<string, string | number | boolean | null>;
+
+interface PredictorComponentEvent {
+  component: "predictor";
+  name: PredictorAnalyticsEventName;
+  params: ComponentEventParams;
+  context: PredictorAnalyticsContext;
+}
+
+/** Discriminated on `component`. One member today. */
+type ComponentEvent = PredictorComponentEvent;
+
+interface PredictorAnalyticsContext {
+  entityId: string;
+  template: "standard" | "embed";
+  language: LanguageType;
+  userIsLoggedIn: boolean;
+  templateTitle: string | null;
+}
+```
+
+`context` is identical on every event from an instance; `params` are per-event. Narrow on
+`component` before reading them — when a second component starts emitting, the union widens and code
+that already narrows keeps compiling:
+
+```ts
+componentEvents.subscribe((event) => {
+  if (event.component !== "predictor") return;
+  event.context.entityId; // typed here
+});
+```
+
+Three properties you can rely on:
+
+- **Flat primitives only.** No nested objects or arrays; multi-value fields are comma-joined
+  strings, because tag managers and GA4 handle array parameters poorly.
+- **Every key an event defines is always present**, `null` rather than absent.
+- **No personal data.** No profile id, email, display name, token, or private-league invitation
+  code. The only user-level fact is `context.userIsLoggedIn`.
+
+### Events
+
+Every event also carries `context`.
+
+| Group | Event | Params |
+| --- | --- | --- |
+| Lifecycle | `widget_view` | — |
+| | `tab_view` | `tab` |
+| | `matchweek_change` | `direction`, `group_id` |
+| Prediction | `prediction_started` | match descriptors + `market` |
+| | `prediction_submitted` | match descriptors + `markets`, `market_count`, `is_edit` |
+| | `prediction_failed` | match descriptors + `markets`, `market_count`, `is_edit` |
+| | `prediction_edited` | match descriptors + `market` |
+| | `prediction_removed` | match descriptors + `market` |
+| Gates | `sign_in_prompt_shown` | match descriptors + `trigger` |
+| | `sign_in_click` | `location` |
+| | `consent_gate_shown` / `consent_accepted` / `consent_declined` | `consent_ids` |
+| Engagement | `odds_click` | `match_id`, `outcome`, `odd_value`, `operator` |
+| | `leaderboard_page_change` | `page`, `total_pages` |
+| | `embed_success_cta_click` | `match_id`, `cta_label`, `url` |
+| Private leagues | `private_league_created` / `_joined` / `_view` / `_invite_shared` / `_invitation_accepted` / `_invitation_declined` / `_left` / `_deleted` | `league_id`, `league_name` |
+
+**Match descriptors** are `match_id`, `home_team`, `home_team_id`, `away_team`, `away_team_id`,
+`kickoff_at`.
+
+**Join on the ids, not the names.** `match_id` and the team ids are canonical, provider-agnostic
+identifiers (`fb:m:*`, `fb:t:*`) — stable across languages and across whichever football data
+provider is behind the account. `match_id` is the same value the prediction itself is posted with,
+so an event joins 1:1 with its prediction record. The `home_team` / `away_team` names are
+**localised by the `language` prop** and exist for readable reports only.
+
+Notes on firing:
+
+- `widget_view` fires once per `entityId`, held until the template request settles — before that the
+  component is a skeleton.
+- `prediction_started` fires once per match, on the user's first answer, however much they then
+  change it.
+- A partially-failed multi-market submit emits **both** `prediction_submitted` and
+  `prediction_failed`, each listing only its own markets.
+- `sign_in_click` does not fire for a `signInCTA.component` you supply — that component owns its own
+  clicks. Where it does fire, your `signInCTA.onClick` still runs.
+
+### Wiring to a tag manager
+
+Every component renders inside a **shadow root**, so a tag manager's built-in no-code triggers (all
+clicks, form submission, element visibility) cannot see into it: a click arrives at `document`
+retargeted to the shadow host, giving one anonymous `<div>` with no text, classes or id, and native
+`submit` events don't escape a shadow root at all. That's inherent to the CSS isolation, not a
+configuration mistake — pushing named events is the answer, and it's more stable anyway.
+
+```ts
+import { componentEvents } from "fansunited-frontend-components";
+
+window.dataLayer = window.dataLayer || [];
+
+componentEvents.subscribe((event) => {
+  window.dataLayer.push({
+    event: `fu_${event.name}`,
+    ...event.params,
+    ...event.context,
+  });
+});
+```
+
+Then create a Custom Event trigger on `fu_prediction_submitted`, a GA4 Event tag, and Data Layer
+Variables for the parameters you want. A single trigger matching `^fu_` with `{{Event}}` as the tag's
+event name forwards the whole catalogue at once.
+
+Two things to get right:
+
+- **Prefix the event names.** `dataLayer` is shared with everything else on the page. The library
+  deliberately does not prefix for you — that would bake its naming into your container.
+- **GTM merges pushes rather than replacing them.** If one push sets `match_id` and a later event
+  omits that key, GTM still reports the old value. Either clear the keys an event doesn't define, or
+  nest everything under one key and read it with dot notation:
+
+  ```ts
+  window.dataLayer.push({ event: `fu_${event.name}`, fu: { ...event.params, ...event.context } });
+  ```
+
+Verify with:
+
+```js
+window.dataLayer.filter((e) => String(e.event).startsWith("fu_"));
+```
+
 ## Components
 
 ### ClassicQuizPlay
@@ -3460,6 +3633,7 @@ Football score predictor component with two templates: the default **multi-tab**
 | `consents`                    | `ConsentDef[]`           | Consent definitions required before predicting                                                    |
 | `matchCardBgImageUrl`         | `string`                 | Background image URL for match prediction cards. Ignored by `"embed"`                             |
 | `betslip`                     | `PredictorBetslipConfig` | Betslip integration config. Omit to disable. See [Betslip Integration](#betslip-integration)      |
+| `callbacks`                   | `PredictorCallbacks`     | `onEvent` — one observer for every journey event the component emits. See [Analytics](#analytics)  |
 
 #### Predictor Templates
 
@@ -3763,6 +3937,37 @@ type PredictorBetslipTrigger =
 
 **Theme fallback:** If `betslip.themeOptions` is not provided, the Betslip widget inherits the Predictor's own `themeOptions`. A single `themeOptions` on the Predictor is enough to theme both components consistently.
 
+#### Analytics
+
+The Predictor emits a typed event for every meaningful step — `widget_view`, `tab_view`,
+`prediction_started`, `prediction_submitted`, `private_league_joined`, `odds_click` and more.
+
+```tsx
+<Predictor
+  entityId="predictor-template-123"
+  sdk={sdk}
+  language="en"
+  callbacks={{
+    onEvent: (event) => analytics.track(event.name, { ...event.params, ...event.context }),
+  }}
+/>
+```
+
+The same stream is available without a prop, via the `componentEvents` bus — which is what you want
+for a tag manager, since it can subscribe after the component has already mounted:
+
+```ts
+import { componentEvents } from "fansunited-frontend-components";
+
+componentEvents.subscribe((event) => {
+  window.dataLayer.push({ event: `fu_${event.name}`, ...event.params, ...event.context });
+});
+```
+
+Payloads carry no personal data. Full event catalogue, parameter tables, the join-key rules, and the
+tag-manager setup (including why built-in click triggers cannot see into the component's shadow root)
+are in [Analytics](#analytics).
+
 #### TypeScript Support
 
 Import types from `fansunited-frontend-core`:
@@ -3783,9 +3988,23 @@ import {
   OnSuccessCTADetails,
   CustomThemeOptions,
   LanguageType,
+  // Analytics
+  PredictorCallbacks,
+  ComponentEvent,
+  ComponentEventParams,
+  PredictorComponentEvent,
+  PredictorAnalyticsContext,
+  PredictorAnalyticsEventName,
 } from "fansunited-frontend-core";
 ```
 
+The `componentEvents` bus itself is imported from `fansunited-frontend-components`, not from core:
+
+```tsx
+import { componentEvents } from "fansunited-frontend-components";
+import type { ComponentEventsApi } from "fansunited-frontend-components";
+```
+
 #### Examples
 
 ##### Basic Predictor
@@ -5173,7 +5392,7 @@ This package exports the following components:
 - **`EitherOrPlay`** - Binary choice game with standings panel and customizable templates
 - **`Discussion`** - Threaded comments with reactions, replies, reporting, and authentication support
 - **`Leaderboard`** - Ranked standings for Classic Quiz, Match Quiz, Top X, and Template entities with multi-entity support
-- **`Predictor`** - Multi-tab football score predictor with leaderboard, private leagues, rules, and prizes
+- **`Predictor`** - Multi-tab football score predictor with leaderboard, private leagues, rules, prizes, and a journey-event analytics bus
 - **`TopX`** - Multi-tab competitive picks predictor with game navigation, leaderboard, private leagues, rules, and prizes
 - **`Betslip`** - Floating betslip with bookmaker deep-link integration, six viewport positions, and command bus API
 - **`Standings`** - Sport-agnostic competition standings table with zone highlighting, rank movement, and team form