Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions portal-template/src/components/listed-scripts.tsx
Original file line number Diff line number Diff line change
@@ -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;
}
2 changes: 2 additions & 0 deletions portal-template/src/components/not-found.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -18,6 +19,7 @@ export function NotFound() {
return (
<HomeLayout {...baseOptions()}>
<DefaultNotFound />
<ListedScripts />
</HomeLayout>
);
}
13 changes: 10 additions & 3 deletions portal-template/src/lib/analytics.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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. */
Expand All @@ -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;
Expand Down
17 changes: 11 additions & 6 deletions portal-template/src/routes/$.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -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__');

Expand Down Expand Up @@ -186,12 +187,16 @@ function Page() {
</DocsPage>
);
} else {
content = (
<Suspense>
<Content collection={page.collection} path={page.path} markdownUrl={page.markdownUrl} />
</Suspense>
);
content = <Content collection={page.collection} path={page.path} markdownUrl={page.markdownUrl} />;
}

return <PortalLayout tree={pageTree}>{content}</PortalLayout>;
return (
<PortalLayout tree={pageTree}>
{/* One boundary for every page's content: React hydrates it last, and ListedScripts with it, never before it. */}
<Suspense>
{content}
<ListedScripts />
</Suspense>
</PortalLayout>
);
}
60 changes: 51 additions & 9 deletions test/portal-template/analytics.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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],
Expand All @@ -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]);
});
Expand All @@ -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]);
});
Expand All @@ -618,6 +640,7 @@ describe('Analytics', () => {

analytics.start();
analytics.reportPageView();
analytics.loadScripts();

expect(page.scripts.map((script) => script.src)).to.deep.equal([SETUP]);
});
Expand All @@ -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);
Expand All @@ -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;
});
Expand All @@ -659,20 +690,24 @@ 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]);
});

// 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]);
});
Expand All @@ -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]);
Expand All @@ -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']);

Expand Down Expand Up @@ -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([
Expand Down
Loading