Repository navigation
feat(portal): load Google Tag Manager and GA4 from portal.analytics - #473
Merged
Merged
Conversation
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
force-pushed
the
sohail/portal-analytics
branch
from
November 12, 2026 11:01
cd8de5e to
0231cfc
Compare
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
force-pushed
the
sohail/portal-analytics
branch
from
November 12, 2026 11:25
0231cfc to
b8a13e6
Compare
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>
…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
left a comment
Contributor
There was a problem hiding this comment.
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.
…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
commented
Nov 16, 2026
sohail2721
left a comment
Contributor
Author
There was a problem hiding this comment.
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.
…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>
|
mehnoorsiddiqui
approved these changes
Nov 16, 2026
This was referenced Nov 16, 2026
Merged
Contributor
|
🎉 This PR is included in version 2.3.0-beta.1 🎉 The release is available on: Your semantic-release bot 📦🚀 |
sohail2721
added a commit
that referenced
this pull request
Nov 19, 2026
PR 2 of apimatic/apimatic-io#2348: `portal.scripts` and `window.apimatic.analytics.subscribe()`. PR 1 and PR 3 merged as #473. The plan this was built from, step by step, is apimatic/apimatic-io#2351; where the code departs from apimatic/apimatic-io#2347, #2348 and #2349 it says where and why. Since the review of 2026-11-17 it also carries `portal.analytics.googleConsentMode`, with which a consent tool can govern the built-in Google tags, and a `--no-analytics` that hands no event to the scripts it keeps. On 2026-11-18 it renamed three event keys that #473 had put out on the `beta` tag, and made a script's `category` required. The same day it answered a re-review of the fixes, whose ten new findings are under "Before merging". Ready for review. What is still to do before it merges is under "Before merging": the portal tests on this branch, the decisions to record in the issues, and releasing it together with #473. ## What a customer can now write ```json "portal": { "analytics": { "googleAnalytics": { "measurementId": "G-ABC123" }, "googleConsentMode": { "default": "denied" } }, "scripts": [ { "src": "static/js/consent.js", "category": "necessary" }, { "src": "https://cdn.example.com/chat.js", "category": "functional" }, { "src": "https://cdn.example.com/analytics.js" } ] } ``` - `src` is an `https` address or a file under `src/static/`. A file is checked on disk like a logo. - `category` is `necessary`, `functional`, `analytics` or `marketing`, the groups consent tools ask readers about. It is required: the CLI assumes none. The schema's description says what belongs in each. - The portal inserts each script after its own bundle and after the vendor tags, in list order, once per page, and never on the OAuth callback page. - `--no-analytics` on `portal generate` and `portal serve` leaves out the `analytics` and `marketing` scripts along with the two Google tags. The scripts it keeps are handed no event: `subscribe()` is there and stays silent. The consent default of `googleConsentMode` stays in such a build. - A script gets the portal's events from `window.apimatic.analytics.subscribe(callback)`: every event so far, then each new one, as a frozen `{ name, params, time, version: 1 }`. It returns the function that stops delivery. - `googleConsentMode` makes the portal queue Google's Consent Mode defaults ("denied", with a wait of 500 ms) before it sets either Google tag up. Both tags load as before and set no cookie until a consent tool calls `gtag('consent', 'update', …)`. Without the setting nothing changes. - Three event keys have new names. `docs_code_copy` carries `code_language` and `docs_sdk_download` carries `sdk_language`, where 2.3.0-beta.1 sends `language`. `docs_search` carries `picked_result`, where it sends `result`. ## What is on the branch One commit per step of the plan, then the fixes from two reviews, the merge with `dev`, the two follow-ups to the second review, five changes of 2026-11-18, seven commits that answer the re-review of that day, three that answer a review comment and SonarCloud after it, and four that answer the last of the review on 2026-11-19. | Commit | What it adds | |---|---| | `19cb032a` | `scripts` entries with an `https` address: parsed, written to `portal.identity.json`, inserted by the loader with `async = false`. The key a start runs once by covers the list, so a config save under `portal serve` reloads with the new one. An inserted tag is found by its `src` attribute, since a selector built from a customer's address misses on a backslash (replaced in `78505ad0`). | | `2580c4ea` | A file from `src/static/` as `src`: checked on disk with the brand's files, written as its portal path, inserted under the base path. | | `bf320b46` | `category`, and `--no-analytics` dropping the two categories. `PortalConfig.withoutVendors()` becomes `withoutAnalytics()`. The flag's help and the README say what it leaves out. | | `7849475b` | `EventFeed` and `window.apimatic.analytics`, put in place at the start, before any tag or script is inserted, on every portal. What scripts are given there changed in `5f220732`. | | `cea1bc0c` | `scripts` in `apimatic.schema.json`, with one `httpsAddress` definition that `pluginUrl` now shares. | | `6782e26c` | The build test lists an address and a static file and checks the built files. | | `a0c6d999` | The fixture script that test ships holds a comment only. Its first version set a property on `window`, which the whole-tree lint that runs after the tests refused, and CI failed on it. | | `5f220732` | Scripts get a frozen `{ subscribe }` at `window.apimatic.analytics`, bound and put in place whatever was there; the feed is held at `window.portalEventFeed` (moved in `ddbad82a`). From the review of 2026-11-16 below. | | `88fe45dc`, `8d117512` | Two refactors from the same review: the feed's delivery is a static helper, and `insertTags()` reads `<head>` once per call (not at all since `78505ad0`). | | `6ed31b30` | `publish()` loops over the subscribers without copying them first, which SonarCloud flagged on this PR as needless. Two tests pin what the copy was guarding: a subscriber added, and one removed, while an event is being handed over. | | `310f38ab` | The merge with `dev`, which took fumadocs-openapi 12.6.5 in #478. A sign-in's answer now reaches the playground through the tab's session storage, and `dev` holds the Google tags back on the OAuth callback only. Listed scripts follow that rule: none on the callback, all on the next page. They used to wait wherever the address held an answer. | | `d9058be4` | A subscriber's callback is called on its own. It was called on the feed's record of that subscriber, so a callback written without strict mode got the record as `this`, and one that reset the record's count was handed the same event without end. From the review of 2026-11-17 below, as are the seven commits after it. | | `ddbad82a` | The feed and the mark of what the page started with are held by the window under one symbol. `window.portalEventFeed` is gone, and so is `window.portalAnalyticsStarted`, which #473 set. A script that looks for the symbol can still reach the feed, as it can anything on the page. | | `78505ad0` | The page remembers each address it inserted, so a script that removes its own element once it has run is not inserted again on the next page view. `insertTags()` no longer reads `<head>`. | | `97946a28` | A page that made `window.apimatic` read-only no longer stops the bundle. The portal starts, and the error shows in the console a moment later. Since `f7518097` that error is left to a page that froze the object too. | | `bc7ec368` | `httpsAddress()` refuses an address with no host before its path (`https:///…`), as the schema's pattern does, and parses it once. `pluginUrl` goes through the same function. | | `e50ac0ac` | `Script.staticFiles()` answers a list, empty for an address, in place of `staticFile()` and its `null`. | | `5f1d49d9` | The flag's help and the README say that a script with no category is left out too. `367cf0be` takes that out again: no entry is without one. | | `07ee1f45` | `deliveredCount` and an `Unsubscribe` type replace two comments in the feed that restated the code, and a two-line comment in the schema test is one line. | | `3df7c3dd` | The schema's description of `scripts` says they stay off the OAuth callback page. It still described the hold that the merge with `dev` removed. | | `17ddf35f` | A build made with `--no-analytics` hands no event to the scripts it keeps. `portal.identity.json` gains `analytics.eventFeed`, which is `"off"` for such a build (`analytics.events` since `6792fa8d`). `subscribe()` stays in place and silent, and the data layer gets its entries as before (it gets none since `b9450b72`). `AnalyticsConfig.withoutVendors()` becomes `withoutAnalytics()`, and the flag's help says what it does. Finding 7 of the review of 2026-11-17. | | `1547e424` | `portal.analytics.googleConsentMode`: the portal queues Google's consent defaults ahead of both vendors' setups, and a `--no-analytics` build queues none (it queues them since `a895b2cd`). Finding 2 of the same review. | | `440f0b28` | The setting in `apimatic.schema.json`, with the schema test holding it to the parser's verdict. | | `94c58970` | The build test sets it and checks that a built script holds the defaults and no prerendered page does. | | `be9556c2` | `language` on `docs_code_copy` and `docs_sdk_download` becomes `code_language` and `sdk_language`. gtag takes `language` on an event for the reader's own language, so GA4's language field read `python` for a code copy. A test keeps the name out of every event. From a review of the docs PR. | | `5ad3cfe8` | `result` on `docs_search` becomes `picked_result`. Next to `result_count` a reviewer read it as the list of results, sent empty. | | `367cf0be` | `category` is required on every entry, by the parser and the schema. No entry counts as `analytics` any more. The flag's help and the README lose "or not set". `oneOf()` loses its fallback, and `brand.colorMode` gets its default through `optional()`. | | `95780b18` | The state a window shares is `WindowAnalytics`, held under `WINDOW_ANALYTICS`, with a comment saying it means the `Window` object, which a reload replaces. "Page" in this code now means a route only. From a review comment on this PR, as is the next. | | `37db2b44` | `start()` keeps that state on the instance and is the one place that reads the global. An instance whose start asked for a reload used to find the state anyway, and its next page view inserted the new script into the window being left. It now adds no tag and hands over no event. | | `9a6e19b4` | `window.gtag` counts as a gtag only when it is a function. A browser answers that name with an element whose id is `gtag`, such as a guide's heading, and on a fresh load of such a page the portal called the heading and its whole script stopped. Portals with Google Analytics had this from #473. New finding 1 of the re-review, as are the six commits after it by their numbers. | | `7b491436` | The build test for the consent setting reads the setting's value, and a second build, without the setting, has to fail the same check. It used to look for two texts that every build holds. New finding 4. | | `a895b2cd` | A `--no-analytics` build keeps the consent default. A script such a build keeps may load a Google tag of its own. New finding 3. | | `eb200e91` | The schema's description of `googleConsentMode` says "Google's own tags", says that other vendors' tags in a container need their own consent checks, and no longer says "set here". New finding 5. | | `a3a04d3e` | The addresses the window remembers start with the `src` of every script `<head>` holds when the portal starts, so a script the host injects itself gets no second copy. New finding 7, a regression of `78505ad0`. | | `f7518097` | `analytics` is defined on the object a host keeps at `window.apimatic`, when that object takes a property. A copy is made only for one that does not. New finding 6. | | `ae99bcc1` | A backslash is refused anywhere before an https address's path, by the schema's pattern and the CLI's alike, and the report asks for "an address starting with 'https://' and a host". New finding 8. | | `37dcd1b3` | `gtagFor()` sets `window.gtag` before it returns it, not inside the return expression, which SonarCloud flagged (S1121) after `9a6e19b4`. | | `b9450b72` | A `--no-analytics` build writes no event to `window.dataLayer` either: `report()` returns at once. The consent default, queued in `start()`, is the one thing such a build puts there. From a review comment on this PR. | | `6792fa8d` | The identity's switch is `analytics.events`, no longer `analytics.eventFeed`, since it turns off the data layer's events too. It is still refused as a setting in `apimatic.json`. | | `15aaf820` | The schema's description of `scripts` names the token an OAuth 2.0 sign-in leaves in session storage among what a listed script can read. Tracked in apimatic/apimatic-io#2355; wording from the review. | | `144c6b73` | The schema's description of `googleConsentMode` says it does not affect which scripts in `portal.scripts` are loaded, or when, in place of "holds back no script". Wording from the review. | | `482418b2` | The schema's description of a script's `category` says what belongs in each of the four, with examples, and that a script doing more than one thing takes the last that applies. From the review. | | `665c8ef9` | `windowGtag()`, `scriptsInHead()` and `putOn()` are inlined where they were called, by the rule `3fc4fdd3` adds to `.ai/instructions.md`: each one's doc comment, signature and brace outweighed its body. Nothing changes in what the portal does. | ## Decisions on record Each is a departure from the issues, made with the reviewer during the build and written up in apimatic/apimatic-io#2351 (section 4 and section 1, row 22), except the four that answer the review of 2026-11-17 and the last two, of 2026-11-18, which are written up here only. The issues themselves are not edited yet. - **No `attributes`.** An entry is `{ src, category }`. A file in `static/` can add a vendor's tag and set its attributes, and Plausible, the issues' example, now gives out a site-specific address with an inline call. Adding the key later breaks no config. - **`category` is not written to the identity file.** Nothing in the browser reads it in this release. - **Two reports for `src`, not three.** What is neither an `https` address nor a file in `static/` gets one report naming both choices. - **Events from before a subscription arrive just after `subscribe()` returns**, not inside it, so `const stop = subscribe(…)` can call `stop()` on the first event. - **`toJSON()` does not write `scripts`**, as it writes neither `analytics` nor `seo`. - **No second Vite build for `--no-analytics` in the build test.** `portal-project-service.test.ts` proves the identity file, as for #473. - **The flag's help** is `leave out the tags set in 'portal.analytics' and each script in 'portal.scripts' whose category is 'analytics' or 'marketing', and hand no event to the scripts that stay.` "The Google Tag Manager and Google Analytics tags" became "the tags", and `17ddf35f` added the events. `5f1d49d9` had added "or not set", which `367cf0be` took out with the default. - **A `--no-analytics` build hands no event to the scripts it keeps** (`17ddf35f`). This reverses a bullet written here earlier on 2026-11-17, which called the open feed a design choice. `subscribe()` stays in place, so a kept script does not throw on a staging build. - **A `--no-analytics` build writes no event to the data layer either** (`b9450b72`). This reverses what stood in the bullet above until 2026-11-18: "the data layer still gets its entries: no vendor reads them there". Since `a895b2cd` keeps the consent default for a Google tag a kept script loads, a vendor can read them there: a tag manager such a script loads fires on the data layer's events. The cost is that a preview made with the flag no longer shows in the console what would have been reported. - **Consent Mode defaults are queued in the setup, and nothing is held back.** #2347 already says GTM and GA4 are never held back and get Consent Mode defaults in their setup. Holding the tags until `necessary` scripts have run was considered and not built: it needs a queue for events, delays analytics by the slowest script, never starts if one hangs, and still races for a consent tool that sets its default late. - **`googleConsentMode` is Google's alone.** It is `{ "default": "denied" }`, an object so that a later key changes no config, and it holds no listed script. The portal-wide consent setting of #2347, which holds scripts by category and gives `window.apimatic.consent.update`, stays a later phase under a key of its own. - **The wait is fixed at 500 ms, and "denied" covers the four Consent Mode v2 types.** The setting is accepted with no built-in tag, for a Google snippet the customer lists themselves. - **A `--no-analytics` build keeps the consent default** (`a895b2cd`). This reverses what stood here until 2026-11-18, that such a build queues nothing for Google. It keeps `necessary` and `functional` scripts, and an owner may load Google's own snippet from one of those, the route this description gives for no contact with Google before consent. On staging only, that snippet then started with no consent state. The default does nothing where no Google tag loads. - **`category` is required** (`367cf0be`). This reverses the default of `analytics` that #2351 records. A reviewer's point: a customer who never chose a category has no way to see why `--no-analytics` dropped a script. What the default guarded still holds, since only a script someone marked `necessary` or `functional` survives the flag. A missing category is reported as `'portal.scripts[0].category' is required.` No release has `scripts`, so no config breaks. - **The four categories stay, and each is defined** (`482418b2`). The review asked why there are four when two behave alike today, `necessary` with `functional` and `analytics` with `marketing`. They are the groups consent tools ask readers about: Cookiebot's necessary, preferences, statistics and marketing, and OneTrust's strictly necessary, functional, performance and targeting. #2347 records them for that reason, for the later consent setting that holds each script until the reader agrees to its group. That setting needs both splits: a reader may accept statistics and refuse marketing, and a chat widget can wait for consent where a consent tool cannot. Merging two names now would leave every config that used the merged one meaning the wrong thing once they split. `preferences` is what `functional` covers, and a fifth group, such as OneTrust's social media, can be added later without breaking a config. - **Three value-object methods keep their own place** although they fall under the rule of `3fc4fdd3`: `AnalyticsConfig.withoutAnalytics()`, `Script.staticFiles()` and `Script.loadsWithoutAnalytics()`. Each answers from private state, so inlining it would mean exposing that state to its caller. - **Three event keys are renamed after #473 went out on the `beta` tag** (`be9556c2`, `5ad3cfe8`). A container built against 2.3.0-beta.1 that reads `docs.language` or `docs.result` gets nothing from them after this, with no error. The docs were not published with that beta. ## Known limits - **A listed script that never answers.** Measured in headless Chrome with a host that accepts the connection and sends nothing: the page, GTM, GA4 and page views are unaffected, but the listed scripts after it do not run while it is pending. On a built portal the window's `load` event also does not fire in that time, so GTM's "Window Loaded" trigger waits with it. Under `portal serve` `load` had already fired. A script that fails outright (a host that does not resolve) holds nothing. - **No consent gating.** Every listed script loads for every reader, whatever its category, unless the build used `--no-analytics`. - **Without `googleConsentMode`, a listed consent script can still lose to the built-in Google tags.** Measured with Google Analytics and the consent script 1.5 s late: Google set its `_ga` cookies and sent the page view with no consent state. With the setting on, the same run set no cookie and marked the page view denied. A customer whose banner decides what is tracked has to set it, and the docs must say so. - **A consent tool's own default replaces the portal's, wait included.** A stand-in that queued its own "denied" default, with no wait, after the portal's kept the state denied, and a returning reader's first page view then went out as denied. With no second default the wait held and it went out as granted. - **`googleConsentMode` is Google's advanced Consent Mode.** Both tags load before the reader answers and send hits marked denied, with no cookie. A customer who wants no contact with Google before consent lists Google's own snippet from a file of theirs that waits; list order holds (measured). - **No `integrity`.** The key is refused as unknown, so a build fixes a script's address but not what it serves. A script listed by its address runs whatever the address serves at each page load: a change by its vendor, or by anyone who takes the address over, reaches a published portal without a rebuild. A file in `static/` changes only with a rebuild, apart from code it loads from elsewhere. Documented rather than fixed, for now: a [review comment on apimatic/apimatic-docs#887](apimatic/apimatic-docs#887 (comment)) asks the scripts warning to say so. An optional `integrity` key can come later without breaking a config. - **Any listed script can read the page**, the API playground included. The replay markers, and keeping scripts off the OAuth callback, limit what a well-behaved vendor script picks up; they do not sandbox a script. - **On the page a sign-in returns to, listed scripts load at once, while the provider's answer still waits in the tab's session storage.** Since the merge with `dev` (#478) the answer is in no page's address but the callback's, where nothing loads. It waits in session storage until a playground reads it, and on a page with no playground it stays for the life of the tab. A listed script that reads session storage can read it there: seen in a browser, a script starting on the returned page read the callback's address, `code` included. #478 accepted that window for the Google tags, which read the address and not the storage. For listed scripts it is tracked in apimatic/apimatic-io#2355: the schema's description of `scripts` names the token (`15aaf820`), and fuma-nama/fumadocs#3874 asks Fumadocs for an option to keep it out of session storage. Whether portals must keep it out of listed scripts' reach altogether is still to decide. Holding them until the playground has taken the answer would not keep a credential from them. Measured with a sign-in through the playground against a stub provider that answers in the implicit flow: a listed script starting on the returned page read the token in the waiting answer; the playground then kept the token in session storage, as `fumadocs-openapi-auth-oauth`, for the life of the tab; and the same script read it there at its next start, on a guide page with no playground. - **`window.apimatic` does not exist for a script the host injects into `<head>` itself**, which runs before the portal's bundle. If such a script puts an object of its own at `window.apimatic.analytics`, the portal replaces it at its start, and callbacks queued on the old one are not carried over. - **A page that made `window.apimatic` read-only and froze its object gets no `subscribe()`.** The portal starts and works, and the error shows in the console. A listed script that calls `window.apimatic.analytics.subscribe()` fails there. Where the object behind the read-only name still takes a property, the portal puts `analytics` on it and nothing is in error (`f7518097`; seen in a browser for a read-only property, not run again for a getter alone). - **A script the host injects is told from a listed one by its `src` as written.** The same file under another spelling of its address, relative where the portal writes it from the root, gets a second copy. - **The schema passes three malformed hosts that the CLI refuses:** `https://:443/…`, `https://[::1/…` and `https://cdn.exa%mple.com/…`. An editor shows no warning for them, and `portal generate` reports the address. ## Risk **Medium.** #473 is out on the `beta` tag only, as 2.3.0-beta.1 (`latest` is 2.2.0, which has none of it). Nothing of this PR is released, and it builds on #473. - **What changes for every portal, scripts listed or not:** - The loader remembers the addresses it has inserted, and reads `<head>` once, at its start, for the scripts already there. This applies to the two Google tags too. It takes `window.gtag` as Google's only when it is a function: a browser answers that name with an element whose id is `gtag`, such as a guide's heading, and `dev`'s GA4 tag calls whatever the name holds, which stops the portal's script on such a page. - The mark of a started page, which #473 kept at `window.portalAnalyticsStarted`, is held under a symbol on the window with the feed. - Every portal gets `window.apimatic.analytics`, and keeps each reported event in memory for the life of the page. - `portal.identity.json` gains `analytics.googleConsentMode` and `analytics.events`. A portal that sets no consent mode queues nothing new, and its events are on. - `pluginUrl` is checked by the same rule from a shared function, and its pattern in the schema moved to a shared definition. A `pluginUrl` with no host before its path (`https:///…`) or with a backslash in its host (`https://host\x.zip`) is now refused; the CLI used to accept both, writing the first without the extra slash and the second with a slash for the backslash. A portal with no `scripts` loads nothing new. - **What changes only for a portal that lists scripts:** those scripts run on every page, the API playground included, with full access to the page. That is the feature, and choosing them is the customer's. - **What cannot be taken back after a release:** the shape of an entry, the four category names and that one is required, `window.apimatic.analytics.subscribe()`, the event it hands over and the keys of each event, and `googleConsentMode` with its one value. Customers will write configs and scripts against them. - **What stands between this and a mistake:** - CI: the whole suite and the lint, on three systems and four Node versions. - Both end-to-end files. - The browser checks under "Test plan, in a browser". - A code review at `6782e26c`, whose five findings are fixed. - A second code review, by a colleague, at `6ed31b30`, and a re-review at `94c58970`. Their fourteen and ten findings are answered under "Before merging". - Two security reviews, the second on `6ed31b30`, which found no vulnerability. - **Where the cover is thin:** - The browser checks were Chrome, with one run each in Firefox and in WebKit on Windows. Safari itself was not run. - The sign-in path was checked by opening the callback by hand, with a typed `code` and `state` and the starting page put in session storage, not with a provider's round trip. One sign-in was then run through the playground itself, against a stub provider that answered in the implicit flow. No real provider has been used. - Real vendors' scripts run: Google's GA4 snippet with a `subscribe()` forwarder (at `6ed31b30`), an open-source consent tool and an open-source session recorder. Not run: a commercial consent tool or replay tool, a chat widget, Segment, or a vendor that reads `data-` attributes. - The thirteen commits after the merge (the second review's fixes and its two follow-ups) have tests and both end-to-end files behind them, and a browser run each: on a preview for the first eight, and on built files too for the consent mode and `--no-analytics`. The re-review at `94c58970` read them; none has had a security review. - The five commits of 2026-11-18 have tests behind them. The first three also have the build end-to-end file, a browser run for the two renames and a run of `portal generate` for the required category. The last two have a browser run on a preview. None has had a code or security review beyond the comment the last two answer, and neither end-to-end file was run locally for the last two. - The seven commits that answer the re-review have tests, both end-to-end files and a browser run on built files behind them, or a run of `portal generate` for the address rule. None has had a code or security review. Two of them change what a host sees: where `analytics` is put on `window.apimatic`, and which scripts in `<head>` count as inserted. - The three commits after them have tests, both end-to-end files and a browser run on a `--no-analytics` build behind them. None has had a code or security review beyond the comment and the SonarCloud issue they answer. - The four commits of 2026-11-19 change three schema descriptions and inline three helpers. They have the schema test, the unit files, both end-to-end files and a browser run on built files behind them, and no other review. - The one real consent tool run against `googleConsentMode` is open source and wired to Consent Mode by hand, as its guide shows. A commercial tool that queues its own default may behave as the stand-in did (see "Known limits"). - The merge with `dev` (`310f38ab`) changed when listed scripts load around a sign-in. That has unit tests, both end-to-end files, a browser run and the re-review at `94c58970` behind it, but no security review. - **No data or state to migrate.** Nothing is stored, and `portal.identity.json` is rewritten on every run. ## How to revert - **On `dev`, before a release:** revert this PR's squash commit with `git revert`. It is one commit, nothing depends on it yet, and there is nothing to migrate or clean up. The revert also takes `--no-analytics` back to leaving out the two Google tags only, with its earlier help text and README lines, and takes `scripts` and `googleConsentMode` out of the schema. - **After a release:** prefer a fix forward. A revert breaks every config that lists scripts or sets `googleConsentMode`: a CLI without this change refuses both as unknown settings, so `portal generate` and `portal serve` fail until the customer removes them. - **A portal already published keeps what it was built with.** It is static files, so reverting the CLI takes no script off a live portal. To stop one, remove its entry from `apimatic.json`, rebuild and redeploy. For `analytics` and `marketing` scripts, building with `--no-analytics` does the same. - **For one customer, without touching the CLI:** remove `scripts` from `apimatic.json` and rebuild. The portal then loads none, and `window.apimatic.analytics` stays there unused. - **There is no feature flag.** ## Before merging - [ ] **Release together with #473.** This PR is what that PR's "Release together with PR 2" item waits for: until it merges, `dev` holds a `--no-analytics` that drops less than it will. - [x] **CI green on `6ed31b30`**, the last commit before the merge with `dev`: the whole suite and the lint, on Ubuntu, macOS and Windows with Node 22, 22.14, 24 and 26. On `6782e26c` the tests passed (2,526 on `ubuntu-latest / Node 24`) and the lint after them failed on the fixture script, which `a0c6d999` fixes. The whole suite was not run locally. - [x] **CI green on `310f38ab`**, the merge with `dev`: all 16 checks. - [x] **CI green on `07ee1f45`**, after the second review's fixes: all 16 checks. - [x] **CI green on `94c58970`**: all 16 checks. - [x] **CI green on `367cf0be`**: all 16 checks. - [x] **CI green on `37db2b44`**: all 16 checks. - [x] **CI green on `ae99bcc1`**: all 16 checks. - [x] **CI green on `6792fa8d`**: all 16 checks. - [x] **CI green on `665c8ef9`**, the head: all 16 checks. - [x] **The re-review at `94c58970`** (a second review, which read the fixes at that commit and raised ten new findings). Each was checked first: the dead page of finding 1 was reproduced on built files, and finding 4 on two builds. Fixed: a heading called "gtag" stopped the portal's script (1, `9a6e19b4`); a staging build dropped the consent default (3, `a895b2cd`); the consent setting's build test could not fail (4, `7b491436`); the schema promised more than Consent Mode does (5, `eb200e91`); a host's own object at `window.apimatic` was swapped for a copy (6, `f7518097`); a script the host injects was loaded twice (7, `a3a04d3e`); a backslash passed for a host (8, `ae99bcc1`); a config save could insert the new script into the window being left (9, `37db2b44`, which a comment on this PR asked for). Not changed: listed scripts can read a sign-in's answer in session storage (2), tracked in apimatic/apimatic-io#2355, since holding them would not keep the token from them (see "Known limits"); and the list of wanted scripts is still built on each page view, and two field comments stay (10). - [x] **The review of 2026-11-16** (a code review of this PR, findings checked by hand). Fixed in `5f220732` and the two refactors after it: `window.apimatic.analytics` was the feed object itself, so `publish()` and the event list were reachable from any script; `subscribe` threw when called detached from that object; an object a page had already put at that name made every report throw; `EventFeed.deliver()` was a private instance method, which `.ai/instructions.md` rules out; and `insertTags()` read `<head>` once per script. Seen in a browser with a page's own stand-in set first. Left as they are, on purpose: an address with a space around it is refused while a static path with one is accepted; the event history is not capped; missing-file checks read a folder once per file. A security review of the diff found no vulnerability. - [x] **The review of 2026-11-17** (a colleague's review at `6ed31b30`, fourteen findings, each checked against the head, the runtime ones reproduced in a browser or in Node first). Fixed in the eight commits after the merge: a script that removes its own element was inserted again on every page view (1, and 10 with it); the feed was reachable at `window.portalEventFeed` (3); a page that had made `window.apimatic` read-only stopped the bundle (4); a callback got the feed's record of it as `this` (5); the CLI accepted and rewrote `https:///…`, which the schema refuses (6, and the double parse of 11); the flag's help left out scripts with no category (9); `staticFile()` answered `null` (12); three comments restated the code (14). Fixed after those, on the reviewer's word: a listed consent script could not hold back the built-in Google tags (2), by `googleConsentMode` in `1547e424`; and `--no-analytics` handed events to the scripts it kept (7), in `17ddf35f`. Left as they are, on purpose: the event history is not capped (8), as after the first review; the browser tells a portal file from an address by its leading `/` (13), which is the rule `api-markdown.tsx` on `dev` uses for images, and tests pin what the CLI writes; `isWebAddress()`, which checks links and the site address, keeps its own rule (the rest of 11). - [x] **The manual list** is closed. Three of its checks were run with real tools on 2026-11-17 and are in the browser list; the others were dropped: each is covered by a run above or by a test, is a docs example, or is optional. - [x] **Review comments.** Rafay's two, both on `analytics.ts`: the name of the state a window shares (answered by `95780b18` and `37db2b44`, resolved), and `--no-analytics` writing every event to the data layer (answered by `b9450b72`, resolved). SonarCloud's one new issue on this PR, S1121 in `vendor-tags.ts`, is answered by `37dcd1b3`. Rafay's last three, on `apimatic.schema.json`: the sign-in token in the description of `scripts` (`15aaf820`, resolved), plain words for what `googleConsentMode` leaves to listed scripts (`144c6b73`, resolved), and defining the four categories and saying why there are four (`482418b2` and "Decisions on record", answered and left open for Rafay). The rule Rafay added to `.ai/instructions.md` in `3fc4fdd3` is applied by `665c8ef9`. - [x] **The docs**, in apimatic/apimatic-docs#887 at `0b13cb5c`, have the `portal.scripts` page with `category` required, the CLI row with the flag's wording, a consent section for `googleConsentMode`, the sign-in section as it works since #478, the three renamed event keys, and what the re-review's fixes change for a reader of them, and what belongs in each category. That PR stays a draft until this is in a full release. - [ ] **apimatic/apimatic-io#2347, #2348 and #2349** record the decisions above. - [ ] **The portal tests** of apimatic/v4-test-automation, which run on a push to `dev` and not on a pull request: dispatch them on this branch. ## Test plan, automated Run on the tree of `6782e26c`; the lint and the analytics and feed tests again on `6ed31b30`, and the build test on `8d117512`. After the merge with `dev`, on `310f38ab`: `tsc` for all three, `eslint .`, every `test/portal-template` file with the config, schema and flag tests (1,130 passing), and both end-to-end files (79 and 6 passing). After the second review's fixes, on the tree of `07ee1f45`: `tsc` for all three, every `test/portal-template` and `test/types/portal` file with the schema, flag, `portal-source-context`, `portal-project-service`, `serve` and `quickstart` tests (1,449 passing), and both end-to-end files (79 and 6 passing); `eslint .` on `07ee1f45` itself. After the two follow-ups, on the tree of `94c58970`: `tsc` for all three, those unit files with `prepare-project` and `portal-template.test.ts` (1,491 passing), and both end-to-end files (80 and 6 passing); `eslint .` on `94c58970` itself. `17ddf35f` and `1547e424` each passed the type checks and those unit files on their own. After the three commits of 2026-11-18, on the tree of `367cf0be`: `tsc` for the CLI and the tests, the unit files those commits touch with the config, schema, source, project, serve and template ones (792 passing), `test/e2e/portal-build.test.ts` (80 passing) and `eslint .`. `tsc` for the template was run after the two renames, which are all that touch it. After `37db2b44`: `tsc` for the template and the tests, the analytics and feed tests (100 passing) and `eslint .`. After the seven commits that answer the re-review, on `ae99bcc1`: `tsc` for all three, the config, schema, source, project, serve and template unit files (804 passing), both end-to-end files (81 and 6 passing) and `eslint .`. After the three commits that follow, on `6792fa8d`: `tsc` for all three, the same unit files (805 passing), both end-to-end files (81 and 6 passing) and `eslint .`. After the four of 2026-11-19, on `665c8ef9`: the same again (805, 81 and 6 passing), with the schema test after each schema commit. - [x] `tsc` for the CLI, the tests and the template (the template's known errors from ungenerated files only). - [x] `eslint` on each step's CLI and test files, and `prettier` on every changed TypeScript file. Neither reads the schema, and `eslint` skips the template's `lib/`. - [x] Unit: `portal-config`, `portal-source-context`, `preview-config`, `portal-project-service`, `schema`, `analytics`, `event-feed`, `portal-template`, and the action and command tests that read the default fixture. Each step added tests to its own files. - [x] `eslint .`, the whole tree, as CI runs it after the tests: clean on `6ed31b30`, on `07ee1f45`, on `94c58970`, on the tree of `367cf0be`, on `ae99bcc1`, on `6792fa8d` and on `665c8ef9`. - [x] `APIMATIC_E2E=1` with `test/e2e/portal-build.test.ts`: 81 passing on `ae99bcc1`, 80 on `94c58970` and on the tree of `367cf0be`, 79 before the consent mode's test. `APIMATIC_E2E=1` with `test/e2e/portal-serve.test.ts`: 6 passing, again on `ae99bcc1`. Both again on `6792fa8d` and `665c8ef9`: 81 and 6. ## Test plan, in a browser (run on Windows: headless Chrome, and one run in Firefox and in WebKit) Against `portal serve` and against `portal generate` output served statically, with GTM and GA4 set. Listed addresses pointed at a local `https` host, so order, delay, failure and silence were exact. - [x] **Order and place.** Scripts sit in `<head>` after the vendor tags, `async` false, and run in list order with the first served 1.5 s late. Seen on a preview and on a built portal. No prerendered page names one. - [x] **Once per page.** After three page changes through the portal's links, each element is there once, ran once and was fetched once, an address with a `\` in its query included. - [x] **A static file.** Loads from `/js/…`, and from `/docs/js/…` with a path in `portal.site.url`, on a preview and on a built portal. - [x] **A missing file.** `portal generate` fails naming `portal.scripts[1].src`, and names the spelling on disk when only the case differs. A config save under `serve` that names one is refused and the page keeps what it had. - [x] **Categories** (run before `367cf0be`, when an entry could still have none). Six probes (one per category, one with none, one static file marked `necessary`). Without the flag all six run, on a preview and a built portal. With `--no-analytics`, on both: only the `necessary` and `functional` ones run, the host is never asked for the others, no Google tag is on the page, the page view is still reported. In the built files, none of 138 holds a dropped address or either ID. - [x] **Config saves under `serve`.** Adding a script reloads the page with it. Editing the description reloads nothing. Under `--no-analytics`, adding an `analytics` script changes nothing and adding a `necessary` one reloads with it. - [x] **Subscribe.** A listed file with four subscribers: a forwarder got the page view from before it loaded, then two page changes, a code copy and a search, the same five events in the same order as the data layer. Each had exactly `name`, `params`, `time`, `version`, both objects frozen. A subscriber that tried to change events changed nothing the next one saw. A one-time subscriber got one event and stopped. A throwing one showed one console error per event and stopped nothing. All of this on a preview; on a built portal under a path, the replay, a page change, the one-time subscriber and the throwing one. - [x] **Through a config save.** A subscriber from before a save that changed nothing got the next page view. - [x] **Around a sign-in** (preview, on `310f38ab`). On `/oauth/callback?code=…&state=…`: no vendor tag, no listed script, no page view. Sent back from the callback to the page that started the sign-in: that page's address is its own, the tag and every listed script load at once, and the page view has the clean address. A listed script starting there could read the answer in session storage; on the API reference page it was gone once the playground had loaded, and on a guide page it stayed. The callback was opened by hand with a typed `code` and `state`, and the starting page put in session storage, not a provider's round trip. - [x] **A `state` of the customer's own** (`?state=CA`, and `?code=…&state=…` in a page's own link; on `310f38ab`): the tag and every listed script load at once, and the page view is reported without them. - [x] **A script that fails** (a host that does not resolve), first in the list: the next ones run, the page works. - [x] **A script that never answers**, first and last in the list: see "Known limits". - [x] **Replay markers.** A listed script with its own `MutationObserver` saw the playground dialog already carrying every marker. - [x] **A script that removes its own element** (preview, on the tree of `07ee1f45`). Before the fix it ran twice on the first page and once more on each page change. After it, once for the whole visit, across three page changes. - [x] **A page that locked `window.apimatic`** (same preview), read-only and with a getter alone. Before the fix the bundle threw and the page never came to life: no theme switch, no listed script, no Google tag. After it the theme switch works, the Google tag and the listed scripts load, and the console shows the error. Run on the tree of `07ee1f45`; since `f7518097` the read-only case gets `subscribe()` and shows no error (below). - [x] **What the window holds** (same preview). No name on the window holds `portal`, and `window.apimatic.analytics` has `subscribe` alone, frozen. A callback written without strict mode that pushes to `this.vendorQueue` filled `window.vendorQueue`. - [x] **Config saves again** (same preview). Saving a description reloads nothing, runs no script again and keeps the subscriber. Adding a script reloads the page with it. - [x] **A consent script against the built-in tags** (on the tree of `94c58970`; every hit was answered in the browser, so none reached Google). With `googleConsentMode` and a consent stand-in 1.5 s late: the data layer leads with the portal's default, no cookie is set, and the page view is marked denied, on a preview and on built files. Without the setting the same run set `_ga` cookies and sent the page view with no consent state. - [x] **A reader who agrees** (preview). After `gtag('consent', 'update', …)` the cookies appear and the next hit is marked granted. A returning reader whose answer came 300 ms after Google's library ran got a first page view marked granted. - [x] **A GTM container** (preview, GTM-KRV5DMCJ) with the setting: the default leads the data layer, no cookie is set, and hits are marked denied. - [x] **A config save that adds the setting** (preview) reloads the page, whose data layer then leads with the default. - [x] **`--no-analytics` and the event feed** (preview and built files). A kept `functional` script that subscribes ran once and was handed nothing across three page views. `subscribe()` gave back a function, called detached too; the data layer held each page view; there was no `window.gtag` and no Google tag. Without the flag the same script got all three. Run before `a895b2cd`: with the consent setting, such a build now queues the default and has a `window.gtag`. Since `b9450b72` the data layer holds no page view either (below). - [x] **`--no-analytics` and the data layer** (built files on `6792fa8d`, `googleConsentMode` set, a `necessary` script standing in for a tag manager that watches the data layer, and Google's own snippet listed as `functional`). After a fresh load, a page change and a search, the data layer holds the consent default, the snippet's own commands and Google's `gtm.dom` and `gtm.load`, and no `docs_` event. The stand-in saw no portal event, a subscriber got none, no cookie was set, and the snippet's page view was marked denied. - [x] **A host with a Content Security Policy** (built files at `94c58970`). With neither host in `script-src`, the listed address and Google's tag are refused, the listed file after them still runs and gets its events, and the theme switch and the in-app links work. With both hosts added, everything loads. - [x] **A real consent tool** (vanilla-cookieconsent 3.1.0, open source, listed in `portal.scripts` beside GA4 built in with `googleConsentMode`, and wired to Consent Mode as its guide shows; a preview at `94c58970`). On a first visit the banner is up, the portal's default leads the data layer, no cookie is set and the page view is marked denied. After "Accept all" the tool sends its update, the `_ga` cookies appear and the next hit is marked granted. On a return visit with the answer stored there is no banner, the update lands ahead of the first page view, and that page view is marked granted. Tag Assistant was not used: the hits themselves were read. - [x] **A real session recorder** (rrweb 2.0.0-alpha.4, listed in `portal.scripts`; the same preview). With the playground open, a number typed into its field is not in the recording, which holds a blocked placeholder for the dialog. A term typed into the search box is in it. This proves the `rr-block` marker alone; the markers for Hotjar, Clarity, FullStory, LogRocket, PostHog and Amplitude were not tried against those tools. - [x] **Firefox and WebKit** (Playwright 1.64.1 on Windows: Firefox 157.0, and WebKit 27.2, the engine Safari uses; built files at `94c58970`). In both: the listed scripts sit in `<head>` in list order and not async; with the first served 1.5 s late, the files after it still ran after it; each ran once across four page views, one that removes its own tag included; a forwarder got every page view, and a late subscriber was handed all four; `subscribe` alone, frozen; the theme switch and in-app links work, with no error. - [x] **The renamed keys** (a preview with both renames, GA4 built in, every hit answered in the browser). A code copy, an SDK download and two searches, one closed and one with a pick, reach the data layer, a subscriber and GA4's own hits as `code_language`, `sdk_language` and `picked_result`. GA4's language field stays `en-us` on each. Before the rename a code copy set it to the code's language. - [x] **A heading called "gtag"** (built files; a preview does not show it, since its heading is not in the page when the script starts). Before `9a6e19b4`, on a fresh load of a guide with that heading: `window.gtag` is the heading, the console shows `a(...) is not a function`, search does not open, the theme switch does nothing, no listed script runs and no hit is sent. After it all of those work and the consent default leads the data layer. - [x] **A staging build that lists Google's own snippet** (built with `--no-analytics` on `ae99bcc1`, the snippet listed as `functional`, `googleConsentMode` set and no built-in tag). The data layer leads with the consent default, no cookie is set, the snippet's page view is marked denied, and a subscriber is handed nothing. - [x] **A script the host injects** (built files on `ae99bcc1`, the tag for a listed file added to one page's `<head>` by hand). It runs once and `<head>` holds one tag for it, on the fresh load and after two page changes. - [x] **A host's own object at `window.apimatic`** (same files, the object set before the portal's script). After the start it is the same object, its class's method works, and `subscribe` is there. A read-only `window.apimatic` holding an ordinary object gets `subscribe` too, with no error. - [x] **An address with a backslash for its host** (`portal generate` on `ae99bcc1`). Refused for a listed script and for `pluginUrl`, with the report that asks for a host; so is `https:///…`. A backslash in the path is accepted. - [x] **After the helpers were inlined** (built files on `665c8ef9`). The four checks above for `ae99bcc1` (a heading called "gtag", a script the host injects, a host's own object and a read-only `window.apimatic`, a staging build with Google's own snippet) and the data layer check for `6792fa8d` give the same results. - [x] **Config saves after `37db2b44`** (preview, on its tree). Saving a description reloads nothing and runs no script again, and the subscriber gets the next page view. Adding a script reloads the page with it, and a counter kept across the reload shows the added script ran once. - [x] **A config with no category** (`portal generate`, on the tree of `367cf0be`). It stops and reports `'portal.scripts[0].category' is required.` for the entry that names none, and the four choices for one that is misspelt. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Muhammad Sohail <sohail.shahbaz@apimatic.io> Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com> Co-authored-by: Muhammad Rafay Nadeem <muhammad.nadeem@apimatic.io>
sohail2721
added a commit
that referenced
this pull request
Nov 19, 2026
…stay (#480) The `--no-analytics` help for `portal generate` and `portal serve` said the flag would "hand no event to the scripts that stay", which took a second read. It now says "send no events", in the flag's help and the README. The docs say the same since apimatic/apimatic-docs#887: the CLI Reference rows, Add Custom Scripts and the changelog. This keeps the help text and the docs in step before the release that ships #473 and #477. Only the wording changes. Typecheck, the portal command flag tests and `eslint .` pass. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Muhammad Sohail <sohail.shahbaz@apimatic.io> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.



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.analyticsloads Google Tag Manager and GA4 fromapimatic.json, and the template reports each page view once asdocs_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 intodev.Draft until the gate:
pnpm testgreen, 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.
portal-template/src/routes/__root.tsx) reports the first page's view on mount and one peronRendered;head()lists no script, and writes thegoogle-site-verificationmeta when the identity file holds a value.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 thedata-portal-playgroundtest 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.portal-template/src/lib/portal-analytics.ts) runs at module evaluation, before React and before any vendor tag, never during prerendering: firstmarkPlaygroundDialogs()(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), thennew Analytics(portal.analytics).start().portal-template/src/lib/analytics.ts) holds the event table and theAnalyticsclass:start()createswindow.dataLayer, pushes every vendor's setup entries and inserts the tags, once per page load, and underportal servereloads the page when a config save changes the vendors;report()adds the cleanedpage_location(pageLocation()), pushes{ docs: null }then{ event, docs }, and calls each adapter that sends for itself;reportPageView()andreportNotFound()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()inlib/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()fromcomponents/playground.tsx).portal-template/src/lib/vendor-tags.ts): theadaptersregistry is keyed by both vendors, so a vendor without an adapter does not compile. GTM pushesgtm.startand loadsgtm.js(with theenvironmentsuffix when set), and reads the data layer itself. GA4 defineswindow.gtagonly when missing, pushesjsandconfigwithsend_page_view: false, loadsgtag/js, sends each event under GA4's own name, and setspage_locationon 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.components/code-copy.tsx, through Fumadocs'Actionsslot) with the block's language ID, the IDs SDK downloads send too (csharp,shellscript), both throughlanguageId(), which reads a name in lowercase and knows the common short names of languages outside the bundle (ktiskotlin), 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 issearchOutcome()(lib/search-report.ts): the result picked goes out as a whole address in the form ofpage_location, and the term at most 100 characters long, which is what GA4 keeps.portal-template/src/lib/portal-types.ts,PortalIdentityinsrc/types/portal/portal-config.ts) carriesanalyticsandseo, filled byAnalyticsConfigandSeoConfigfrom theportalblock, 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 generateandportal servewarn when GA4 is set.--no-analyticsonportal generateandportal serve, defined once inFlagsProvider) reaches the actions asPortalBuildOptions, andPortalSourceContextapplies it where the settings are read, for a build and for each config save underportal serve: both vendors are dropped, the kept query names stay. The options have no default, so every caller chooses.portal serveloads exactly what a hosted portal loads: no debug mode, no preview distinction, so the sketchedPortalDeliveryis not built (decided 2026-11-12, to record in #2347).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.test/e2e/portal-build.test.ts, behindAPIMATIC_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 thebutton[aria-live]its copies are reported by, so a Fumadocs update that changes either fails here.test/commands/portal/*-flags.test.tsrun 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.2docs_code_copy, 3.3docs_search, 3.4docs_not_found, 3.5docs_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
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 againstportal servewith both vendors: no tag at#access_token=…&state=…, both once the address was clean, and no GA4 hit carrying the token.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, sincepageLocation()strips both. 12.6.2'sgetReturnedFlow()reads the answer fromsessionStorageunderfumadocs-openapi-oauth-returnedand 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 storeslocation.hrefunder that key, withtest/portal-template/oauth-callback.test.tsand the comment atoauth-callback.ts:20following.devpins 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 inpnpm-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, commit1c616d56) was removed on 2026-11-12.portal.scripts). PR 2 makes--no-analyticsalso leave out theanalyticsandmarketingscripts, 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.searchOutcome(),apiRequest()and the built-page checks.docs_plugin_install, nodocs_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_foundwith the page left, plus its page view), and a playground request with a response and one that fails (client_error), withdocs_api_requestnever carrying the request address.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 ontodevand retargeted the same day.An end-to-end run on 2026-11-13 (headless Chrome against
portal serveand 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 apluginblock. It also found the first page view inportal servecarrying the site name as its title, fixed in__root.tsxby reporting directly only when the router is idle at mount.Decisions on record: the e2e list's "a
--no-analyticsbuild holds no ID" check is not intest/e2e/portal-build.test.ts;test/infrastructure/portal-project-service.test.tschecks 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 frombe8cc928on; the review of 2026-11-13 requesting changes from09a22ba3to96885d4d, with the OAuth return page in1bb6dfbb, 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
f54b30efto02200bbc, 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.statusstays one text value, the HTTP status as digits orclient_error. A search'sresultis a whole address in the form ofpage_location.refleft 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 throughkeepQueryParamsbut cannot take one out. The same review found the not-found page reportingdocs_not_foundfor the page a reader left it for; fixed, and seen in headless Chrome on a served and a built portal.🤖 Generated with Claude Code