diff --git a/portal-template/src/components/listed-scripts.tsx b/portal-template/src/components/listed-scripts.tsx new file mode 100644 index 00000000..d662e771 --- /dev/null +++ b/portal-template/src/components/listed-scripts.tsx @@ -0,0 +1,10 @@ +import { useEffect } from 'react'; +import { analytics } from '@/lib/portal-analytics'; + +/** Rendered with a page's content, so its effect runs once React has hydrated the page a script may change. */ +export function ListedScripts() { + useEffect(() => { + analytics.loadScripts(); + }, []); + return null; +} diff --git a/portal-template/src/components/not-found.tsx b/portal-template/src/components/not-found.tsx index 3eba7d78..e62de595 100644 --- a/portal-template/src/components/not-found.tsx +++ b/portal-template/src/components/not-found.tsx @@ -4,6 +4,7 @@ import { baseOptions } from '@/lib/layout.shared'; import { analytics } from '@/lib/portal-analytics'; import { HomeLayout } from 'fumadocs-ui/layouts/home'; import { DefaultNotFound } from 'fumadocs-ui/layouts/home/not-found'; +import { ListedScripts } from './listed-scripts'; export function NotFound() { // The path the router has settled on: its location alone already names the page a reader is leaving this one for. @@ -18,6 +19,7 @@ export function NotFound() { return ( + ); } diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts index 148d65e5..56a4cd4c 100644 --- a/portal-template/src/lib/analytics.ts +++ b/portal-template/src/lib/analytics.ts @@ -122,7 +122,14 @@ export class Analytics { throw error; }); } - insertTags(this.live, this.scripts, inserted); + // The listed scripts wait for `loadScripts()`: React drops a change one makes to the page before it hydrates. + insertTags(this.live, [], inserted); + } + + /** From `ListedScripts`, once the page has hydrated. */ + public loadScripts(): void { + const inserted = this.windowAnalytics?.inserted; + if (inserted !== undefined) insertTags([], this.scripts, inserted); } /** `href` is the page the event belongs to, when the caller saw the address move on first. */ @@ -142,8 +149,8 @@ export class Analytics { public reportPageView(): void { if (isOAuthCallbackPath(window.location.pathname)) return; const inserted = this.windowAnalytics?.inserted; - // The tags and scripts a start on the OAuth callback left out, now that the reader has moved on from it. - if (inserted !== undefined) insertTags(this.live, this.scripts, inserted); + // The tags a start on the OAuth callback left out, now that the reader has moved on from it. + if (inserted !== undefined) insertTags(this.live, [], inserted); const page = pageLocation(window.location.href, this.settings.keepQueryParams); if (page === this.lastPageView) return; this.previousPageView = this.lastPageView; diff --git a/portal-template/src/routes/$.tsx b/portal-template/src/routes/$.tsx index b884d880..1e85470f 100644 --- a/portal-template/src/routes/$.tsx +++ b/portal-template/src/routes/$.tsx @@ -17,6 +17,7 @@ import { getMDXComponents } from '@/components/mdx'; import { OpenAPIPage } from '@/components/api-page'; import { MarkdownCopyButton } from '@/components/markdown-copy-button'; import { slimOpenAPIPageProps } from '@/lib/openapi-slim'; +import { ListedScripts } from '@/components/listed-scripts'; const rootRoute = getRouteApi('__root__'); @@ -186,12 +187,16 @@ function Page() { ); } else { - content = ( - - - - ); + content = ; } - return {content}; + return ( + + {/* One boundary for every page's content: React hydrates it last, and ListedScripts with it, never before it. */} + + {content} + + + + ); } diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts index c44d685d..876bd3ec 100644 --- a/test/portal-template/analytics.test.ts +++ b/test/portal-template/analytics.test.ts @@ -580,10 +580,27 @@ describe('Analytics', () => { const WIDGET = 'https://cdn.example.com/widget.js'; const listed: PortalScript[] = [{ src: SETUP }, { src: WIDGET }]; + // React drops a change a script makes to the page before it has hydrated, which loadScripts() waits for. + it('inserts none on a start or a page view, and all once loadScripts() is called', () => { + const page = browser(quickstart); + const analytics = new Analytics(withGtm(), listed); + + analytics.start(); + analytics.reportPageView(); + + expect(page.scripts.map((script) => script.src)).to.deep.equal([GTM_SCRIPT]); + + analytics.loadScripts(); + + expect(page.scripts.map((script) => script.src)).to.deep.equal([GTM_SCRIPT, SETUP, WIDGET]); + }); + it('inserts each after the vendor tags, in the order listed, and not async, so they run in that order', () => { const page = browser(quickstart); + const analytics = new Analytics(withBoth, listed); - new Analytics(withBoth, listed).start(); + analytics.start(); + analytics.loadScripts(); expect(page.scripts.map(({ src, async }) => [src, async])).to.deep.equal([ [GTM_SCRIPT, true], @@ -595,8 +612,10 @@ describe('Analytics', () => { it('inserts them on a portal with neither vendor set', () => { const page = browser(quickstart); + const analytics = new Analytics(none, listed); - new Analytics(none, listed).start(); + analytics.start(); + analytics.loadScripts(); expect(page.scripts.map((script) => script.src)).to.deep.equal([SETUP, WIDGET]); }); @@ -605,7 +624,10 @@ describe('Analytics', () => { it("inserts a file of the portal's own by its path from the root, and an address as it is", () => { const page = browser(quickstart); - new Analytics(none, [{ src: '/js/widget.js' }, { src: WIDGET }]).start(); + const analytics = new Analytics(none, [{ src: '/js/widget.js' }, { src: WIDGET }]); + + analytics.start(); + analytics.loadScripts(); expect(page.scripts.map((script) => script.src)).to.deep.equal(['/js/widget.js', WIDGET]); }); @@ -618,6 +640,7 @@ describe('Analytics', () => { analytics.start(); analytics.reportPageView(); + analytics.loadScripts(); expect(page.scripts.map((script) => script.src)).to.deep.equal([SETUP]); }); @@ -626,12 +649,16 @@ describe('Analytics', () => { const page = browser(quickstart); const twice = [...listed, { src: SETUP }]; const analytics = new Analytics(withGtm(), twice); + const second = new Analytics(withGtm(), twice); analytics.start(); + analytics.loadScripts(); analytics.reportPageView(); page.go('https://docs.test/guides/errors', 'Errors | Acme API'); analytics.reportPageView(); - new Analytics(withGtm(), twice).start(); + analytics.loadScripts(); + second.start(); + second.loadScripts(); expect(page.scripts.map((script) => script.src)).to.deep.equal([GTM_SCRIPT, SETUP, WIDGET]); expect(page.reloads()).to.equal(0); @@ -641,13 +668,17 @@ describe('Analytics', () => { it('inserts none again once its element has left the page, on a new page or for a second instance', () => { const page = browser(quickstart); const analytics = new Analytics(withGtm(), listed); + const second = new Analytics(withGtm(), listed); analytics.start(); + analytics.loadScripts(); page.scripts.length = 0; analytics.reportPageView(); page.go('https://docs.test/guides/errors', 'Errors | Acme API'); analytics.reportPageView(); - new Analytics(withGtm(), listed).start(); + analytics.loadScripts(); + second.start(); + second.loadScripts(); expect(page.scripts).to.be.empty; }); @@ -659,11 +690,13 @@ describe('Analytics', () => { analytics.start(); analytics.reportPageView(); + analytics.loadScripts(); expect(page.scripts).to.be.empty; page.go(quickstart); analytics.reportPageView(); + analytics.loadScripts(); expect(page.scripts.map((script) => script.src)).to.deep.equal([GTM_SCRIPT, SETUP, WIDGET]); }); @@ -671,8 +704,10 @@ describe('Analytics', () => { // A sign-in's answer reaches the playground through the tab's session, so the page it returns to holds none back. it('inserts them at once on a page whose own link carries a state parameter', () => { const page = browser(`${quickstart}?state=CA`); + const analytics = new Analytics(withGtm(), listed); - new Analytics(withGtm(), listed).start(); + analytics.start(); + analytics.loadScripts(); expect(page.scripts.map((script) => script.src)).to.deep.equal([GTM_SCRIPT, SETUP, WIDGET]); }); @@ -684,9 +719,13 @@ describe('Analytics', () => { ] as const) { it(`reloads the page for a start with ${change}, as a config save under portal serve makes`, () => { const page = browser(quickstart); - new Analytics(none, listed).start(); + const first = new Analytics(none, listed); + first.start(); + first.loadScripts(); + const saved = new Analytics(none, [...next]); - new Analytics(none, [...next]).start(); + saved.start(); + saved.loadScripts(); expect(page.reloads()).to.equal(1); expect(page.scripts.map((script) => script.src)).to.deep.equal([SETUP, WIDGET]); @@ -712,7 +751,9 @@ describe('Analytics', () => { return append(script); }; - new Analytics(withGtm(), [{ src: 'https://cdn.example.com/widget.js' }]).start(); + const analytics = new Analytics(withGtm(), [{ src: 'https://cdn.example.com/widget.js' }]); + analytics.start(); + analytics.loadScripts(); expect(atEachInsert).to.deep.equal(['function', 'function']); @@ -837,6 +878,7 @@ describe('Analytics', () => { analytics.start(); analytics.reportPageView(); + analytics.loadScripts(); expect(page.window.apimatic).to.equal(locked); expect(page.scripts.map((script) => script.src)).to.deep.equal([