Skip to content

feat(portal): load Google Tag Manager and GA4 from portal.analytics - #473

Merged
sohail2721 merged 73 commits into
devfrom
sohail/portal-analytics
Nov 16, 2026
Merged

sohail2721 merged 73 commits into
devfrom
sohail/portal-analytics

Conversation

@sohail2721

@sohail2721 sohail2721 commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

PR 1 of apimatic/apimatic-io#2348, with PR 3 (the other seven events) following in this same PR since 2026-11-12, so GA4 and GTM can be tested with every event before anything merges. PR 1: portal.analytics loads Google Tag Manager and GA4 from apimatic.json, and the template reports each page view once as docs_page_view. The detail and the code sketches are in apimatic/apimatic-io#2349. The build plan and the docs draft are kept out of the repository, so the squash brings neither into dev.

Draft until the gate: pnpm test green, the manual list in apimatic/apimatic-io#2349 ("Manual, on a test portal") checked, and each of PR 3's events seen once in GTM Preview with all of its keys. The squash title then covers both: feat(portal): load Google Tag Manager and GA4 from portal.analytics and report the portal events.

What is on the branch

Read it from the entry point down.

  • The root route (portal-template/src/routes/__root.tsx) reports the first page's view on mount and one per onRendered; head() lists no script, and writes the google-site-verification meta when the identity file holds a value.
  • The API page (portal-template/src/components/api-page.tsx) renders the playground's header inside one element carrying the opt-out markers of the session replay tools a GTM tag may load (PostHog, FullStory, rrweb, Amplitude, Hotjar, Clarity, LogRocket) and the data-portal-playground test hook, with Fumadocs' endpoint bar while the playground's chunk loads. The cURL sample carries the same markers, since it follows what the reader types. The client is lazy-loaded from Fumadocs' public export, as Fumadocs itself loads it.
  • The bundle's start (portal-template/src/lib/portal-analytics.ts) runs at module evaluation, before React and before any vendor tag, never during prerendering: first markPlaygroundDialogs() (lib/replay-markers.ts), one observer that marks the playground's dialog as Fumadocs adds it, ahead of any replay tool's observer (until openapi: let PlaygroundClient put attributes on the playground dialog fuma-nama/fumadocs#3824 takes the markers itself), then new Analytics(portal.analytics).start().
  • The module (portal-template/src/lib/analytics.ts) holds the event table and the Analytics class: start() creates window.dataLayer, pushes every vendor's setup entries and inserts the tags, once per page load, and under portal serve reloads the page when a config save changes the vendors; report() adds the cleaned page_location (pageLocation()), pushes { docs: null } then { event, docs }, and calls each adapter that sends for itself; reportPageView() and reportNotFound() keep the page history the two events need, and the not-found page reports only once the router has settled on it (components/not-found.tsx), so leaving it reports nothing for the page the reader goes to. Nothing is reported on /oauth/callback, and the tags wait while the address holds an OAuth answer (holdsOAuthAnswer() in lib/oauth-callback.ts): on the callback, and on the page a sign-in returns to until the playground has taken the answer out, which loads them (analytics.loadTags() from components/playground.tsx).
  • The vendors (portal-template/src/lib/vendor-tags.ts): the adapters registry is keyed by both vendors, so a vendor without an adapter does not compile. GTM pushes gtm.start and loads gtm.js (with the environment suffix when set), and reads the data layer itself. GA4 defines window.gtag only when missing, pushes js and config with send_page_view: false, loads gtag/js, sends each event under GA4's own name, and sets page_location on each page view, so GA4's own scroll and click events carry the cleaned address too. insertTags() appends each tag once, none while the address holds an OAuth answer.
  • The reporters: code copies report from each block's own copy button (components/code-copy.tsx, through Fumadocs' Actions slot) with the block's language ID, the IDs SDK downloads send too (csharp, shellscript), both through languageId(), which reads a name in lowercase and knows the common short names of languages outside the bundle (kt is kotlin), so one language is one value; MDX blocks get theirs at build time (lib/transformer-language.ts), the API reference's at render, and "Example Response", whose button Fumadocs keeps to itself, through a click handler on its card. The playground times its requests in a ref of its own and reports each result once (components/playground.tsx, lib/api-request.ts). The search dialog's report is searchOutcome() (lib/search-report.ts): the result picked goes out as a whole address in the form of page_location, and the term at most 100 characters long, which is what GA4 keeps.
  • The shared type (portal-template/src/lib/portal-types.ts, PortalIdentity in src/types/portal/portal-config.ts) carries analytics and seo, filled by AnalyticsConfig and SeoConfig from the portal block, with #2348's messages less its format rules: an ID, an environment value, the verification token and a kept name are any non-empty string, and no name is refused (decided 2026-11-12, to record in #2347); portal generate and portal serve warn when GA4 is set.
  • The flag (--no-analytics on portal generate and portal serve, defined once in FlagsProvider) reaches the actions as PortalBuildOptions, and PortalSourceContext applies it where the settings are read, for a build and for each config save under portal serve: both vendors are dropped, the kept query names stay. The options have no default, so every caller chooses. portal serve loads exactly what a hosted portal loads: no debug mode, no preview distinction, so the sketched PortalDelivery is not built (decided 2026-11-12, to record in #2347).
  • The schema (apimatic.schema.json) describes both blocks with no pattern, as the parser reads them; the schema test holds the two to one verdict per case.
  • The end-to-end proof (test/e2e/portal-build.test.ts, behind APIMATIC_E2E=1) builds the default fixture with both vendors and a verification value set: the IDs sit in a browser script, no prerendered page names the tag host, every page carries the meta, and the operation page holds the playground's prerendered header and the cURL sample each inside an element replays skip, and the copy button of "Example Response" as the button[aria-live] its copies are reported by, so a Fumadocs update that changes either fails here. test/commands/portal/*-flags.test.ts run both commands to see the flag reach the settings reader.

Steps, as the plan numbers them: 1.1 the pure functions, 1.2 adapters and page views, 1.3 the loader's wait (built, then removed, see below), 1.4 the bundle wiring, 1.5 the verification meta and the playground out of replays, 1.6 the parser and the GA4 warning, 1.7 --no-analytics, 1.8 the schema, 1.9 the end-to-end proof, 1.10 README and docs. PR 1 is complete. In this PR, PR 3: 3.1 the three click reporters, 3.2 docs_code_copy, 3.3 docs_search, 3.4 docs_not_found, 3.5 docs_api_request, 3.6 the docs (done). PR 1 and PR 3 are complete; the gate below is what remains. PR 2 (portal.scripts) follows in its own PR.

Before merging

  • No vendor tag reads an OAuth answer from the address (1bb6dfbb): with 12.6.0 the playground reads a returned sign-in's answer from the address, so the tags wait until Fumadocs has taken it out, and an answer nothing takes out waits for the next page. Seen in headless Chrome against portal serve with both vendors: no tag at #access_token=…&state=…, both once the address was clean, and no GA4 hit carrying the token.
  • Later, not a merge gate: take fumadocs-openapi 12.6.2 and have the callback hand the answer over as Fumadocs' createOAuthHandler() does, so the answer never reaches the address at all. After a playground sign-in the provider lands on /oauth/callback, and our own callback copies its query and # part (?code=…&state=… or #access_token=…) onto the starting page, where the vendor tags read the address for themselves; the portal's own events are clean, since pageLocation() strips both. 12.6.2's getReturnedFlow() reads the answer from sessionStorage under fumadocs-openapi-oauth-returned and falls back to the address; 12.6.0 reads the address only, so the callback cannot store it there before the bump. With the bump: oauthCallback() returns the bare starting page and the route stores location.href under that key, with test/portal-template/oauth-callback.test.ts and the comment at oauth-callback.ts:20 following. dev pins 12.6.0 since feat(portal): fumadocs-openapi 12.6 with PKCE for playground sign-ins #472 merged on 2026-11-12, under the seven-day release-age rule in pnpm-workspace.yaml; 12.6.2 clears it on 2026-11-19, and this branch takes it then. The 5-second wait that held the tags back (step 1.3, commit 1c616d56) was removed on 2026-11-12.
  • Release together with PR 2 (portal.scripts). PR 2 makes --no-analytics also leave out the analytics and marketing scripts, and updates the flag's help. Released alone, this PR would have the flag drop more in a later release than it does in this one.
  • Follow-up, not a merge gate: a browser smoke test in apimatic/v4-test-automation, from the Playwright scripts of the review of 2026-11-16: each of the eight events once with its keys, and leaving the not-found page. The components that report are not unit-tested, and they lean on Fumadocs' markup, storage keys and render order; what guards them here is the pinned event table, searchOutcome(), apiRequest() and the built-page checks.
  • The manual list in apimatic/apimatic-io#2349 ("Manual, on a test portal with GTM Preview and GA4 DebugView"), with no debug mode: DebugView needs Tag Assistant or the Google Analytics Debugger extension on the test browser.
  • Each of the eight events once in GTM Preview, with all of its keys, as the docs draft's table lists them: a page view, a Markdown copy, an install copy (one docs_plugin_install, no docs_code_copy), an SDK download, a code copy from a page's block, the API reference's cURL sample and "Example Response", each with its language ID, a search with a pick and one without, a reopen without typing (nothing), a broken portal link (docs_not_found with the page left, plus its page view), and a playground request with a response and one that fails (client_error), with docs_api_request never carrying the request address.
  • The "Done when" lines in apimatic/apimatic-io#2348 for loading, counting, nothing private, verification and events.

Base

Was stacked on #472 (fumadocs-openapi 12.6) while it was open, as the plan's section 3 says, so the diff showed only this work. #472 merged on 2026-11-12 as f7fe7dff, and this branch was rebased onto dev and retargeted the same day.

An end-to-end run on 2026-11-13 (headless Chrome against portal serve and a built portal, with a real GA4 property) saw seven of the eight events arrive once each with their keys, and the playground dialog marked in the browser; the plugin event needs a project with a plugin block. It also found the first page view in portal serve carrying the site name as its title, fixed in __root.tsx by reporting directly only when the router is idle at mount.

Decisions on record: the e2e list's "a --no-analytics build holds no ID" check is not in test/e2e/portal-build.test.ts; test/infrastructure/portal-project-service.test.ts checks the identity file written from a config without vendors instead, which saves a full build in CI (plan step 1.9). The code review of 2026-11-13 and the reviewer's findings of the same day are addressed from be8cc928 on; the review of 2026-11-13 requesting changes from 09a22ba3 to 96885d4d, with the OAuth return page in 1bb6dfbb, but for a playground result that arrives after the reader closed the dialog, which Fumadocs gives no callback for in 12.6.0 or 12.6.2.

The review of 2026-11-16 is addressed from f54b30ef to 02200bbc, and settled four things customers will build on. The event names and keys are pinned by a test, as plain text apart from the interface, so a rename is a change made there on purpose. status stays one text value, the HTTP status as digits or client_error. A search's result is a whole address in the form of page_location. ref left the built-in kept names: no platform reads it from the address, sites use it for codes of their own, and a customer can add a name through keepQueryParams but cannot take one out. The same review found the not-found page reporting docs_not_found for the page a reader left it for; fixed, and seen in headless Chrome on a served and a built portal.

🤖 Generated with Claude Code

sohail2721 pushed a commit that referenced this pull request Nov 11, 2026
The list is only ever asked whether it holds a name (SonarCloud on #473).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
sohail2721 pushed a commit that referenced this pull request Nov 12, 2026
The list is only ever asked whether it holds a name (SonarCloud on #473).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@sohail2721
sohail2721 force-pushed the sohail/portal-analytics branch from cd8de5e to 0231cfc Compare November 12, 2026 11:01
Muhammad Sohail and others added 24 commits November 12, 2026 16:24
Step 1.1 of .ai/plans/portal-analytics.md: pageLocation(), holdsOAuthAnswer()
and the PortalEvents map with docs_page_view, tested without a DOM.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The list is only ever asked whether it holds a name (SonarCloud on #473).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Step 1.2 of .ai/plans/portal-analytics.md: the GTM and GA4 adapters, analyticsFor()
with startAnalytics(), report() and reportPageViews(), and the shared adapter suite.
The vendor settings join portal-types.ts.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…answer

Step 1.3 of .ai/plans/portal-analytics.md: insertWhenClean() checks every 100 ms for
up to 5 seconds, inserts once the answer is gone, and leaves a page never cleaned to
the next page change. Every analyticsFor() test now runs on a fake clock.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…ribe

Nothing reads it before PR 2 adds window.apimatic.analytics.subscribe(), and the
plan now builds top-down: nothing is written before the code that calls it.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Step 1.4 of .ai/plans/portal-analytics.md, the browser entry point: the root route
subscribes the loader to onRendered and reports page views; portal-analytics.ts builds
the one instance from portal.analytics and starts it at module evaluation; the shared
type and PortalIdentity carry analytics, written as the default until the parser lands.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
analyticsFor() and its inner functions become the Analytics class: start(),
insertWhenClean(), report() and reportPageView(). The router subscription moves
into the root effect, which already holds the router, and the one-use helpers
are inlined.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Removes the wait while the address holds an OAuth answer (step 1.3, 1c616d5):
holdsOAuthAnswer(), the nine-name list, the timing constants and insertWhenClean().
start() appends the vendor tags directly and the root reports page views only.
fuma-nama/fumadocs#3809 is the PR's merge prerequisite instead; until it ships, a
Google tag can read the answer after a playground sign-in.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…out of replays

The root route's head() writes Google's site verification meta when the
identity file holds a value. The identity file gains `seo`, written as null
until the config parser reads it.

The API page wraps the playground in one element carrying the opt-out
markers of the session replay tools a GTM tag may load (PostHog, FullStory,
rrweb, Amplitude, Hotjar, Clarity, LogRocket), so a replay records the rest
of the page and leaves the playground's inputs blank. The playground client
is lazy-loaded from Fumadocs' public export, as Fumadocs itself loads it.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
`AnalyticsConfig` parses `googleTagManager` (with its optional `environment`),
`googleAnalytics` and `keepQueryParams`, with every rule and message from the
table in apimatic/apimatic-io#2348; an OAuth answer's names are refused in the
kept list. `SeoConfig` parses `googleSiteVerification`. Both reach the identity
file through `identity()` and are serialised only when set, so quickstart's
block gains nothing.

`portal generate` warns, before the build, when Google Analytics is set: the
portal sends its own page views, so the stream's history-change page views
must be turned off or every page change counts twice.

GA4's `debugMode` is written as false until the delivery reaches `identity()`
in the next step.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
A container ID, a measurement ID, an environment's auth and preview values,
the verification token and a kept query parameter name are any non-empty
string: a wrong value fails at the vendor, not in the CLI, so the parser
checks presence and type only and holds no pattern. The kept-name list no
longer refuses an OAuth answer's names either.

Decided 2026-11-12; it replaces the locked rule and the format rows of the
table in apimatic/apimatic-io#2348, and is to be recorded in #2347.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…ntity file

`portal generate` and `portal serve` take `--no-analytics`, for a staging
build that must not count. The flag reaches `identity()` as one boolean,
passed through the prepare action and the project service and never
stored: with it off, both vendors are written as null and the browser
loads no tag, while the kept query names still go through. `portal serve`
hands the same value to the rewrite when the block changes.

`portal serve` is a hosted portal in every way: GA4's debug mode and the
preview/build distinction are gone, so the sketched delivery class is not
built. Decided 2026-11-12, to be recorded in apimatic/apimatic-io#2347.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Editors now offer both blocks. Every ID, environment value, kept name and
the verification token is any non-blank string, as the parser reads them,
so the schema carries no pattern and refuses nothing the parser accepts;
the schema test holds the two to the same verdict on each case, including
the formats the parser stopped checking.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The default end-to-end build reads a copy of its fixture with both vendors
and a verification value set, and checks the output: a browser script
holds both IDs while no prerendered page names the tag host, every
prerendered page carries the verification meta, and the operation page
holds the playground's prerendered header inside the element session
replays skip. The fixture the other suites read stays as it is.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The README's generated sections carry --no-analytics on both portal
commands. The docs page draft for docs.apimatic.io/v4 travels in
.ai/plans/portal-analytics-docs.md: the settings, the page view event,
the GA4 and GTM setup, previews and staging, Search Console, consent, the
CSP domains, container access, session replay and other tag managers,
with the CLI reference row. It is the reviewer's to take to the docs
repository.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Three more events through the same report(): docs_markdown_copy when the
copy succeeds, docs_plugin_install as the install command's copy button is
clicked, through an Actions wrapper around Fumadocs' button, and
docs_sdk_download with the SDK's language from every download link, the
SDK page's own included.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Fumadocs' copy button has no callback, so the document hears every click:
one inside a code block's figure reports docs_code_copy with the block's
caption, or the selected tab's name in a tabbed set. An untitled block
reports nothing, and the install command's block, which reports its own
copy, is marked and skipped.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
One docs_search when the dialog closes after the reader typed in this
open: the term trimmed, the result picked or '' for none, and how many
results the list showed. Fumadocs closes the dialog before it hands over
the pick, so the report waits a tick for it; a reopen closed without
typing reports nothing.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
docs_not_found from the not-found page's mount: page_referrer is the
portal page the reader left for it after an in-portal link, else the
document's referrer without its query and # part on a first load, else
empty. The page's own docs_page_view still arrives.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
docs_api_request once per result: the endpoint as the spec writes it,
the HTTP status or client_error, and the duration, the response's own or
timed from the request's start for one that never arrived. Never the
request's address, headers or body. The reporting wraps Fumadocs' result
display inside the playground's lazy chunk, so the split from the page
bundle holds.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The docs draft's table lists every event with its keys and when it
fires, the GA4 custom dimensions and metrics to register, and the GTM
trigger and variable pattern for the events beyond the page view.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The playground's dialog, which Fumadocs portals outside the marked
wrapper, is marked for session replay as it appears, until
fuma-nama/fumadocs#3824 lets the markers be passed to it directly; the
markers themselves move to one module the wrapper shares.

docs_search carries the page it was made on, captured when the dialog
opens, since a pick changes the address before the close is reported,
and a pick without typing counts as a search. docs_api_request reports
a result object once however often the display mounts, which happens
on every reopen and twice under StrictMode, and a request that failed
before it was sent has no duration. docs_not_found reports once per
missing page and again for the next, keyed on the path. The code-copy
listener ignores dropdowns and the playground's dialog, and prefers a
block's caption over its tab.

Vendor values are escaped in the tag addresses, since the parser checks
presence only. The two empty events take no keys at report().

The docs draft's consent, CSP, replay, search and GA4 lines are
corrected: direct GA4 cannot wait for a banner, search_term is GA4's own
parameter, and the redact setting sits under the tag settings.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The warning that a GA4 stream counts page changes twice fires only when
the build loads GA4, so a staging build built with --no-analytics is
not told to change a stream it does not report to.

AnalyticsConfig holds GA4 as a GoogleAnalyticsSetting, named as the
template names it, instead of a bare measurement ID rebuilt in two
places. Quickstart names the two booleans it passes to serve, the prompt
builds its message before logging it and links with a scheme, and the
toJSON() comment says what the code does.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The step-by-step plan the analytics PR was built from, with each step's
commit, the branch table, the questions each step raised and their
answers, and the review of 2026-11-12.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@sohail2721
sohail2721 force-pushed the sohail/portal-analytics branch from 0231cfc to b8a13e6 Compare November 12, 2026 11:25
@sohail2721
sohail2721 changed the base branch from chore/fumadocs-openapi-12-6 to dev November 12, 2026 11:25
In `portal serve` the root effect runs while the router is still
pending, before the page's own head has applied, so the first
docs_page_view carried the site name as its title; the address dedupe
then dropped the onRendered report that had the right one. A
prerendered page mounts with the router idle and the right title, and
raises no onRendered for its first page, so the direct report stays for
that case: the effect now reports directly only when the router is idle
at mount, and leaves the first page to onRendered otherwise.

Seen with headless Chrome against both a served and a built portal, each
sending one first page view with the page's title after the change. The
plan records the end-to-end run.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Muhammad Sohail and others added 8 commits November 13, 2026 17:34
…rtup

Mutation observers are told in the order they were made. One made as the bundle starts, before any vendor tag,
marks the dialog before a replay tool's observer records it, which one made per mount did not.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The test hook no longer marks the cURL sample and the dialog, which carry the replay markers alone; the e2e
test checks the one element again, with its markers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…age ID

Copies report through each block's Actions slot instead of a document listener: the MDX blocks, which the
build names the language of, the API reference's blocks, its Markdown and the playground's, Example Response,
and every command block, an SDK card's install command included. language is the ID SDK downloads also send,
csharp or shellscript; the IDs and aliases move from shiki-bundle.ts to languages.ts, so a page can read them
without loading the highlighter.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…quences

searchOutcome() takes the dialog's open, loading, typed and picked state; the dialog keeps the refs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A first client-side visit to an operation page showed nothing in the playground's place until its chunk
loaded; Fumadocs shows its endpoint bar there, which it does not export, so the template draws the same.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Comments that restated the code go; the rest say why in one line.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The build plan, its review log and the docs draft for apimatic-docs stay on the author's machine, so the squash brings none of them into dev.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
fumadocs-openapi 12.6.0 reads a returned sign-in's answer from the address, so the callback sends the reader back with it attached, and gtm.js and gtag.js read the address for themselves. The tags now wait while the address carries the callback's path or a state, which Fumadocs sends with every authorization, and the playground loads them once Fumadocs has taken the answer out, in its effects; an answer nothing takes out waits for the next page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@mehnoorsiddiqui mehnoorsiddiqui left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tested this branch end to end: the unit and e2e suites, plus headless Chrome against built portals and portal serve. Everything works apart from the not-found bug I commented on earlier. Most of the notes below are about things that will be hard to change once this ships.

A few general ones:

  • Most of Waseem's and Saeed's threads look fixed in the code now, but 18 of them are still open with no replies. Could you reply to or resolve them, and re-request review from Saeed?
  • The analytics logic is unit-tested, but the components that report events aren't, which is how the not-found bug got through. A lot of it also depends on Fumadocs internals (markup, storage keys, render order), so a Fumadocs update could stop events or the tag hold without any test failing. A browser smoke test that fires each of the 8 events once and checks their keys would catch both. I can share the Playwright scripts I used as a starting point.
  • The manual GTM Preview / GA4 DebugView checks in the description are still unticked. My headless run doesn't replace those.

Comment thread test/e2e/portal-build.test.ts Resolved
Comment thread portal-template/src/lib/analytics.ts Resolved
Comment thread portal-template/src/lib/languages.ts Resolved
Comment thread portal-template/src/lib/analytics.ts Resolved
Comment thread src/types/flags-provider.ts Resolved
Muhammad Sohail and others added 8 commits November 16, 2026 13:05
…n it

The not-found page keyed its report on the router's location, which
already names the page a reader is leaving for while the not-found page
is still mounted. Leaving it by Back, the Home link or any other link
sent a second docs_not_found, for the page the reader went to, with the
missing page as its referrer. The report is now keyed on the path the
router has resolved, and nothing is reported in between.

Seen in headless Chrome on portal serve and on a built portal, with
in-app navigations only: leaving the missing page reports nothing more,
and a second visit and a second missing page each report once.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
languageId() looked a name up as written, so a fence written TS or
TypeScript missed the alias table, and a language the bundle does not
know went out in the author's capitals: several values for one language
in the one GA4 dimension. It now reads the name in lowercase first.
docs_sdk_download goes through the same function, so the two events
share one table instead of two sets that happen to match.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
… term

result was the picked page's path under the base path, while every
page_location is a whole address, so the two did not join in a report.
searchOutcome() now passes the pick through pageLocation(), which also
drops the # part of a heading hit. The term is cut at 100 characters,
which is what GA4 keeps of a value, so no other tag gets more of a key
or a token pasted into search.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Every other built-in name is one an ad or mail platform reads from the
address itself. Nothing reads ref, sites use it for referral and invite
codes of their own, and a customer can add a name through
keepQueryParams but cannot take one out, so once shipped it could not
have been removed.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Customers build GTM triggers and GA4 reports on them. The typed table
follows the interface through a rename, so a rename passed CI. The
names and keys are now also listed as plain text, and a change has to be
made in that list on purpose.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
resolve() and resolveSettings() defaulted to loading the vendor tags, so
a new caller that forgot the argument got them without noticing.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…response copy button

The check that the cURL sample sits inside an element session replays
skip went out with 95c8187, though the sample follows what the reader
types. It is back. A second check expects Fumadocs' copy button on
"Example Response" to be the button[aria-live] the report listens for,
so a Fumadocs update that changes either fails the build test instead of
silently dropping the markers or the event.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
… only

Its two values are public in the built portal, and with them anyone can
load that environment's version of the container.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

@sohail2721 sohail2721 left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the end-to-end run. Each note is answered in its thread; the three general ones:

  • Open threads. Waseem's and Saeed's are all answered, and resolved but one: a playground result that lands after the dialog closed, which needs a result callback from Fumadocs. Saeed's review is re-requested.
  • Browser smoke test. Agreed, and it belongs in apimatic/v4-test-automation, which already drives a browser against this CLI's build on every push to dev. Yes please to the Playwright scripts. It is a follow-up item in the description; in this repository the new guards are the pinned event table and the two built-page checks.
  • Manual checks. GTM Preview and GA4 DebugView are still to do before merge.

Comment thread test/e2e/portal-build.test.ts Resolved
Comment thread portal-template/src/lib/analytics.ts Resolved
Comment thread src/types/flags-provider.ts Resolved
Muhammad Sohail and others added 2 commits November 16, 2026 14:40
…short name a block uses

A language the bundle does not ship went out by the name the author
gave it, so kt and kotlin were two values in the one GA4 dimension. A
small report-only map beside the bundle's aliases names the common short
names by Shiki's ID, and a test holds each entry to the ID and alias
Shiki lists. A block in no language reported plaintext from a page and
text from a description; both are plaintext now.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…rror

docs_api_request sends status as the HTTP status in digits or as
client_error, in one field customers register as one GA4 dimension. The
choice is now written on the event's type and held by a test, so a
change to either form is made on purpose.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@sonarqubecloud

Copy link
Copy Markdown

@sohail2721
sohail2721 merged commit 6e4b215 into dev Nov 16, 2026
17 of 18 checks passed
@github-actions

Copy link
Copy Markdown
Contributor

🎉 This PR is included in version 2.3.0-beta.1 🎉

The release is available on:

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants