diff --git a/README.md b/README.md index a1bf9676b..8ee8c6b4f 100644 --- a/README.md +++ b/README.md @@ -298,7 +298,7 @@ Generate a static API Documentation Portal. ``` USAGE - $ apimatic portal generate [--zip] [-i ] [-d ] [-f] [-k ] + $ apimatic portal generate [--zip] [--no-analytics] [-i ] [-d ] [-f] [-k ] FLAGS -d, --destination= [default: /portal] path where the portal will be generated. @@ -306,6 +306,7 @@ FLAGS -i, --input= [default: ./] path to the parent directory containing the 'src' directory, which includes API specifications and configuration files. -k, --auth-key= override current authentication state with an authentication key. + --no-analytics leave out the Google Tag Manager and Google Analytics tags set in 'portal.analytics'. --zip write the generated portal as a .zip archive. DESCRIPTION @@ -338,7 +339,7 @@ Preview your API Documentation Portal with live reload. ``` USAGE - $ apimatic portal serve [-p 23513] [-o] [-i ] [-k ] + $ apimatic portal serve [-p 23513] [-o] [--no-analytics] [-i ] [-k ] FLAGS -i, --input= [default: ./] path to the parent directory containing the 'src' directory, which includes API @@ -346,6 +347,7 @@ FLAGS -k, --auth-key= override current authentication state with an authentication key. -o, --open open the portal in the default browser. -p, --port=23513 [default: 23513] port to serve the portal on. + --no-analytics leave out the Google Tag Manager and Google Analytics tags set in 'portal.analytics'. DESCRIPTION Preview your API Documentation Portal with live reload. diff --git a/apimatic.schema.json b/apimatic.schema.json index f3dae7b92..78ea007da 100644 --- a/apimatic.schema.json +++ b/apimatic.schema.json @@ -177,6 +177,79 @@ } } }, + "analytics": { + "type": "object", + "description": "Analytics the portal loads. Every page view goes to window.dataLayer as docs_page_view, and to GA4 when a measurement ID is set.", + "additionalProperties": false, + "properties": { + "googleTagManager": { + "type": "object", + "additionalProperties": false, + "required": ["containerId"], + "properties": { + "containerId": { + "allOf": [ + { + "$ref": "#/definitions/nonBlank" + } + ], + "description": "The container's ID, for example 'GTM-ABC123'." + }, + "environment": { + "type": "object", + "description": "A GTM environment, for a staging build only, which loads the container's staging version: the gtm_auth and gtm_preview values from the environment's snippet. Both are public in the built portal, so a production portal sets none.", + "additionalProperties": false, + "required": ["auth", "preview"], + "properties": { + "auth": { + "$ref": "#/definitions/nonBlank" + }, + "preview": { + "$ref": "#/definitions/nonBlank" + } + } + } + } + }, + "googleAnalytics": { + "type": "object", + "additionalProperties": false, + "required": ["measurementId"], + "properties": { + "measurementId": { + "allOf": [ + { + "$ref": "#/definitions/nonBlank" + } + ], + "description": "The GA4 web stream's measurement ID, for example 'G-ABC123'. The portal sends its own page views, so turn off the stream's 'Page changes based on browser history events'. Don't also add a GA4 tag to the GTM container: every hit would count twice." + } + } + }, + "keepQueryParams": { + "type": "array", + "description": "Your own link tags to keep in reported page addresses. Campaign (utm_), ad-click and cross-domain tags are kept already; every other query parameter is dropped.", + "items": { + "$ref": "#/definitions/nonBlank" + } + } + } + }, + "seo": { + "type": "object", + "description": "Search engine settings.", + "additionalProperties": false, + "properties": { + "googleSiteVerification": { + "allOf": [ + { + "$ref": "#/definitions/nonBlank" + } + ], + "description": "The content value of Google's site verification meta tag, for Search Console. Not needed for a Domain property verified by DNS." + } + } + }, "pluginUrl": { "type": "string", "description": "Where the context plugin is hosted, starting with 'https://' and with no spaces. The Context Plugin page installs it from here, and the portal carries no copy of its own.", diff --git a/portal-pages/sdk.mdx b/portal-pages/sdk.mdx index b6f558c3b..5792c0a6a 100644 --- a/portal-pages/sdk.mdx +++ b/portal-pages/sdk.mdx @@ -3,6 +3,6 @@ title: "{{name}} SDK" description: "Install and start using the {{name}} SDK." --- - + {{docs}} diff --git a/portal-template/src/components/api-markdown.tsx b/portal-template/src/components/api-markdown.tsx index 884582c22..e3e26b206 100644 --- a/portal-template/src/components/api-markdown.tsx +++ b/portal-template/src/components/api-markdown.tsx @@ -1,10 +1,10 @@ import { createMarkdownRenderer } from 'fumadocs-core/content/md'; import { remarkGfm } from 'fumadocs-core/mdx-plugins/remark-gfm'; -import { DynamicCodeBlock } from 'fumadocs-ui/components/dynamic-codeblock'; import defaultMdxComponents from 'fumadocs-ui/mdx'; import { Children, type ComponentProps, type ReactElement } from 'react'; import { withBasePath } from '@/lib/base-path'; import { languageOf } from '@/lib/code-titles'; +import { ReportedCodeBlock } from './code-copy'; const { Markdown } = createMarkdownRenderer({ remarkPlugins: [remarkGfm] }); @@ -28,5 +28,5 @@ function CodeBlock({ children }: ComponentProps<'pre'>) { const text = code.props.children; if (typeof text !== 'string') return null; const language = languageOf(code.props.className?.split(' ') ?? []) ?? 'text'; - return ; + return ; } diff --git a/portal-template/src/components/api-page.tsx b/portal-template/src/components/api-page.tsx index 219e28517..6b135aabe 100644 --- a/portal-template/src/components/api-page.tsx +++ b/portal-template/src/components/api-page.tsx @@ -1,18 +1,34 @@ +import { lazy, Suspense } from 'react'; import { createOpenAPIPage } from 'fumadocs-openapi/ui'; import { withBasePath } from '@/lib/base-path'; import { mediaAdapters } from '@/lib/media-adapters'; import { oauthCallbackPath } from '@/lib/oauth-callback'; +import { REPLAY_MARKERS } from '@/lib/replay-markers'; import { ApiMarkdown } from './api-markdown'; +import { ReportedCodeBlock } from './code-copy'; +import { EndpointBar } from './endpoint-bar'; import { renderExampleLayout } from './example-layout'; import { codeUsages, renderUsageTabs } from './usage-tabs'; +// Its own chunk, as Fumadocs loads it: the playground's forms are not in every page's bundle. +const Playground = lazy(() => import('./playground')); + export const OpenAPIPage = createOpenAPIPage({ codeUsages, generateTypeScriptDefinitions: false, content: { renderAPIExampleLayout: renderExampleLayout, renderAPIExampleUsageTabs: renderUsageTabs }, - components: { Markdown: ApiMarkdown }, + components: { Markdown: ApiMarkdown, CodeBlock: ReportedCodeBlock }, mediaAdapters, oauthRedirectUrl: withBasePath(oauthCallbackPath), + playground: { + render: ({ method, path }) => ( +
+ }> + + +
+ ) + }, // Portals under paths of one host keep their playground's saved values apart; at the root the keys stay Fumadocs' own. storageKeyPrefix: `fumadocs-openapi-${withBasePath('/').slice(1)}` }); diff --git a/portal-template/src/components/code-copy.tsx b/portal-template/src/components/code-copy.tsx new file mode 100644 index 000000000..4414d5388 --- /dev/null +++ b/portal-template/src/components/code-copy.tsx @@ -0,0 +1,34 @@ +import type { CodeBlockProps as BlockProps } from 'fumadocs-ui/components/codeblock'; +import { DynamicCodeBlock } from 'fumadocs-ui/components/dynamic-codeblock'; +import type { CodeBlockProps } from 'fumadocs-openapi'; +import { languageId } from '@/lib/languages'; +import { analytics } from '@/lib/portal-analytics'; + +type Actions = NonNullable; + +export const reportCodeCopy = (language: string) => + analytics.report('docs_code_copy', { language: languageId(language) }); + +// Fumadocs' own, which any Actions a block is given replaces. +const DefaultActions: Actions = ({ className, children }) => ( +
{children}
+); + +/** A block's Actions slot, which Fumadocs hands the copy button: a click on it calls `onCopy`. */ +export function reportCopies(onCopy: () => void, Actions: Actions = DefaultActions): Actions { + return ({ className, children }) => + Actions({ + className, + children: children && ( + + {children} + + ) + }); +} + +/** Fumadocs' highlighted block, as the API reference renders each, reporting its copies with its language. */ +export function ReportedCodeBlock({ codeblock, ...props }: CodeBlockProps) { + const Actions = reportCopies(() => reportCodeCopy(props.lang), codeblock?.Actions); + return ; +} diff --git a/portal-template/src/components/command-block.tsx b/portal-template/src/components/command-block.tsx index 4d0c8454b..19b54ddf6 100644 --- a/portal-template/src/components/command-block.tsx +++ b/portal-template/src/components/command-block.tsx @@ -2,11 +2,14 @@ import type { ReactNode } from 'react'; import { asMarkdown } from 'fumadocs-core/server'; import { CodeBlock, Pre } from 'fumadocs-ui/components/codeblock'; import { CODE_BLOCK_TITLES } from '@/lib/code-titles'; +import { reportCodeCopy, reportCopies } from './code-copy'; interface CommandBlockProps { command: string; /** One line that truncates, for a card; the full command is still what the button copies. */ compact?: boolean; + /** Called as the copy button is clicked; a copy of a shell command otherwise. */ + onCopy?: () => void; } // Centred on the one line, where the block's own placement pins the button to the top corner. @@ -15,13 +18,15 @@ function CentredActions({ children }: Readonly<{ children?: ReactNode }>) { } /** One shell command in a copyable block: an MDX page has no highlighter to hand, so it is plain. */ -export function CommandBlock({ command, compact = false }: Readonly) { +const reportShellCopy = () => reportCodeCopy('shellscript'); + +export function CommandBlock({ command, compact = false, onCopy = reportShellCopy }: Readonly) { if (asMarkdown()) { return `\`\`\`bash\n${command}\n\`\`\``; } if (!compact) { return ( - +
           
             {/* A highlighted block's lines carry this class, which is what the block pads. */}
@@ -35,7 +40,7 @@ export function CommandBlock({ command, compact = false }: Readonly
       
         
diff --git a/portal-template/src/components/endpoint-bar.tsx b/portal-template/src/components/endpoint-bar.tsx
new file mode 100644
index 000000000..85890ea2a
--- /dev/null
+++ b/portal-template/src/components/endpoint-bar.tsx
@@ -0,0 +1,35 @@
+const METHOD_COLORS: Record = {
+  PUT: 'text-yellow-600 dark:text-yellow-400',
+  PATCH: 'text-orange-600 dark:text-orange-400',
+  POST: 'text-blue-600 dark:text-blue-400',
+  DELETE: 'text-red-600 dark:text-red-400'
+};
+
+/** Fumadocs' endpoint bar, which it shows while the playground loads but does not export: the method and the route. */
+export function EndpointBar({ method, route }: Readonly<{ method: string; route: string }>) {
+  const verb = method.toUpperCase();
+  return (
+    
+ + {verb} + +
+ {route.split(/(\{[^}]*\}|\/)/).map((part, index) => { + if (index % 2 === 0) return part; + if (part === '/') { + return ( + + / + + ); + } + return ( + + {part} + + ); + })} +
+
+ ); +} diff --git a/portal-template/src/components/example-layout.tsx b/portal-template/src/components/example-layout.tsx index 8c904800d..aa3c0a310 100644 --- a/portal-template/src/components/example-layout.tsx +++ b/portal-template/src/components/example-layout.tsx @@ -1,9 +1,10 @@ -import { createContext, useContext, useMemo, useState, type ReactNode } from 'react'; +import { createContext, useContext, useMemo, useState, type MouseEvent, type ReactNode } from 'react'; import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@fumadocs/api-docs/components/select'; import { useOpenAPI } from 'fumadocs-openapi'; import { useExampleRequests, useOperation } from 'fumadocs-openapi/operation'; import { CodeSample } from '@/lib/code-samples'; import { Parameter, requestExamples, type RequestExample } from '@/lib/request-examples'; +import { reportCodeCopy } from './code-copy'; interface ExampleSelection { operation: unknown; @@ -20,6 +21,11 @@ interface LayoutSlots { const SelectionContext = createContext(undefined); +// "Example Response" copies through a button of Fumadocs' own in the card's header, which takes no callback. +const reportResponseCopy = (event: MouseEvent) => { + if (event.target instanceof Element && event.target.closest('button[aria-live]') !== null) reportCodeCopy('json'); +}; + export function useExampleSelection(): ExampleSelection { const selection = useContext(SelectionContext); if (selection === undefined) throw new Error('useExampleSelection needs an ExampleLayout above it'); @@ -63,7 +69,9 @@ function ExampleLayout({ selector, usageTabs, responseTabs }: Readonly {selector === null ? null : } {usageTabs} - {responseTabs} +
+ {responseTabs} +
); diff --git a/portal-template/src/components/markdown-copy-button.tsx b/portal-template/src/components/markdown-copy-button.tsx index ed4ea43eb..2064b733b 100644 --- a/portal-template/src/components/markdown-copy-button.tsx +++ b/portal-template/src/components/markdown-copy-button.tsx @@ -2,6 +2,7 @@ import { useEffect, useState } from 'react'; import { buttonVariants } from 'fumadocs-ui/components/ui/button'; import { Check, Copy, X } from 'lucide-react'; import { copyMarkdown } from '@/lib/copy-markdown'; +import { analytics } from '@/lib/portal-analytics'; type CopyState = 'idle' | 'copying' | 'copied' | 'failed'; @@ -24,7 +25,10 @@ export function MarkdownCopyButton({ markdownUrl }: Readonly<{ markdownUrl: stri const copy = () => { setState('copying'); copyMarkdown(markdownUrl).then( - () => setState('copied'), + () => { + setState('copied'); + analytics.report('docs_markdown_copy', {}); + }, (error: unknown) => { console.error(error); setState('failed'); diff --git a/portal-template/src/components/mdx.tsx b/portal-template/src/components/mdx.tsx index 8661f5e65..cbd8b5b88 100644 --- a/portal-template/src/components/mdx.tsx +++ b/portal-template/src/components/mdx.tsx @@ -1,10 +1,13 @@ +import type { HTMLAttributes } from 'react'; import defaultMdxComponents from 'fumadocs-ui/mdx'; import { Accordion, Accordions } from 'fumadocs-ui/components/accordion'; +import { CodeBlock, Pre } from 'fumadocs-ui/components/codeblock'; import { File, Files, Folder } from 'fumadocs-ui/components/files'; import { InlineTOC } from 'fumadocs-ui/components/inline-toc'; import { Step, Steps } from 'fumadocs-ui/components/steps'; import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; import { TypeTable } from 'fumadocs-ui/components/type-table'; +import { reportCodeCopy, reportCopies } from './code-copy'; import { PluginInstall } from './plugin-install'; import { PluginLanguage, PluginLanguages, PluginPlatforms } from './plugin-support'; import { SdkActions } from './sdk-actions'; @@ -12,9 +15,17 @@ import { SdkCard, SdkCards } from './sdk-cards'; type MDXComponents = Record; +type HighlightedPre = HTMLAttributes & { 'data-language'?: string }; + export function getMDXComponents(components?: MDXComponents) { return { ...defaultMdxComponents, + // Fumadocs' own, its copy button reporting the language the build names on the block. + pre: ({ 'data-language': language = 'plaintext', ...props }: HighlightedPre) => ( + reportCodeCopy(language))}> +
{props.children}
+
+ ), // Fumadocs' components beyond its defaults, so an author's page can use them without importing. Accordion, Accordions, diff --git a/portal-template/src/components/not-found.tsx b/portal-template/src/components/not-found.tsx index 375aacb7e..3eba7d789 100644 --- a/portal-template/src/components/not-found.tsx +++ b/portal-template/src/components/not-found.tsx @@ -1,8 +1,20 @@ +import { useEffect } from 'react'; +import { useRouterState } from '@tanstack/react-router'; 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'; export function NotFound() { + // The path the router has settled on: its location alone already names the page a reader is leaving this one for. + const settled = useRouterState({ + select: ({ location, resolvedLocation }) => + resolvedLocation?.pathname === location.pathname ? location.pathname : null + }); + // Keyed on the path: the same component shows the next missing page too. + useEffect(() => { + if (settled !== null) analytics.reportNotFound(); + }, [settled]); return ( diff --git a/portal-template/src/components/playground.tsx b/portal-template/src/components/playground.tsx new file mode 100644 index 000000000..0908ea9ae --- /dev/null +++ b/portal-template/src/components/playground.tsx @@ -0,0 +1,49 @@ +import { createContext, use, useEffect, useMemo, useRef, type RefObject } from 'react'; +import { useOperation } from 'fumadocs-openapi/operation'; +import type { FetchResult } from 'fumadocs-openapi/playground'; +import PlaygroundClient, { DefaultResultDisplay, type ResultDisplayProps } from 'fumadocs-openapi/ui/playground/client'; +import { apiRequest } from '@/lib/api-request'; +import { analytics } from '@/lib/portal-analytics'; + +/** When this playground last sent a request, for a result that has no duration of its own. */ +const SentAt = createContext>({ current: null }); + +// The display mounts again with the same result on each reopen, and twice in a dev build. +const reported = new WeakSet(); + +function ResultDisplay(props: ResultDisplayProps) { + const { method, path } = useOperation(); + const sentAt = use(SentAt); + useEffect(() => { + if (reported.has(props.data)) return; + reported.add(props.data); + const endpoint = `${method.toUpperCase()} ${path}`; + analytics.report('docs_api_request', apiRequest(endpoint, props.data, sentAt.current, Date.now())); + sentAt.current = null; + }, [method, path, props.data, sentAt]); + return ; +} + +const components = { ResultDisplay }; + +/** The playground with the reporting around it, in the one chunk the API page loads lazily. */ +export default function Playground() { + const sentAt = useRef(null); + // Fumadocs' request has no callback of its own: the time is noted here, and the request goes on unchanged. + const fetchOptions = useMemo( + () => ({ + onRequestInit: (requestInit: RequestInit) => { + sentAt.current = Date.now(); + return requestInit; + } + }), + [] + ); + // Fumadocs takes a returned sign-in's answer out of the address in the effects of the playground below this one. + useEffect(() => analytics.loadTags(), []); + return ( + + + + ); +} diff --git a/portal-template/src/components/plugin-install.tsx b/portal-template/src/components/plugin-install.tsx index 9c810b52f..2ecc911c1 100644 --- a/portal-template/src/components/plugin-install.tsx +++ b/portal-template/src/components/plugin-install.tsx @@ -3,11 +3,14 @@ import { asMarkdown } from 'fumadocs-core/server'; import { CommandBlock } from './command-block'; import { fullAddress } from '@/lib/base-path'; import { installCommand } from '@/lib/install-command'; +import { analytics } from '@/lib/portal-analytics'; import { portal } from '@/lib/portal'; // The address never changes while the page is open, so there is nothing to subscribe to. const noSubscribe = () => () => {}; +const reportInstall = () => analytics.report('docs_plugin_install', {}); + /** The prerender cannot know where the portal is hosted, so the browser swaps in its own address. */ export function PluginInstall({ path }: Readonly<{ path: string }>) { // Ahead of the hook, which only React may call; either branch is taken in every render of one environment. @@ -19,5 +22,5 @@ export function PluginInstall({ path }: Readonly<{ path: string }>) { () => fullAddress('/'), () => portal.siteUrl ); - return ; + return ; } diff --git a/portal-template/src/components/sdk-actions.tsx b/portal-template/src/components/sdk-actions.tsx index 4c90cfb18..541e21229 100644 --- a/portal-template/src/components/sdk-actions.tsx +++ b/portal-template/src/components/sdk-actions.tsx @@ -3,8 +3,11 @@ import { asMarkdown } from 'fumadocs-core/server'; import { buttonVariants } from 'fumadocs-ui/components/ui/button'; import { Code, Download, Package } from 'lucide-react'; import { withBasePath } from '@/lib/base-path'; +import { languageId } from '@/lib/languages'; +import { analytics } from '@/lib/portal-analytics'; export interface SdkActionsProps { + language: string; download: string; /** Empty when no source repository is recorded. */ source: string; @@ -19,7 +22,7 @@ export const LINK = export const QUIET_LINK = `${LINK} text-fd-muted-foreground hover:text-fd-foreground`; /** Download, View source and View package: each shown only when there is something behind it. */ -export function SdkActions({ download, source, packageUrl, registry }: Readonly) { +export function SdkActions({ language, download, source, packageUrl, registry }: Readonly) { // The page's Markdown twin, which the page actions and llms-full.txt hand to an AI assistant. if (asMarkdown()) { const links = [ @@ -35,6 +38,7 @@ export function SdkActions({ download, source, packageUrl, registry }: Readonly<
@@ -62,10 +66,19 @@ interface LinkProps { children: ReactNode; } +interface DownloadLinkProps extends LinkProps { + language: string; +} + /** A plain link, not a route: the zip is a file the site serves beside its pages. */ -export function DownloadLink({ href, className, children }: Readonly) { +export function DownloadLink({ href, className, language, children }: Readonly) { return ( - + analytics.report('docs_sdk_download', { language: languageId(language) })} + > {children} ); diff --git a/portal-template/src/components/sdk-cards.tsx b/portal-template/src/components/sdk-cards.tsx index fda88b91e..b79013469 100644 --- a/portal-template/src/components/sdk-cards.tsx +++ b/portal-template/src/components/sdk-cards.tsx @@ -8,7 +8,6 @@ import { LanguageLogo, LogoTile } from './logos'; import { DownloadLink, ExternalLink, LINK, QUIET_LINK, SdkActions, type SdkActionsProps } from './sdk-actions'; interface SdkCardProps extends SdkActionsProps { - language: string; name: string; /** The language's own page. */ page: string; @@ -41,7 +40,10 @@ function LinkContext({ name }: Readonly<{ name: string }>) { export function SdkCard({ language, name, page, install, ...actions }: Readonly) { if (asMarkdown()) { const command = install ? `\`${install}\` · ` : ''; - return [`- [${name}](${withBasePath(page)}): ${command}`, ]; + return [ + `- [${name}](${withBasePath(page)}): ${command}`, + + ]; } const { download, source, packageUrl, registry } = actions; return ( @@ -57,7 +59,7 @@ export function SdkCard({ language, name, page, install, ...actions }: Readonly< {install ? ( ) : ( - + Download SDK @@ -65,7 +67,7 @@ export function SdkCard({ language, name, page, install, ...actions }: Readonly< )}
{install ? ( - + Download SDK diff --git a/portal-template/src/components/search.tsx b/portal-template/src/components/search.tsx index 8180d4108..db1450481 100644 --- a/portal-template/src/components/search.tsx +++ b/portal-template/src/components/search.tsx @@ -8,13 +8,16 @@ import { SearchDialogInput, SearchDialogList, SearchDialogOverlay, + type SearchItemType, type SharedProps } from 'fumadocs-ui/components/dialog/search'; import { useDocsSearch } from 'fumadocs-core/search/client'; import { staticClient } from 'fumadocs-core/search/client/orama-static'; import { useI18n } from 'fumadocs-ui/contexts/i18n'; -import { useMemo } from 'react'; +import { useEffect, useMemo, useRef } from 'react'; import { withBasePath } from '@/lib/base-path'; +import { analytics } from '@/lib/portal-analytics'; +import { searchOutcome } from '@/lib/search-report'; export default function DefaultSearchDialog(props: SharedProps) { const { locale } = useI18n(); @@ -32,8 +35,52 @@ export default function DefaultSearchDialog(props: SharedProps) { [query.data] ); + const typed = useRef(false); + const picked = useRef(''); + const openedAt = useRef(''); + const wasOpen = useRef(false); + + // The page the search is made on: a pick changes the address before the dialog reports its close. + useEffect(() => { + if (!props.open) return; + wasOpen.current = true; + openedAt.current = window.location.href; + }, [props.open]); + + // A close is seen from the prop, which the hotkey changes too. + useEffect(() => { + if (!wasOpen.current) return; + const outcome = searchOutcome({ + open: props.open, + loading: query.isLoading, + typed: typed.current, + picked: picked.current, + term: search, + resultCount: results?.length ?? 0 + }); + if (!outcome.ended) return; + wasOpen.current = false; + typed.current = false; + picked.current = ''; + if (outcome.report !== null) analytics.report('docs_search', outcome.report, openedAt.current); + }, [props.open, query.isLoading, search, results]); + + const onSearchChange = (value: string) => { + typed.current = true; + setSearch(value); + }; + const onSelect = (item: SearchItemType) => { + picked.current = 'url' in item ? new URL(item.url, window.location.href).href : ''; + }; + return ( - + diff --git a/portal-template/src/components/usage-tabs.tsx b/portal-template/src/components/usage-tabs.tsx index a5e59fcf5..43cb1d7ba 100644 --- a/portal-template/src/components/usage-tabs.tsx +++ b/portal-template/src/components/usage-tabs.tsx @@ -5,6 +5,7 @@ import { useCodeUsage } from 'fumadocs-openapi/operation'; import { createCodeUsageGeneratorRegistry } from 'fumadocs-openapi/requests/generators'; import { curl } from 'fumadocs-openapi/requests/generators/curl'; import { CodeSample } from '@/lib/code-samples'; +import { REPLAY_MARKERS } from '@/lib/replay-markers'; import { useExampleSelection } from './example-layout'; interface UsageTab { @@ -64,9 +65,13 @@ function SampleCode({ sample }: Readonly<{ sample: CodeSample }>) { return ; } -// Follows the playground's edits to the selected example, on the selected server. +// Follows the playground's edits, typed credentials included, so it carries the playground's replay markers. function CurlCode() { const { CodeBlock } = useComponents(); const code = useCodeUsage(CURL_USAGE_ID); - return code === undefined ? null : ; + return code === undefined ? null : ( +
+ +
+ ); } diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts new file mode 100644 index 000000000..10e59cffd --- /dev/null +++ b/portal-template/src/lib/analytics.ts @@ -0,0 +1,126 @@ +import { isOAuthCallbackPath } from './oauth-callback'; +import type { PortalAnalytics } from './portal-types'; +import { type Adapter, adapters, insertTags } from './vendor-tags'; + +/** The query parameters an ad or mail platform reads from an address itself; a customer adds names and removes none. */ +const KEPT_PREFIXES = ['utm_', 'hsa_']; +const KEPT_NAMES = new Set([ + '_gl', + 'gclid', + 'gbraid', + 'wbraid', + 'gad_source', + 'dclid', + 'fbclid', + 'msclkid', + 'ttclid', + 'twclid', + 'li_fat_id', + 'mc_cid', + '_hsenc', + '_hsmi' +]); + +/** Customers' GTM triggers match these names, so renaming or removing one breaks them without an error. */ +export interface PortalEvents { + docs_page_view: { page_title: string }; + docs_markdown_copy: Record; + docs_plugin_install: Record; + docs_sdk_download: { language: string }; + docs_code_copy: { language: string }; + docs_search: { search_term: string; result: string; result_count: number }; + docs_not_found: { page_referrer: string }; + /** `status` is always text: the HTTP status in digits, or `client_error` for a request that never reached the API. */ + docs_api_request: { endpoint: string; status: string; duration_ms: number }; +} +export type PortalEventName = keyof PortalEvents; + +type DataLayerEntry = { docs: null } | { event: PortalEventName; docs: Readonly> }; + +declare global { + interface Window { + dataLayer?: unknown[]; + /** Held by the window: a config save under `portal serve` evaluates this module again. */ + portalAnalyticsStarted?: string; + } +} + +/** The address as reported: no `#` part, and no query but the kept tags. */ +export function pageLocation(href: string, keep: readonly string[]): string { + const url = new URL(href); + url.search = new URLSearchParams( + [...url.searchParams].filter( + ([name]) => KEPT_PREFIXES.some((prefix) => name.startsWith(prefix)) || KEPT_NAMES.has(name) || keep.includes(name) + ) + ).toString(); + url.hash = ''; + return url.href; +} + +export class Analytics { + private readonly live: Adapter[]; + private lastPageView: string | null = null; + private previousPageView: string | null = null; + private lastNotFound: string | null = null; + + public constructor(private readonly settings: PortalAnalytics) { + this.live = Object.values(adapters) + .map((build) => build(settings)) + .filter((adapter) => adapter !== null); + } + + public start(): void { + const settings = JSON.stringify(this.settings); + if (window.portalAnalyticsStarted === settings) return; + // Other vendors after a config save: only a fresh page holds exactly their tags. + if (window.portalAnalyticsStarted !== undefined) { + window.location.reload(); + return; + } + window.portalAnalyticsStarted = settings; + const dataLayer = (window.dataLayer ??= []); + for (const adapter of this.live) adapter.setup(dataLayer); + insertTags(this.live); + } + + /** The tags held back while the address held an OAuth answer, once something has taken it out. */ + public loadTags(): void { + insertTags(this.live); + } + + /** `href` is the page the event belongs to, when the caller saw the address move on first. */ + public report(name: E, params: PortalEvents[E], href = window.location.href): void { + if (isOAuthCallbackPath(new URL(href).pathname)) return; + const docs = { ...params, page_location: pageLocation(href, this.settings.keepQueryParams) }; + const dataLayer = (window.dataLayer ??= []); + // GTM merges every push into what it holds, so a tag would send the last event's details without this. + dataLayer.push({ docs: null } satisfies DataLayerEntry); + dataLayer.push({ event: name, docs } satisfies DataLayerEntry); + for (const adapter of this.live) adapter.send?.(name, docs); + } + + public reportPageView(): void { + if (isOAuthCallbackPath(window.location.pathname)) return; + this.loadTags(); + const page = pageLocation(window.location.href, this.settings.keepQueryParams); + if (page === this.lastPageView) return; + this.previousPageView = this.lastPageView; + this.lastPageView = page; + if (this.lastNotFound !== page) this.lastNotFound = null; + this.report('docs_page_view', { page_title: document.title }); + } + + public reportNotFound(): void { + const page = pageLocation(window.location.href, this.settings.keepQueryParams); + if (page === this.lastNotFound) return; + this.lastNotFound = page; + const referrer = document.referrer === '' ? null : new URL(document.referrer); + if (referrer !== null) { + referrer.search = ''; + referrer.hash = ''; + } + // The missing page's own view may be reported before this or after it. + const left = this.lastPageView === page ? this.previousPageView : this.lastPageView; + this.report('docs_not_found', { page_referrer: left ?? referrer?.href ?? '' }); + } +} diff --git a/portal-template/src/lib/api-request.ts b/portal-template/src/lib/api-request.ts new file mode 100644 index 000000000..19db41dc4 --- /dev/null +++ b/portal-template/src/lib/api-request.ts @@ -0,0 +1,15 @@ +import type { FetchResult } from 'fumadocs-openapi/playground'; +import type { PortalEvents } from './analytics'; + +/** A playground result as `docs_api_request` reports it; a request that never reached the API is timed from `sentAt`. */ +export function apiRequest( + endpoint: string, + result: FetchResult, + sentAt: number | null, + now: number +): PortalEvents['docs_api_request'] { + if (result.type === 'response') { + return { endpoint, status: String(result.status), duration_ms: Math.round(result.duration) }; + } + return { endpoint, status: 'client_error', duration_ms: sentAt === null ? 0 : now - sentAt }; +} diff --git a/portal-template/src/lib/code-titles.ts b/portal-template/src/lib/code-titles.ts index 6d6cdbca6..73005bf35 100644 --- a/portal-template/src/lib/code-titles.ts +++ b/portal-template/src/lib/code-titles.ts @@ -1,5 +1,4 @@ -// A type alone, so a page naming a title does not load the highlighter the bundle builds. -import type { BundledLanguage } from './shiki-bundle'; +import type { BundledLanguage } from './languages'; /** What a code block's header calls its language; a shell is named for where the command runs. */ export const CODE_BLOCK_TITLES: Readonly> = { diff --git a/portal-template/src/lib/languages.ts b/portal-template/src/lib/languages.ts new file mode 100644 index 000000000..0d1865c4e --- /dev/null +++ b/portal-template/src/lib/languages.ts @@ -0,0 +1,99 @@ +/** The languages the portal highlights, by Shiki's IDs; apart from `shiki-bundle.ts`, so naming one loads no grammar. */ +export const BUNDLED_LANGUAGES = [ + // The seven the CLI generates SDKs for (src/types/sdk/generate.ts). + 'csharp', + 'go', + 'java', + 'php', + 'python', + 'ruby', + 'typescript', + + // Shell commands, and the shapes a response or a specification is shown in. + 'http', + 'json', + 'jsonc', + 'shellscript', + 'shellsession', + 'xml', + 'yaml', + + // What the Markdown pages beside the reference are written in. + 'css', + 'diff', + 'graphql', + 'html', + 'javascript', + 'jsx', + 'markdown', + 'sql', + 'tsx' +] as const; + +export type BundledLanguage = (typeof BUNDLED_LANGUAGES)[number]; + +/** Shiki's aliases, which a hand-built bundle lacks; `test/portal-template.test.ts` holds them to Shiki's own. */ +export const languageAliases: Readonly> = { + 'c#': 'csharp', + cs: 'csharp', + py: 'python', + rb: 'ruby', + ts: 'typescript', + cts: 'typescript', + mts: 'typescript', + js: 'javascript', + cjs: 'javascript', + mjs: 'javascript', + bash: 'shellscript', + sh: 'shellscript', + shell: 'shellscript', + zsh: 'shellscript', + console: 'shellsession', + yml: 'yaml', + md: 'markdown', + gql: 'graphql' +}; + +/** The grammar a fence's language names, by its own name or an alias; null for one not bundled. */ +export function bundledLanguage(name: string): BundledLanguage | null { + if ((BUNDLED_LANGUAGES as readonly string[]).includes(name)) { + return name as BundledLanguage; + } + return Object.hasOwn(languageAliases, name) ? languageAliases[name] : null; +} + +/** Short names of languages outside the bundle, by Shiki's ID: for reports only, so one language is one value. */ +export const reportedAliases: Readonly> = { + kt: 'kotlin', + kts: 'kotlin', + rs: 'rust', + 'c++': 'cpp', + objc: 'objective-c', + 'f#': 'fsharp', + fs: 'fsharp', + hs: 'haskell', + clj: 'clojure', + erl: 'erlang', + jl: 'julia', + ps: 'powershell', + ps1: 'powershell', + pwsh: 'powershell', + batch: 'bat', + cmd: 'bat', + dockerfile: 'docker', + makefile: 'make', + tf: 'terraform', + tfvars: 'terraform', + protobuf: 'proto', + properties: 'ini', + // Shiki's other names for a block in no language, which a page's own blocks report as `plaintext`. + text: 'plaintext', + txt: 'plaintext', + plain: 'plaintext' +}; + +/** A language as the portal reports it: its ID for any name it goes by, bundled or not, else the name in lowercase. */ +export function languageId(name: string): string { + const lowered = name.toLowerCase(); + return bundledLanguage(lowered) ?? (Object.hasOwn(reportedAliases, lowered) ? reportedAliases[lowered] : lowered); +} diff --git a/portal-template/src/lib/oauth-callback.ts b/portal-template/src/lib/oauth-callback.ts index cf8cf74df..ad878ec7a 100644 --- a/portal-template/src/lib/oauth-callback.ts +++ b/portal-template/src/lib/oauth-callback.ts @@ -1,3 +1,5 @@ +import { withBasePath } from './base-path'; + /** * The one redirect URI a portal owner registers with their OAuth provider, instead of the * address of every endpoint page that can start an authorization. The CLI keeps the user's @@ -5,6 +7,21 @@ */ export const oauthCallbackPath = '/oauth/callback'; +/** Whether a path is the callback's under `base`, Vite's own unless one is given; a static host may add a slash. */ +export function isOAuthCallbackPath(pathname: string, base?: string): boolean { + return pathname.replace(/\/$/, '') === withBasePath(oauthCallbackPath, base); +} + +/** The callback's address always holds a provider's answer; a page a sign-in returned to does until the playground reads it. */ +export function holdsOAuthAnswer({ pathname, search, hash }: Pick): boolean { + // Fumadocs sends a `state` with every authorization, and the answer carries it back in the query or the `#` part. + return ( + isOAuthCallbackPath(pathname) || + new URLSearchParams(search).has('state') || + new URLSearchParams(hash.slice(1)).has('state') + ); +} + /** Where the playground notes the path of the page that started the flow before it leaves: this tab's session storage. */ const STARTING_PAGE_KEY = 'fumadocs-openapi-oauth'; diff --git a/portal-template/src/lib/portal-analytics.ts b/portal-template/src/lib/portal-analytics.ts new file mode 100644 index 000000000..d23527eb9 --- /dev/null +++ b/portal-template/src/lib/portal-analytics.ts @@ -0,0 +1,10 @@ +import { Analytics } from './analytics'; +import { portal } from './portal'; +import { markPlaygroundDialogs } from './replay-markers'; + +export const analytics = new Analytics(portal.analytics); +// When the bundle starts, before React and before any vendor tag. Never during prerendering. +if (typeof window !== 'undefined') { + markPlaygroundDialogs(); + analytics.start(); +} diff --git a/portal-template/src/lib/portal-types.ts b/portal-template/src/lib/portal-types.ts index 8762b2eb2..cbc8cc0e1 100644 --- a/portal-template/src/lib/portal-types.ts +++ b/portal-template/src/lib/portal-types.ts @@ -22,6 +22,32 @@ export interface PortalFavicon { type: string | null; } +export interface GoogleTagManagerEnvironment { + auth: string; + preview: string; +} + +export interface GoogleTagManagerSetting { + containerId: string; + environment: GoogleTagManagerEnvironment | null; +} + +export interface GoogleAnalyticsSetting { + measurementId: string; +} + +/** Public values: they sit in every page's scripts. */ +export interface PortalAnalytics { + googleTagManager: GoogleTagManagerSetting | null; + googleAnalytics: GoogleAnalyticsSetting | null; + keepQueryParams: string[]; +} + +export interface PortalSeo { + /** The content value of Google's site verification meta tag, for Search Console. */ + googleSiteVerification: string | null; +} + export interface Portal { name: string; description: string | null; @@ -33,4 +59,6 @@ export interface Portal { links: PortalLink[]; /** Whether each page offers to open itself in an external AI assistant. */ pageActions: boolean; + analytics: PortalAnalytics; + seo: PortalSeo; } diff --git a/portal-template/src/lib/rehype-code-titles.ts b/portal-template/src/lib/rehype-code-titles.ts index e563fe269..01fd1ec13 100644 --- a/portal-template/src/lib/rehype-code-titles.ts +++ b/portal-template/src/lib/rehype-code-titles.ts @@ -1,6 +1,6 @@ import { parseCodeBlockAttributes } from 'fumadocs-core/mdx-plugins/codeblock-utils'; import { CODE_BLOCK_TITLES, languageOf } from './code-titles'; -import { bundledLanguage } from './shiki-bundle'; +import { bundledLanguage } from './languages'; interface HastNode { type: string; diff --git a/portal-template/src/lib/replay-markers.ts b/portal-template/src/lib/replay-markers.ts new file mode 100644 index 000000000..d1ab35424 --- /dev/null +++ b/portal-template/src/lib/replay-markers.ts @@ -0,0 +1,28 @@ +/** The opt-out markers of the session replay tools a GTM tag may load; each keeps its tool out of the element. */ +export const REPLAY_MARKERS = { + className: 'ph-no-capture fs-exclude rr-block amp-block', + 'data-hj-suppress': '', + 'data-clarity-mask': 'True', + 'data-private': '' +} as const; + +function markForReplay(element: Element): void { + element.classList.add(...REPLAY_MARKERS.className.split(' ')); + for (const [name, value] of Object.entries(REPLAY_MARKERS)) { + if (name !== 'className') element.setAttribute(name, value); + } +} + +/** Observers are told in the order they were made, so this one, made before any tag's, marks the dialog first. */ +export function markPlaygroundDialogs(): void { + new MutationObserver((mutations) => { + for (const { addedNodes } of mutations) { + for (const node of addedNodes) { + if (!(node instanceof Element)) continue; + // Told from the search dialog by its request form, until fuma-nama/fumadocs#3824 takes the markers itself. + const dialog = node.matches('[role="dialog"]') ? node : node.querySelector('[role="dialog"]'); + if (dialog !== null && dialog.querySelector('form') !== null) markForReplay(dialog); + } + } + }).observe(document.body, { childList: true, subtree: true }); +} diff --git a/portal-template/src/lib/search-report.ts b/portal-template/src/lib/search-report.ts new file mode 100644 index 000000000..2b347b3ae --- /dev/null +++ b/portal-template/src/lib/search-report.ts @@ -0,0 +1,28 @@ +import { pageLocation, type PortalEvents } from './analytics'; + +/** The search dialog on a render after it opened. */ +export interface SearchDialogState { + open: boolean; + /** The last keystrokes' results are still on their way. */ + loading: boolean; + typed: boolean; + /** The whole address of the result picked, or empty. */ + picked: string; + term: string; + resultCount: number; +} + +export type SearchOutcome = { ended: false } | { ended: true; report: PortalEvents['docs_search'] | null }; + +/** What GA4 keeps of a parameter's value, so no other tag gets more of what a reader pasted into search. */ +const TERM_LIMIT = 100; + +/** A search ends once the dialog has closed with its results in; it reports when the reader typed or picked a term. */ +export function searchOutcome(state: SearchDialogState): SearchOutcome { + if (state.open || state.loading) return { ended: false }; + const search_term = state.term.trim().slice(0, TERM_LIMIT); + const counted = (state.typed || state.picked !== '') && search_term !== ''; + // In the shape of `page_location`, so a report joins the two: a heading hit loses its `#` part. + const result = state.picked === '' ? '' : pageLocation(state.picked, []); + return { ended: true, report: counted ? { search_term, result, result_count: state.resultCount } : null }; +} diff --git a/portal-template/src/lib/shiki-bundle.ts b/portal-template/src/lib/shiki-bundle.ts index 2ab73b5c3..e5e02869a 100644 --- a/portal-template/src/lib/shiki-bundle.ts +++ b/portal-template/src/lib/shiki-bundle.ts @@ -1,5 +1,6 @@ import { createBundledHighlighter } from 'shiki/core'; import { createJavaScriptRegexEngine } from 'shiki/engine/javascript'; +import { languageAliases, type BundledLanguage } from './languages'; // Re-exported untouched: Fumadocs imports it from the `shiki` entry point this file stands // in for, though the bundle itself builds its highlighter on the JavaScript engine. @@ -44,49 +45,12 @@ const languages = { markdown: () => import('shiki/dist/langs/markdown.mjs'), sql: () => import('shiki/dist/langs/sql.mjs'), tsx: () => import('shiki/dist/langs/tsx.mjs') -} satisfies Record; - -/** - * Shiki's own bundle resolves `ts` or `yml` through an alias table beside its grammars; a - * hand-built map has none, so an alias reaches Fumadocs as an unknown language and is replaced - * with `text`. Each shares its grammar's import, as Shiki's `bundledLanguagesAlias` does, so - * the bundler still emits one chunk per language rather than one per spelling. Taken from - * Shiki's `bundledLanguagesInfo`; `test/portal-template.test.ts` holds them to it. - */ -const aliases: Record = { - 'c#': 'csharp', - cs: 'csharp', - py: 'python', - rb: 'ruby', - ts: 'typescript', - cts: 'typescript', - mts: 'typescript', - js: 'javascript', - cjs: 'javascript', - mjs: 'javascript', - bash: 'shellscript', - sh: 'shellscript', - shell: 'shellscript', - zsh: 'shellscript', - console: 'shellsession', - yml: 'yaml', - md: 'markdown', - gql: 'graphql' -}; - -export type BundledLanguage = keyof typeof languages; - -/** The grammar a fence's language names, by its own name or an alias; null for one not bundled. */ -export function bundledLanguage(name: string): BundledLanguage | null { - if (Object.hasOwn(languages, name)) { - return name as BundledLanguage; - } - return Object.hasOwn(aliases, name) ? aliases[name] : null; -} +} satisfies Record; +// Each alias shares its grammar's import, as Shiki's `bundledLanguagesAlias` does: one chunk per language, not per spelling. const bundledLanguages = { ...languages, - ...Object.fromEntries(Object.entries(aliases).map(([alias, id]) => [alias, languages[id]])) + ...Object.fromEntries(Object.entries(languageAliases).map(([alias, id]) => [alias, languages[id]])) } as never; /** The two Fumadocs asks for by default; the rest of Shiki's themes are never requested. */ diff --git a/portal-template/src/lib/source.ts b/portal-template/src/lib/source.ts index f6eae85e3..e239a1405 100644 --- a/portal-template/src/lib/source.ts +++ b/portal-template/src/lib/source.ts @@ -1,9 +1,9 @@ import { defineDocs } from 'fumadocs-mdx/macro'; import { applyMdxPreset } from 'fumadocs-mdx/config'; -import { rehypeCodeDefaultOptions } from 'fumadocs-core/mdx-plugins'; import rehypeRaw from 'rehype-raw'; import { rehypeCodeTitles, rehypeKeepCodeMeta } from './rehype-code-titles'; import { navigationSchema } from './navigation-schema'; +import { rehypeCodeOptions } from './transformer-language'; // What `rehype-raw` must hand on untouched, being MDX's own nodes rather than HTML. const MDX_NODE_TYPES = ['mdxFlowExpression', 'mdxJsxFlowElement', 'mdxJsxTextElement', 'mdxTextExpression', 'mdxjsEsm']; @@ -35,7 +35,7 @@ export const generated = defineDocs({ // A remote image is never fetched for its size, which would make the build depend on its host. remarkImageOptions: { external: false }, // The SDK pages' design heads a block with its title alone, without Fumadocs' language icon. - rehypeCodeOptions: { ...rehypeCodeDefaultOptions, icon: false }, + rehypeCodeOptions: { ...rehypeCodeOptions, icon: false }, // The SDK docs' HTML fails the build unrendered; not sanitized, as it comes from the owner's own spec. // The titles go in after it, and ahead of `rehypeCode`, the first of the defaults, which reads them. rehypePlugins: (defaults) => [ diff --git a/portal-template/src/lib/transformer-language.ts b/portal-template/src/lib/transformer-language.ts new file mode 100644 index 000000000..be12cf340 --- /dev/null +++ b/portal-template/src/lib/transformer-language.ts @@ -0,0 +1,16 @@ +import { rehypeCodeDefaultOptions } from 'fumadocs-core/mdx-plugins'; +import type { ShikiTransformer } from 'shiki'; + +/** Names each highlighted block's language on its `pre`, which the MDX `pre` hands to the block's copy button. */ +export const transformerLanguage: ShikiTransformer = { + name: 'portal:language', + pre(node) { + node.properties['data-language'] = this.options.lang; + } +}; + +/** Fumadocs' code options for every collection, with each block's language named for its copy button. */ +export const rehypeCodeOptions = { + ...rehypeCodeDefaultOptions, + transformers: [...(rehypeCodeDefaultOptions.transformers ?? []), transformerLanguage] +}; diff --git a/portal-template/src/lib/vendor-tags.ts b/portal-template/src/lib/vendor-tags.ts new file mode 100644 index 000000000..76f7922e0 --- /dev/null +++ b/portal-template/src/lib/vendor-tags.ts @@ -0,0 +1,67 @@ +import { holdsOAuthAnswer } from './oauth-callback'; +import type { PortalAnalytics } from './portal-types'; + +type Gtag = (...command: unknown[]) => void; + +declare global { + interface Window { + gtag?: Gtag; + } +} + +export interface Adapter { + setup(dataLayer: unknown[]): void; + script: string; + /** For a vendor that does not read the data layer itself, as GTM does. */ + send?(name: string, params: Record): void; +} + +type Vendor = Exclude; +const GOOGLE = 'https://www.googletagmanager.com'; + +/** Keyed by every vendor `PortalAnalytics` names, so a vendor without an adapter does not compile. */ +export const adapters: { [V in Vendor]: (settings: PortalAnalytics) => Adapter | null } = { + googleTagManager: ({ googleTagManager: setting }) => { + if (setting === null) return null; + const env = setting.environment; + const environment = env + ? `>m_auth=${encodeURIComponent(env.auth)}>m_preview=${encodeURIComponent(env.preview)}>m_cookies_win=x` + : ''; + return { + setup: (dataLayer) => dataLayer.push({ 'gtm.start': Date.now(), event: 'gtm.js' }), + script: `${GOOGLE}/gtm.js?id=${encodeURIComponent(setting.containerId)}${environment}` + }; + }, + googleAnalytics: ({ googleAnalytics: setting }) => { + if (setting === null) return null; + return { + setup: (dataLayer) => { + // gtag.js reads only Arguments objects from the data layer, never an array of the same values. + const gtag = (window.gtag ??= function () { + dataLayer.push(arguments); + }); + gtag('js', new Date()); + gtag('config', setting.measurementId, { send_page_view: false }); + }, + script: `${GOOGLE}/gtag/js?id=${encodeURIComponent(setting.measurementId)}`, + send: (name, params) => { + // GA4's own events, such as a scroll, read this instead of the address, which may hold more. + if (name === 'docs_page_view') window.gtag?.('set', { page_location: params.page_location }); + // The page's gtag, since a second instance under `portal serve` never runs its setup. + window.gtag?.('event', name.replace(/^docs_/, ''), params); + } + }; + } +}; + +/** None while the address holds an OAuth answer, which the tags read for themselves; each once, so a later call adds the rest. */ +export function insertTags(live: Adapter[]): void { + if (holdsOAuthAnswer(window.location)) return; + for (const { script: src } of live) { + if (document.head.querySelector(`script[src="${src}"]`) !== null) continue; + const script = document.createElement('script'); + script.async = true; + script.src = src; + document.head.append(script); + } +} diff --git a/portal-template/src/routes/__root.tsx b/portal-template/src/routes/__root.tsx index ba8d973df..1186941d8 100644 --- a/portal-template/src/routes/__root.tsx +++ b/portal-template/src/routes/__root.tsx @@ -1,5 +1,6 @@ -import { createRootRoute, HeadContent, Outlet, Scripts } from '@tanstack/react-router'; +import { createRootRoute, HeadContent, Outlet, Scripts, useRouter } from '@tanstack/react-router'; import { createServerFn } from '@tanstack/react-start'; +import { useEffect } from 'react'; import { staticFunctionMiddleware } from '@tanstack/start-static-server-functions'; import { source } from '@/lib/source.server'; import appCss from '@/styles/app.css?url'; @@ -7,6 +8,7 @@ import { RootProvider } from 'fumadocs-ui/provider/tanstack'; import SearchDialog from '@/components/search'; import { withBasePath } from '@/lib/base-path'; import { portal } from '@/lib/portal'; +import { analytics } from '@/lib/portal-analytics'; // The sidebar tree is the same on every page. Loaded here, once, it is written to a single // cache file instead of being repeated in every page's own loader payload. @@ -39,7 +41,10 @@ export const Route = createRootRoute({ { charSet: 'utf-8' }, { name: 'viewport', content: 'width=device-width, initial-scale=1' }, { title: portal.name }, - ...(portal.description ? [{ name: 'description', content: portal.description }] : []) + ...(portal.description ? [{ name: 'description', content: portal.description }] : []), + ...(portal.seo.googleSiteVerification + ? [{ name: 'google-site-verification', content: portal.seo.googleSiteVerification }] + : []) ], links: [{ rel: 'stylesheet', href: appCss }, ...iconLinks] }), @@ -47,6 +52,12 @@ export const Route = createRootRoute({ }); function RootComponent() { + const router = useRouter(); + useEffect(() => { + // A prerendered page mounts idle with no `onRendered` to come; `portal serve` mounts pending, and one follows. + if (router.state.status === 'idle') analytics.reportPageView(); + return router.subscribe('onRendered', () => analytics.reportPageView()); + }, [router]); return ( diff --git a/portal-template/vite.config.ts b/portal-template/vite.config.ts index 1151c6ff5..9fd1975e4 100644 --- a/portal-template/vite.config.ts +++ b/portal-template/vite.config.ts @@ -12,6 +12,7 @@ import { prerenderPages } from './prerender-pages.ts'; import { remarkJsxImages } from './remark-jsx-images.ts'; import { specReload } from './spec-reload.ts'; import { remarkImageReferences } from './src/lib/remark-image-references.ts'; +import { rehypeCodeOptions } from './src/lib/transformer-language.ts'; import { staticFunctionsBase } from './static-functions-base.ts'; import { staticImages } from './static-images.ts'; @@ -37,7 +38,8 @@ export default defineConfig(async ({ command, isPreview }) => { mdxOptions: { remarkImageOptions: { publicDir: publicDir || undefined, external: false }, // A function, so it runs ahead of the preset's own plugins, `remarkImage` among them. - remarkPlugins: (plugins) => [remarkImageReferences, [remarkJsxImages, { publicDir }], ...plugins] + remarkPlugins: (plugins) => [remarkImageReferences, [remarkJsxImages, { publicDir }], ...plugins], + rehypeCodeOptions } } }), diff --git a/src/actions/portal/generate.ts b/src/actions/portal/generate.ts index 2a1f42b3b..ac126945f 100644 --- a/src/actions/portal/generate.ts +++ b/src/actions/portal/generate.ts @@ -5,6 +5,7 @@ import { CommandMetadata } from '../../types/common/command-metadata.js'; import { DirectoryPath } from '../../types/file/directoryPath.js'; import { PortalContext } from '../../types/portal-context.js'; import { SiteAddress } from '../../types/portal/config/site-address.js'; +import { PortalBuildOptions } from '../../types/portal/portal-source.js'; import { ProjectContext } from '../../types/project-context.js'; import { ActionResult } from '../action-result.js'; import { PreparePortalProjectAction } from './prepare-project.js'; @@ -26,7 +27,8 @@ export class GenerateAction { project: ProjectContext, portalDirectory: DirectoryPath, force: boolean, - zipPortal: boolean + zipPortal: boolean, + build: PortalBuildOptions ): Promise => { if (project.isSourceDirectory(portalDirectory)) { this.prompts.directoryCannotBeSame(portalDirectory); @@ -41,7 +43,8 @@ export class GenerateAction { } const portalContext = new PortalContext(portalDirectory); - return await new PreparePortalProjectAction(this.configDir, this.commandMetadata, this.authKey).execute(project, { + const prepare = new PreparePortalProjectAction(this.configDir, this.commandMetadata, this.authKey); + return await prepare.execute(project, build, { confirm: () => this.confirmOverwrite(portalContext, portalDirectory, force), onPrepared: (portalProject, source) => this.build(portalProject, source.config.siteAddress(), portalContext, portalDirectory, zipPortal) diff --git a/src/actions/portal/prepare-project.ts b/src/actions/portal/prepare-project.ts index 1aea7782d..415d5bc98 100644 --- a/src/actions/portal/prepare-project.ts +++ b/src/actions/portal/prepare-project.ts @@ -6,7 +6,7 @@ import { PreparePortalProjectPrompts } from '../../prompts/portal/prepare-projec import { CommandMetadata } from '../../types/common/command-metadata.js'; import { DirectoryPath } from '../../types/file/directoryPath.js'; import { PortalArtifacts } from '../../types/portal/portal-artifacts.js'; -import { PortalSource } from '../../types/portal/portal-source.js'; +import { PortalBuildOptions, PortalSource } from '../../types/portal/portal-source.js'; import { ProjectContext } from '../../types/project-context.js'; import { ActionResult } from '../action-result.js'; @@ -36,6 +36,7 @@ export class PreparePortalProjectAction { /** Takes the caller's next step rather than returning, because its temporary directories must outlive this call. */ public readonly execute = async ( project: ProjectContext, + build: PortalBuildOptions, { confirm = async () => true, onPrepared }: PreparationSteps ): Promise => { const sourceDirectory = project.sourceDirectory(); @@ -63,7 +64,7 @@ export class PreparePortalProjectAction { } // Ahead of the server run, which can take minutes: a mistake or a question should not wait on it. - const source = await project.portalSource().resolve(); + const source = await project.portalSource().resolve(build); if (source.isErr()) { this.prompts.sourceProblem(source.error, sourceDirectory); return ActionResult.failed(); @@ -72,6 +73,9 @@ export class PreparePortalProjectAction { this.prompts.contentNotices(source.value.contentNotices, sourceDirectory); this.prompts.unmergedSpecs(source.value.unmergedSpecs, sourceDirectory); this.prompts.leftOutSpecs(source.value.leftOutSpecs, sourceDirectory); + if (source.value.config.usesGoogleAnalytics()) { + this.prompts.googleAnalyticsCountsPageChanges(); + } if (!(await confirm())) { return ActionResult.cancelled(); diff --git a/src/actions/portal/serve.ts b/src/actions/portal/serve.ts index 1c190afeb..8c644e9a5 100644 --- a/src/actions/portal/serve.ts +++ b/src/actions/portal/serve.ts @@ -9,7 +9,7 @@ import { ProjectContext } from '../../types/project-context.js'; import { isSkippedByGlob } from '../../types/portal/content-tree.js'; import { GeneratedPages } from '../../types/portal/generated-pages.js'; import { PortalArtifacts } from '../../types/portal/portal-artifacts.js'; -import { PortalSettings, PortalSource, WatchedSource } from '../../types/portal/portal-source.js'; +import { PortalBuildOptions, PortalSettings, PortalSource, WatchedSource } from '../../types/portal/portal-source.js'; import { PreviewConfig } from '../../types/portal/preview-config.js'; import { PreviewContent } from '../../types/portal/preview-content.js'; import { PreviewSpecs } from '../../types/portal/preview-specs.js'; @@ -45,9 +45,11 @@ export class PortalServeAction { project: ProjectContext, port: number, openInBrowser: boolean, + build: PortalBuildOptions, onServing?: () => void ): Promise => { - return await new PreparePortalProjectAction(this.configDir, this.commandMetadata, this.authKey).execute(project, { + const prepare = new PreparePortalProjectAction(this.configDir, this.commandMetadata, this.authKey); + return await prepare.execute(project, build, { onPrepared: async (portalProject, source, artifacts) => { const servePort = await this.networkService.getServerPort([port, 3000, 3001, 3002]); if (servePort !== port) { @@ -73,13 +75,20 @@ export class PortalServeAction { // adds and removes, and which the root nav.json makes tabs of or places in Home. let generatedPages = source.generatedPages; const contentWatch = this.watchContent(project, source, () => generatedPages, portalProject.projectDirectory); - const configWatch = this.watchConfig(project, source, artifacts, portalProject.projectDirectory, (settings) => { - const sectionsChanged = !settings.generatedPages.makesSameSectionsAs(generatedPages); - generatedPages = settings.generatedPages; - if (sectionsChanged) { - contentWatch?.recheck(); + const configWatch = this.watchConfig( + project, + source, + artifacts, + portalProject.projectDirectory, + build, + (settings) => { + const sectionsChanged = !settings.generatedPages.makesSameSectionsAs(generatedPages); + generatedPages = settings.generatedPages; + if (sectionsChanged) { + contentWatch?.recheck(); + } } - }); + ); const specWatch = this.watchSpecs(project, source); const closeWatches = async () => { await specWatch?.close(); @@ -122,6 +131,7 @@ export class PortalServeAction { source: PortalSource, artifacts: PortalArtifacts, portalProjectDirectory: DirectoryPath, + build: PortalBuildOptions, onApplied: (settings: PortalSettings) => void ): FileWatch | undefined { const sourceDirectory = project.sourceDirectory(); @@ -129,7 +139,7 @@ export class PortalServeAction { const preview = new PreviewConfig(source.config, source.staticDirectory !== null); const applyEdit = async () => { - const reloaded = await sourceContext.resolveSettings(source.suggestedSite); + const reloaded = await sourceContext.resolveSettings(source.suggestedSite, build); if (reloaded.isErr()) { preview.refuse(); this.prompts.configRejected(reloaded.error, sourceDirectory); diff --git a/src/actions/quickstart.ts b/src/actions/quickstart.ts index 1c620ffe7..7b7b2069d 100644 --- a/src/actions/quickstart.ts +++ b/src/actions/quickstart.ts @@ -244,6 +244,7 @@ export class QuickstartAction { project, DEFAULT_PORTAL_PORT, true, + { analytics: true }, () => this.prompts.nextSteps(configFile) ); diff --git a/src/commands/portal/generate.ts b/src/commands/portal/generate.ts index a4f1223cd..87ba963e9 100644 --- a/src/commands/portal/generate.ts +++ b/src/commands/portal/generate.ts @@ -28,6 +28,7 @@ The portal is built on your machine and written as static files for any static h default: false, description: 'write the generated portal as a .zip archive.' }), + ...FlagsProvider.noAnalytics, ...FlagsProvider.input, ...FlagsProvider.destination('portal', 'portal'), ...FlagsProvider.force, @@ -36,7 +37,7 @@ The portal is built on your machine and written as static files for any static h async run(): Promise { const { - flags: { input, destination, force, zip: zipPortal, 'auth-key': authKey } + flags: { input, destination, force, zip: zipPortal, 'no-analytics': noAnalytics, 'auth-key': authKey } } = await this.parse(PortalGenerate); const project = ProjectContext.at(input); @@ -47,7 +48,9 @@ The portal is built on your machine and written as static files for any static h intro('Generate Portal'); const action = new GenerateAction(this.getConfigDir(), commandMetadata, authKey); - const result = await action.execute(project, project.portalDirectory(destination), force, zipPortal); + const result = await action.execute(project, project.portalDirectory(destination), force, zipPortal, { + analytics: !noAnalytics + }); outro(result); } diff --git a/src/commands/portal/serve.ts b/src/commands/portal/serve.ts index ba4d41c1c..e13b4bf72 100644 --- a/src/commands/portal/serve.ts +++ b/src/commands/portal/serve.ts @@ -36,13 +36,14 @@ Nothing is written to disk; run 'apimatic portal generate' to produce the static description: 'open the portal in the default browser.', default: false }), + ...FlagsProvider.noAnalytics, ...FlagsProvider.input, ...FlagsProvider.authKey }; public async run() { const { - flags: { input, port, open, 'auth-key': authKey } + flags: { input, port, open, 'no-analytics': noAnalytics, 'auth-key': authKey } } = await this.parse(PortalServe); const commandMetadata: CommandMetadata = { @@ -52,7 +53,7 @@ Nothing is written to disk; run 'apimatic portal generate' to produce the static intro('Portal Serve'); const action = new PortalServeAction(this.getConfigDir(), commandMetadata, authKey); - const result = await action.execute(ProjectContext.at(input), port, open); + const result = await action.execute(ProjectContext.at(input), port, open, { analytics: !noAnalytics }); outro(result); } diff --git a/src/prompts/portal/prepare-project.ts b/src/prompts/portal/prepare-project.ts index cf50a4be3..24ce0f2e6 100644 --- a/src/prompts/portal/prepare-project.ts +++ b/src/prompts/portal/prepare-project.ts @@ -41,6 +41,16 @@ export class PreparePortalProjectPrompts { reportAuthorizationFailure(failure); } + /** The portal reports its own page views, so a GA4 stream that also counts history changes counts each page twice. */ + public googleAnalyticsCountsPageChanges() { + const message = + `Google Analytics is set, so the portal sends its own page views. In GA4, turn off the stream's ` + + `"Page changes based on browser history events" (Admin → Data streams → your stream → Enhanced ` + + `measurement → Page views → advanced settings), or every page change counts twice. ` + + `See the analytics page on ${f.link('https://docs.apimatic.io/v4/')}.`; + log.warn(message); + } + public sourceNotZipped(problem: FileProblem, sourceDirectory: DirectoryPath) { log.error(notZippedForUpload(sourceDirectory, problem.reason)); } diff --git a/src/types/flags-provider.ts b/src/types/flags-provider.ts index 44f7a516e..899b955c0 100644 --- a/src/types/flags-provider.ts +++ b/src/types/flags-provider.ts @@ -33,6 +33,13 @@ export class FlagsProvider { }; } + public static readonly noAnalytics = { + 'no-analytics': Flags.boolean({ + default: false, + description: "leave out the Google Tag Manager and Google Analytics tags set in 'portal.analytics'." + }) + }; + // Auth key group public static authKey = { 'auth-key': Flags.string({ diff --git a/src/types/portal-source-context.ts b/src/types/portal-source-context.ts index f81e4e271..8dd06d313 100644 --- a/src/types/portal-source-context.ts +++ b/src/types/portal-source-context.ts @@ -30,6 +30,7 @@ import { MissingFile, MissingImage, MissingStaticFile, + PortalBuildOptions, PortalScaffoldProblem, PortalSettings, PortalSource, @@ -135,7 +136,7 @@ export class PortalSourceContext { } /** Reads and validates the whole source directory, or reports the first problem found. */ - public async resolve(): Promise> { + public async resolve(build: PortalBuildOptions): Promise> { const document = await this.readConfigDocument(); if (document.isErr()) { return err(document.error); @@ -149,7 +150,7 @@ export class PortalSourceContext { } const { specs, suggestedSite, unmergedSpecs, leftOutSpecs } = discovered.value; - const settings = await this.settingsFrom(document.value, suggestedSite); + const settings = await this.settingsFrom(document.value, suggestedSite, build); if (settings.isErr()) { return err(settings.error); } @@ -279,17 +280,21 @@ export class PortalSourceContext { * is accepted exactly when a build would accept it. `suggested` is what `resolve` found in the * specifications, which are not read again; changing them needs a restart anyway. */ - public async resolveSettings(suggested: SuggestedSite | null): Promise> { + public async resolveSettings( + suggested: SuggestedSite | null, + build: PortalBuildOptions + ): Promise> { const document = await this.readConfigDocument(); if (document.isErr()) { return err(document.error); } - return this.settingsFrom(document.value, suggested); + return this.settingsFrom(document.value, suggested, build); } private async settingsFrom( document: ApimaticConfigDocument, - suggested: SuggestedSite | null + suggested: SuggestedSite | null, + build: PortalBuildOptions ): Promise> { const settings = PortalSourceContext.parseSettings(document, suggested); if (settings.isErr()) { @@ -301,7 +306,7 @@ export class PortalSourceContext { if (missingFiles.length > 0) { return err({ kind: 'missingStaticFiles', files: missingFiles }); } - return ok(settings.value); + return ok(build.analytics ? settings.value : { ...settings.value, config: settings.value.config.withoutVendors() }); } private async readConfigDocument(): Promise> { diff --git a/src/types/portal/config/analytics-config.ts b/src/types/portal/config/analytics-config.ts new file mode 100644 index 000000000..76ec59d2b --- /dev/null +++ b/src/types/portal/config/analytics-config.ts @@ -0,0 +1,118 @@ +import { err, ok, Result } from 'neverthrow'; +import { isJsonObject } from '../../../utils/json-utils.js'; +import { allOf, namespace, nonEmptyString, optional, Parsed, required, unknownKeys } from './fields.js'; + +/** From a GTM environment's own snippet, so a staging build can still be checked in GTM. */ +export interface GoogleTagManagerEnvironment { + auth: string; + preview: string; +} + +export interface GoogleTagManagerSetting { + containerId: string; + environment: GoogleTagManagerEnvironment | null; +} + +export interface GoogleAnalyticsSetting { + measurementId: string; +} + +/** Public values: they sit in every page's scripts. */ +export interface PortalAnalytics { + googleTagManager: GoogleTagManagerSetting | null; + googleAnalytics: GoogleAnalyticsSetting | null; + keepQueryParams: string[]; +} + +const KNOWN = ['googleTagManager', 'googleAnalytics', 'keepQueryParams']; + +export class AnalyticsConfig { + private constructor( + private readonly googleTagManager: GoogleTagManagerSetting | null, + private readonly googleAnalytics: GoogleAnalyticsSetting | null, + private readonly keepQueryParams: string[] + ) {} + + public static readonly defaults = new AnalyticsConfig(null, null, []); + + public static parse(value: unknown, path: string): Parsed { + return namespace(value, path).andThen((data) => + allOf( + unknownKeys(data, KNOWN, path), + Result.combineWithAllErrors([ + optional(data.googleTagManager, (vendor) => googleTagManager(vendor, `${path}.googleTagManager`)), + optional(data.googleAnalytics, (vendor) => googleAnalytics(vendor, `${path}.googleAnalytics`)), + keptQueryParams(data.keepQueryParams, `${path}.keepQueryParams`) + ]) + ).map(([gtm, ga, keep]) => new AnalyticsConfig(gtm, ga, keep)) + ); + } + + /** `portal generate` and `portal serve` warn when this is true: the customer has a GA4 stream setting to turn off. */ + public usesGoogleAnalytics(): boolean { + return this.googleAnalytics !== null; + } + + public identity(): PortalAnalytics { + return { + googleTagManager: this.googleTagManager, + googleAnalytics: this.googleAnalytics, + keepQueryParams: this.keepQueryParams + }; + } + + /** For a staging build: neither vendor tag loads, while a reported address still keeps the same names. */ + public withoutVendors(): AnalyticsConfig { + return new AnalyticsConfig(null, null, this.keepQueryParams); + } +} + +// Each ID is required and nothing more: its format is the vendor's to check, since a wrong value fails there, not here. +function googleTagManager(value: unknown, path: string): Parsed { + if (!isJsonObject(value)) { + return err([`'${path}' must be a JSON object with 'containerId'.`]); + } + return allOf( + unknownKeys(value, ['containerId', 'environment'], path), + Result.combineWithAllErrors([ + required(value.containerId, `${path}.containerId`, nonEmptyString), + optional(value.environment, (given) => environment(given, `${path}.environment`)) + ]) + ).map(([containerId, environment]) => ({ containerId, environment })); +} + +function environment(value: unknown, path: string): Parsed { + if (!isJsonObject(value)) { + return err([`'${path}' must be a JSON object with 'auth' and 'preview'.`]); + } + return allOf( + unknownKeys(value, ['auth', 'preview'], path), + Result.combineWithAllErrors([ + required(value.auth, `${path}.auth`, nonEmptyString), + required(value.preview, `${path}.preview`, nonEmptyString) + ]) + ).map(([auth, preview]) => ({ auth, preview })); +} + +function googleAnalytics(value: unknown, path: string): Parsed { + if (!isJsonObject(value)) { + return err([`'${path}' must be a JSON object with 'measurementId'.`]); + } + return allOf( + unknownKeys(value, ['measurementId'], path), + Result.combineWithAllErrors([required(value.measurementId, `${path}.measurementId`, nonEmptyString)]) + ).map(([measurementId]) => ({ measurementId })); +} + +/** Names a reported address keeps, beyond the campaign names it always keeps. */ +function keptQueryParams(value: unknown, path: string): Parsed { + if (value === undefined) { + return ok([]); + } + if (!Array.isArray(value)) { + return err([`'${path}' must be a list of query parameter names.`]); + } + return Result.combineWithAllErrors(value.map((name, index) => nonEmptyString(name, `${path}[${index}]`))).mapErr( + (errors) => errors.flat() + ); +} diff --git a/src/types/portal/config/fields.ts b/src/types/portal/config/fields.ts index 4755f3d46..ef581704a 100644 --- a/src/types/portal/config/fields.ts +++ b/src/types/portal/config/fields.ts @@ -52,11 +52,12 @@ export function lightDark( if (!isJsonObject(value)) { return err([`'${path}' must be a string, or an object with 'light' and 'dark'.`]); } - const mode = (name: 'light' | 'dark'): Parsed => - value[name] === undefined ? err([`'${path}.${name}' is required.`]) : parse(value[name], `${path}.${name}`); return allOf( unknownKeys(value, ['light', 'dark'], path), - Result.combineWithAllErrors([mode('light'), mode('dark')]) + Result.combineWithAllErrors([ + required(value.light, `${path}.light`, parse), + required(value.dark, `${path}.dark`, parse) + ]) ).map(([light, dark]) => ({ light, dark, single: false })); } @@ -64,6 +65,15 @@ export function optional(value: unknown, parse: (present: unknown) => Parsed< return value === undefined ? ok(null) : parse(value); } +/** Present, then parsed: a field left out is named as missing rather than as the wrong type. */ +export function required( + value: unknown, + path: string, + parse: (present: unknown, path: string) => Parsed +): Parsed { + return value === undefined ? err([`'${path}' is required.`]) : parse(value, path); +} + export function optionalBoolean(value: unknown, path: string, fallback: boolean): Parsed { if (value === undefined) { return ok(fallback); diff --git a/src/types/portal/config/seo-config.ts b/src/types/portal/config/seo-config.ts new file mode 100644 index 000000000..e775fdd5f --- /dev/null +++ b/src/types/portal/config/seo-config.ts @@ -0,0 +1,30 @@ +import { Result } from 'neverthrow'; +import { allOf, namespace, nonEmptyString, optional, Parsed, unknownKeys } from './fields.js'; + +export interface PortalSeo { + /** The content value of Google's site verification meta tag, for Search Console. */ + googleSiteVerification: string | null; +} + +const KNOWN = ['googleSiteVerification']; + +export class SeoConfig { + private constructor(private readonly googleSiteVerification: string | null) {} + + public static readonly defaults = new SeoConfig(null); + + public static parse(value: unknown, path: string): Parsed { + return namespace(value, path).andThen((data) => + allOf( + unknownKeys(data, KNOWN, path), + Result.combineWithAllErrors([ + optional(data.googleSiteVerification, (given) => nonEmptyString(given, `${path}.googleSiteVerification`)) + ]) + ).map(([googleSiteVerification]) => new SeoConfig(googleSiteVerification)) + ); + } + + public identity(): PortalSeo { + return { googleSiteVerification: this.googleSiteVerification }; + } +} diff --git a/src/types/portal/portal-config.ts b/src/types/portal/portal-config.ts index 56cf2ce4b..acc020305 100644 --- a/src/types/portal/portal-config.ts +++ b/src/types/portal/portal-config.ts @@ -2,10 +2,12 @@ import { err, ok, Result } from 'neverthrow'; import { isJsonObject } from '../../utils/json-utils.js'; import { UrlPath } from '../file/urlPath.js'; import { AiConfig } from './config/ai-config.js'; +import { AnalyticsConfig, PortalAnalytics } from './config/analytics-config.js'; import { BrandConfig, ColorMode } from './config/brand-config.js'; import { allOf, optional, Parsed, unknownKeys } from './config/fields.js'; import { Link } from './config/link.js'; import { NavigationConfig } from './config/navigation-config.js'; +import { PortalSeo, SeoConfig } from './config/seo-config.js'; import { SiteAddress } from './config/site-address.js'; import { SiteConfig, SuggestedSite } from './config/site-config.js'; import { StaticAsset } from './config/static-asset.js'; @@ -35,11 +37,13 @@ export interface PortalIdentity { links: PortalLink[]; /** Whether each page offers to open itself in an external AI assistant. */ pageActions: boolean; + analytics: PortalAnalytics; + seo: PortalSeo; } const BLOCK = 'portal'; -const NAMESPACES = ['site', 'brand', 'navigation', 'ai']; +const NAMESPACES = ['site', 'brand', 'navigation', 'ai', 'analytics', 'seo']; /** The one setting outside the namespaces, named as the portal artifacts endpoint reads it. */ const PLUGIN_URL = 'pluginUrl'; @@ -50,6 +54,8 @@ export class PortalConfig { private readonly brand: BrandConfig, private readonly navigation: NavigationConfig, private readonly ai: AiConfig, + private readonly analytics: AnalyticsConfig, + private readonly seo: SeoConfig, private readonly pluginAddress: UrlPath | null ) {} @@ -60,6 +66,8 @@ export class PortalConfig { BrandConfig.defaults, NavigationConfig.defaults, AiConfig.defaults, + AnalyticsConfig.defaults, + SeoConfig.defaults, null ); } @@ -86,6 +94,8 @@ export class PortalConfig { BrandConfig.parse(block.brand, `${BLOCK}.brand`), NavigationConfig.parse(block.navigation, `${BLOCK}.navigation`), AiConfig.parse(block.ai, `${BLOCK}.ai`), + AnalyticsConfig.parse(block.analytics, `${BLOCK}.analytics`), + SeoConfig.parse(block.seo, `${BLOCK}.seo`), optional(block.pluginUrl, (value) => secureAddress(value, `${BLOCK}.${PLUGIN_URL}`)) ]) ).map((settings) => new PortalConfig(...settings)); @@ -113,6 +123,11 @@ export class PortalConfig { return this.brand.files(); } + /** `portal generate` and `portal serve` warn when this is true: the customer has a GA4 stream setting to turn off. */ + public usesGoogleAnalytics(): boolean { + return this.analytics.usesGoogleAnalytics(); + } + public identity(): PortalIdentity { const address = this.site.siteAddress(); const logo = this.brand.logoImages(); @@ -125,11 +140,26 @@ export class PortalConfig { favicon: favicon === null ? null : { url: favicon.portalPath(), type: favicon.imageType() }, colorMode: this.brand.mode(), links: this.navigation.headerLinks().map(portalLink), - pageActions: this.ai.offersPageActions() + pageActions: this.ai.offersPageActions(), + analytics: this.analytics.identity(), + seo: this.seo.identity() }; } - /** Every namespace included, defaults and all, which is what quickstart writes. */ + /** The same portal with neither vendor tag, for a staging build under `--no-analytics`. */ + public withoutVendors(): PortalConfig { + return new PortalConfig( + this.site, + this.brand, + this.navigation, + this.ai, + this.analytics.withoutVendors(), + this.seo, + this.pluginAddress + ); + } + + /** Every namespace included, defaults and all, which is what quickstart writes; `analytics` and `seo` start unset. */ public toJSON(): PortalBlock { return { site: this.site.toJSON(), diff --git a/src/types/portal/portal-source.ts b/src/types/portal/portal-source.ts index bf5c8ccf8..c5adac07c 100644 --- a/src/types/portal/portal-source.ts +++ b/src/types/portal/portal-source.ts @@ -47,6 +47,12 @@ export interface PortalSource extends PortalSettings { contentNotices: ContentNotices; } +/** What a run's flags change in the portal it builds from the source. */ +export interface PortalBuildOptions { + /** False under `--no-analytics`: the portal loads neither vendor tag. */ + analytics: boolean; +} + /** Why a source directory could not be written; each variant maps to its own message. */ export type PortalScaffoldProblem = | { kind: 'configUnreadable' } diff --git a/test/actions/portal/generate.test.ts b/test/actions/portal/generate.test.ts index c5f30bf22..72f610d51 100644 --- a/test/actions/portal/generate.test.ts +++ b/test/actions/portal/generate.test.ts @@ -38,12 +38,13 @@ describe('GenerateAction', () => { let authorize: sinon.SinonStub; let build: sinon.SinonStub; - const execute = (projectDirectory = FIXTURE, force = false, zip = false) => + const execute = (projectDirectory = FIXTURE, force = false, zip = false, analytics = true) => new GenerateAction(new DirectoryPath(root), COMMAND_METADATA, 'auth-key').execute( ProjectContext.in(projectDirectory), portalDirectory, force, - zip + zip, + { analytics } ); const inPortal = (relative: string) => fs.existsSync(path.join(portalDirectory.toString(), relative)); @@ -119,7 +120,9 @@ describe('GenerateAction', () => { it('fails when the source and destination are the same directory', async () => { const action = new GenerateAction(new DirectoryPath(root), COMMAND_METADATA); - const result = await action.execute(ProjectContext.in(FIXTURE), FIXTURE.join('src'), false, false); + const result = await action.execute(ProjectContext.in(FIXTURE), FIXTURE.join('src'), false, false, { + analytics: true + }); expect(result.isFailed()).to.be.true; expect(prompts.directoryCannotBeSame.calledOnce).to.be.true; diff --git a/test/actions/portal/prepare-project-stubs.ts b/test/actions/portal/prepare-project-stubs.ts index 5357b97e1..28f6909ff 100644 --- a/test/actions/portal/prepare-project-stubs.ts +++ b/test/actions/portal/prepare-project-stubs.ts @@ -1,3 +1,5 @@ +import fs from 'fs'; +import path from 'path'; import { ok } from 'neverthrow'; import sinon from 'sinon'; import { PortalProjectService } from '../../../src/infrastructure/portal-project-service'; @@ -34,6 +36,20 @@ export function completeArtifacts( ); } +/** A copy of `fixture` at `directory`, its `portal.analytics` set to `analytics`. */ +export function fixtureWithAnalytics( + fixture: DirectoryPath, + directory: DirectoryPath, + analytics: object +): DirectoryPath { + fs.cpSync(fixture.toString(), directory.toString(), { recursive: true }); + const configFile = path.join(directory.toString(), 'src', 'apimatic.json'); + const config = JSON.parse(fs.readFileSync(configFile, 'utf8')); + config.portal.analytics = analytics; + fs.writeFileSync(configFile, JSON.stringify(config)); + return directory; +} + /** * What `PreparePortalProjectAction` reaches for, stubbed the same way for both commands that run * it. A test that cares about one of these overrides it afterwards; the defaults are the happy path. diff --git a/test/actions/portal/prepare-project.test.ts b/test/actions/portal/prepare-project.test.ts index cbb8aa5bb..cb60ea153 100644 --- a/test/actions/portal/prepare-project.test.ts +++ b/test/actions/portal/prepare-project.test.ts @@ -1,4 +1,6 @@ +import fs from 'fs'; import os from 'os'; +import path from 'path'; import AdmZip from 'adm-zip'; import sinon from 'sinon'; import { expect } from 'chai'; @@ -12,7 +14,12 @@ import { FilePath } from '../../../src/types/file/filePath'; import { CommandMetadata } from '../../../src/types/common/command-metadata'; import { ProjectContext } from '../../../src/types/project-context'; import { TempContext } from '../../../src/types/temp-context'; -import { completeArtifacts, PreparePortalProjectStubs, stubPreparePortalProject } from './prepare-project-stubs'; +import { + completeArtifacts, + fixtureWithAnalytics, + PreparePortalProjectStubs, + stubPreparePortalProject +} from './prepare-project-stubs'; const COMMAND_METADATA: CommandMetadata = { commandName: 'portal generate', shell: 'test' }; @@ -31,6 +38,7 @@ describe('PreparePortalProjectAction', () => { const result = await new PreparePortalProjectAction(new DirectoryPath(os.tmpdir()), COMMAND_METADATA).execute( ProjectContext.in(share), + { analytics: true }, { onPrepared } ); @@ -45,9 +53,10 @@ describe('PreparePortalProjectAction', () => { let shared: PreparePortalProjectStubs; let onPrepared: sinon.SinonStub; - const execute = () => + const execute = (analytics = true, project = FIXTURE) => new PreparePortalProjectAction(new DirectoryPath(os.tmpdir()), COMMAND_METADATA).execute( - ProjectContext.in(FIXTURE), + ProjectContext.in(project), + { analytics }, { onPrepared } ); @@ -71,6 +80,46 @@ describe('PreparePortalProjectAction', () => { expect(uploaded.filter((entry) => entry.startsWith('static/'))).to.be.empty; }); + describe('with both vendors set', () => { + let root: string; + const project = () => + fixtureWithAnalytics(FIXTURE, new DirectoryPath(root), { + googleTagManager: { containerId: 'GTM-ABC123' }, + googleAnalytics: { measurementId: 'G-ABC123' } + }); + + beforeEach(() => { + root = fs.mkdtempSync(path.join(os.tmpdir(), 'portal-prepare-')); + }); + + afterEach(() => { + fs.rmSync(root, { recursive: true, force: true }); + }); + + it('warns that Google Analytics counts page changes, before the artifacts are asked for', async () => { + await execute(true, project()); + + expect(shared.prompts.googleAnalyticsCountsPageChanges.calledOnce).to.be.true; + expect(shared.prompts.googleAnalyticsCountsPageChanges.calledBefore(shared.artifacts)).to.be.true; + expect(onPrepared.firstCall.args[1].config.usesGoogleAnalytics()).to.be.true; + }); + + it('prepares the project, and hands on the source, with neither vendor tag and no warning under --no-analytics', async () => { + await execute(false, project()); + + expect(shared.prepare.firstCall.args[1].config.identity().analytics.googleTagManager).to.be.null; + expect(onPrepared.firstCall.args[1].config.identity().analytics.googleTagManager).to.be.null; + expect(onPrepared.firstCall.args[1].config.usesGoogleAnalytics()).to.be.false; + expect(shared.prompts.googleAnalyticsCountsPageChanges.called).to.be.false; + }); + }); + + it('does not warn about Google Analytics when it is not set', async () => { + await execute(); + + expect(shared.prompts.googleAnalyticsCountsPageChanges.called).to.be.false; + }); + it('reports a source it could not zip, without asking for the artifacts', async () => { const problem: FileProblem = { kind: 'zipFailed', reason: 'EBUSY: resource busy or locked' }; sinon.stub(TempContext.prototype, 'zip').resolves(err(problem)); diff --git a/test/actions/portal/serve.test.ts b/test/actions/portal/serve.test.ts index 60f2ba9fb..1d381ae3e 100644 --- a/test/actions/portal/serve.test.ts +++ b/test/actions/portal/serve.test.ts @@ -45,11 +45,12 @@ describe('PortalServeAction', () => { /** Stands in for the preview process dying, with what it printed on the way out. */ let exit: (output: string) => void; - const execute = (projectDirectory = FIXTURE, openInBrowser = false) => + const execute = (projectDirectory = FIXTURE, openInBrowser = false, analytics = true) => new PortalServeAction(new DirectoryPath(root), COMMAND_METADATA, 'auth-key').execute( ProjectContext.in(projectDirectory), PORT, - openInBrowser + openInBrowser, + { analytics } ); /** Stands in for the watch on `directory`, answered by `watching`; any other tree's watch is left alone. */ @@ -608,8 +609,8 @@ describe('PortalServeAction', () => { fs.writeFileSync(path.join(source.toString(), 'apimatic.json'), JSON.stringify(config)); /** Runs the preview until `body` is done with it, then stops it as CTRL+C would. */ - const whileServing = async (body: () => Promise) => { - const running = execute(new DirectoryPath(root)); + const whileServing = async (body: () => Promise, analytics = true) => { + const running = execute(new DirectoryPath(root), false, analytics); const { onChange } = await watched; save = async (config: object) => { writeConfig(config); @@ -890,6 +891,21 @@ describe('PortalServeAction', () => { }); }); + it('leaves the vendor tags out of the project and of each rewrite under --no-analytics', async () => { + const applyConfig = sinon.spy(PortalProjectService.prototype, 'applyConfig'); + const config = originalConfig(); + config.portal.analytics = { googleTagManager: { containerId: 'GTM-ABC123' } }; + writeConfig(config); + + await whileServing(async () => { + config.portal.site.name = 'Renamed API'; + await save(config); + }, false); + + expect(shared.prepare.firstCall.args[1].config.identity().analytics.googleTagManager).to.be.null; + expect(applyConfig.lastCall.args[1].config.identity().analytics.googleTagManager).to.be.null; + }); + it('reports a change it could not write to the preview', async () => { await whileServing(async () => { sinon.stub(PortalProjectService.prototype, 'applyConfig').resolves(err('EACCES: permission denied')); diff --git a/test/actions/quickstart.test.ts b/test/actions/quickstart.test.ts index 66d4cc314..0b571f1d5 100644 --- a/test/actions/quickstart.test.ts +++ b/test/actions/quickstart.test.ts @@ -22,6 +22,7 @@ import { FileDownloadService } from '../../src/infrastructure/services/file-down import { ServiceError } from '../../src/infrastructure/service-error'; import { UrlPath } from '../../src/types/file/urlPath'; import { ProjectContext } from '../../src/types/project-context'; +import { PortalConfig } from '../../src/types/portal/portal-config'; import { completeArtifacts } from './portal/prepare-project-stubs'; const COMMAND_METADATA: CommandMetadata = { commandName: 'portal quickstart', shell: 'test' }; @@ -107,6 +108,7 @@ describe('QuickstartAction', () => { .stub(PortalArtifactsService.prototype, 'generate') .resolves(ok(completeArtifacts([Language.TYPESCRIPT, Language.PYTHON]))); const prepare = sinon.stub(PortalProjectService.prototype, 'prepare').resolves(err('stopped here')); + const withoutVendors = sinon.spy(PortalConfig.prototype, 'withoutVendors'); await execute(); @@ -127,6 +129,7 @@ describe('QuickstartAction', () => { // prepares a project. expect(artifacts.called, 'the wizard asked for the artifacts').to.be.true; expect(prepare.called, 'the wizard reached the preview').to.be.true; + expect(withoutVendors.called, 'the preview counts like a hosted portal').to.be.false; }); it('asks for nothing more and stops when no language is chosen', async () => { diff --git a/test/commands/portal/build-options.ts b/test/commands/portal/build-options.ts new file mode 100644 index 000000000..ab7d09d4d --- /dev/null +++ b/test/commands/portal/build-options.ts @@ -0,0 +1,35 @@ +import os from 'os'; +import sinon from 'sinon'; +import { Config } from '@oclif/core'; +import { err, ok } from 'neverthrow'; +import { PortalAuthorizationService } from '../../../src/infrastructure/services/portal-authorization-service.js'; +import { PortalSourceContext } from '../../../src/types/portal-source-context.js'; +import { stubPreparePortalProject } from '../../actions/portal/prepare-project-stubs.js'; + +const FIXTURE = 'test/resources/portal-inputs/default'; + +/** Just enough of oclif's config for a command to parse its flags and name its config directory. */ +const config = { + configDir: os.tmpdir(), + shell: 'test', + runHook: async () => ({ successes: [], failures: [] }) +} as unknown as Config; + +/** Runs a portal command up to its read of the source, and gives what its flags asked that read for. */ +export async function buildOptionsOf( + command: new (argv: string[], config: Config) => { run(): Promise }, + argv: string[] +): Promise { + stubPreparePortalProject(); + sinon.stub(PortalAuthorizationService.prototype, 'authorize').resolves(ok(undefined)); + const resolve = sinon.stub(PortalSourceContext.prototype, 'resolve').resolves(err({ kind: 'missingConfig' })); + sinon.stub(process.stdout, 'write').returns(true); + const exitCode = process.exitCode; + try { + await new command([...argv, '--input', FIXTURE], config).run(); + } finally { + process.exitCode = exitCode; + sinon.restore(); + } + return resolve.firstCall.args[0]; +} diff --git a/test/commands/portal/generate-flags.test.ts b/test/commands/portal/generate-flags.test.ts new file mode 100644 index 000000000..b5917aad4 --- /dev/null +++ b/test/commands/portal/generate-flags.test.ts @@ -0,0 +1,10 @@ +import { expect } from 'chai'; +import PortalGenerate from '../../../src/commands/portal/generate.js'; +import { buildOptionsOf } from './build-options.js'; + +describe('portal generate flags', () => { + it('reads the source without the vendor tags under --no-analytics, and with them otherwise', async () => { + expect(await buildOptionsOf(PortalGenerate, ['--no-analytics'])).to.deep.equal({ analytics: false }); + expect(await buildOptionsOf(PortalGenerate, [])).to.deep.equal({ analytics: true }); + }); +}); diff --git a/test/commands/portal/serve-flags.test.ts b/test/commands/portal/serve-flags.test.ts new file mode 100644 index 000000000..f3607c004 --- /dev/null +++ b/test/commands/portal/serve-flags.test.ts @@ -0,0 +1,10 @@ +import { expect } from 'chai'; +import PortalServe from '../../../src/commands/portal/serve.js'; +import { buildOptionsOf } from './build-options.js'; + +describe('portal serve flags', () => { + it('reads the source without the vendor tags under --no-analytics, and with them otherwise', async () => { + expect(await buildOptionsOf(PortalServe, ['--no-analytics'])).to.deep.equal({ analytics: false }); + expect(await buildOptionsOf(PortalServe, [])).to.deep.equal({ analytics: true }); + }); +}); diff --git a/test/e2e/portal-build.test.ts b/test/e2e/portal-build.test.ts index 3bf144d25..84489d291 100644 --- a/test/e2e/portal-build.test.ts +++ b/test/e2e/portal-build.test.ts @@ -39,6 +39,8 @@ interface BuiltPortal { root: string; project: DirectoryPath; output: DirectoryPath; + /** What the build read: the fixture, or its copy when settings were added to it. */ + source: DirectoryPath; } interface Delivered { @@ -64,12 +66,22 @@ function deliveredInto( ); } -/** Resolves, prepares, builds and saves a fixture as `portal generate` does. */ -async function buildFixture(name: string, delivered: Delivered = {}): Promise { - const fixture = new DirectoryPath(process.cwd()).join('test/resources/portal-inputs').join(name).join('src'); +/** Resolves, prepares, builds and saves a fixture as `portal generate` does, with `settings` added to its `portal` block. */ +async function buildFixture(name: string, delivered: Delivered = {}, settings?: object): Promise { + let fixture = new DirectoryPath(process.cwd()).join('test/resources/portal-inputs').join(name).join('src'); const root = canonical(fs.mkdtempSync(path.join(os.tmpdir(), 'portal-e2e-'))); - const source = (await new PortalSourceContext(fixture).resolve())._unsafeUnwrap(); + if (settings !== undefined) { + // A copy, so the fixture the other suites read stays as it is. + const copy = new DirectoryPath(root).join('src'); + fs.cpSync(fixture.toString(), copy.toString(), { recursive: true }); + const configFile = path.join(copy.toString(), 'apimatic.json'); + const config = JSON.parse(fs.readFileSync(configFile, 'utf8')); + fs.writeFileSync(configFile, JSON.stringify({ ...config, portal: { ...config.portal, ...settings } })); + fixture = copy; + } + + const source = (await new PortalSourceContext(fixture).resolve({ analytics: true }))._unsafeUnwrap(); const project = new DirectoryPath(root).join('build'); fs.mkdirSync(project.toString(), { recursive: true }); @@ -85,7 +97,7 @@ async function buildFixture(name: string, delivered: Delivered = {}): Promise { if (built === undefined) throw new Error(`${name} is not built`); @@ -104,7 +116,7 @@ function portalBuilt(name: string, delivered: Delivered = {}) { }; before(async () => { - built = await buildFixture(name, delivered); + built = await buildFixture(name, delivered, settings); }); after(() => removeBuilt(built)); @@ -112,6 +124,7 @@ function portalBuilt(name: string, delivered: Delivered = {}) { return { output: () => have().output, project: () => have().project, + source: () => have().source, read: (relative: string) => fs.readFileSync(path.join(have().output.toString(), relative), 'utf8'), exists: (relative: string) => fs.existsSync(path.join(have().output.toString(), relative)) }; @@ -179,8 +192,14 @@ const stylesheetOf = (output: DirectoryPath) => { (enabled ? describe : describe.skip)('portal build (end to end)', function () { this.timeout(10 * 60 * 1000); - const fixture = new DirectoryPath(process.cwd()).join('test/resources/portal-inputs/default/src'); - const portal = portalBuilt('default', { codeSampleCatalogs: CODE_SAMPLES }); + const portal = portalBuilt( + 'default', + { codeSampleCatalogs: CODE_SAMPLES }, + { + analytics: { googleTagManager: { containerId: 'GTM-E2ETEST' }, googleAnalytics: { measurementId: 'G-E2ETEST' } }, + seo: { googleSiteVerification: 'e2e-verification' } + } + ); const { read, exists } = portal; /** The prerendered server-function cache entries carrying the sidebar tree. */ @@ -248,6 +267,54 @@ const stylesheetOf = (output: DirectoryPath) => { expect(read('index.html')).to.contain(' + fs + .readdirSync(portal.output().toString(), { recursive: true, withFileTypes: true }) + .filter((entry) => entry.isFile() && entry.name.endsWith('.html')) + .map((entry) => path.relative(portal.output().toString(), path.join(entry.parentPath, entry.name))); + + it('tells the browser both vendor IDs in a script, and names the tag host in no prerendered page', () => { + const scripts = scriptsOf(portal.output()); + expect(scripts.some(({ text }) => text.includes('GTM-E2ETEST') && text.includes('G-E2ETEST'))).to.be.true; + // The loader itself, not only the identity file the IDs sit in. + expect(scripts.some(({ text }) => text.includes('gtm.js?id=') && text.includes('/gtag/js?id='))).to.be.true; + for (const page of pages()) { + expect(read(page), page).to.not.contain('googletagmanager.com'); + } + }); + + it('carries the verification meta on every prerendered page', () => { + expect(pages()).to.have.length.greaterThan(3); + for (const page of pages()) { + expect(read(page), page).to.contain(' { + const parts = read('api/apimatic-calculator/simple-calculator/Calculate/index.html').split( + 'data-portal-playground' + ); + expect(parts, 'one element').to.have.length(2); + // What Fumadocs' playground renders on the server: its header, with the method, the route and the trigger. + expect(parts[1].slice(0, 2000)).to.match(/>GET<[\s\S]*\{operation\}[\s\S]*aria-haspopup="dialog"/); + expect(parts[0].slice(parts[0].lastIndexOf(' { + // The marked element's one child, past React's own comment, is the sample's block, with the command in it. + expect(read('api/apimatic-calculator/simple-calculator/Calculate/index.html')).to.match( + /data-private="">(?:)*)[\s\S])*>curl<[\s\S]*?> -X<[\s\S]*?> GET { + // Fumadocs' own button, in the card's header: after the title, before the header closes. + expect(read('api/apimatic-calculator/simple-calculator/Calculate/index.html')).to.match( + />Example Response<\/span>(?:(?!<\/div>)[\s\S])*]*\baria-live=/ + ); + }); + it('keeps the server-side specification loader out of the browser bundle', () => { const scripts = fs .readdirSync(path.join(portal.output().toString(), 'assets')) @@ -288,13 +355,13 @@ const stylesheetOf = (output: DirectoryPath) => { // published: `portal.server.ts` holds the absolute path of every specification, and the // prepared project's own location has no business in the output either. it('publishes neither the specification paths nor the project directory', () => { - expect(filesNaming(portal.project().toString(), fixture.join('spec').toString())).to.deep.equal([]); + expect(filesNaming(portal.project().toString(), portal.source().join('spec').toString())).to.deep.equal([]); }); // `defineDocs({ dir })` compiles its directory into the client bundle as the collection's // `base`, which is why the project reads a copy of the content by a relative name. it('publishes no absolute path from the build machine at all', () => { - expect(filesNaming(fixture.join('content').toString(), fixture.toString())).to.deep.equal([]); + expect(filesNaming(portal.source().join('content').toString(), portal.source().toString())).to.deep.equal([]); }); it('writes the sidebar tree to one cache file instead of into every page payload', () => { diff --git a/test/e2e/portal-serve.test.ts b/test/e2e/portal-serve.test.ts index b11324e75..d9f8ee159 100644 --- a/test/e2e/portal-serve.test.ts +++ b/test/e2e/portal-serve.test.ts @@ -30,7 +30,7 @@ const enabled = process.env.APIMATIC_E2E === '1'; const root = canonical(fs.mkdtempSync(path.join(os.tmpdir(), 'portal-serve-e2e-'))); roots.push(root); - const resolved = (await new PortalSourceContext(source).resolve())._unsafeUnwrap(); + const resolved = (await new PortalSourceContext(source).resolve({ analytics: true }))._unsafeUnwrap(); const delivered = path.join(root, 'delivered'); fs.mkdirSync(delivered, { recursive: true }); fs.writeFileSync(path.join(delivered, 'typescript.zip'), 'PK typescript'); diff --git a/test/infrastructure/portal-pages-service.test.ts b/test/infrastructure/portal-pages-service.test.ts index 65fb95b61..3f88fdf83 100644 --- a/test/infrastructure/portal-pages-service.test.ts +++ b/test/infrastructure/portal-pages-service.test.ts @@ -90,7 +90,7 @@ describe('PortalPagesService', () => { 'install="npm install @acme/calc" packageUrl="https://www.npmjs.com/package/@acme/calc" registry="npm" />' ); expect(read('sdks/typescript.mdx')).to.contain( - '' ); }); diff --git a/test/infrastructure/portal-project-service.test.ts b/test/infrastructure/portal-project-service.test.ts index 5724fe4cd..9c3a74d43 100644 --- a/test/infrastructure/portal-project-service.test.ts +++ b/test/infrastructure/portal-project-service.test.ts @@ -540,6 +540,28 @@ describe('PortalProjectService', () => { const themeFile = () => path.join(project.toString(), 'src/styles/theme.css'); const identityFile = () => path.join(project.toString(), 'portal.identity.json'); + it('writes the vendors the config holds, and none from a config without them', async () => { + const config = configFor({ + site: { name: 'My API' }, + analytics: { googleTagManager: { containerId: 'GTM-ABC123' }, googleAnalytics: { measurementId: 'G-ABC123' } } + }); + (await service.prepare(project, sourceFor({ config: config.withoutVendors() }), NO_ARTIFACTS))._unsafeUnwrap(); + + expect(readIdentity().analytics).to.deep.equal({ + googleTagManager: null, + googleAnalytics: null, + keepQueryParams: [] + }); + + expect((await service.applyConfig(project, settingsFor(config)))._unsafeUnwrap()).to.be.true; + + expect(readIdentity().analytics).to.deep.equal({ + googleTagManager: { containerId: 'GTM-ABC123', environment: null }, + googleAnalytics: { measurementId: 'G-ABC123' }, + keepQueryParams: [] + }); + }); + it('writes nothing, and says so, when the block makes the same site', async () => { const config = configFor({ site: { name: 'My API' }, brand: { colors: { primary: '#1d4ed8' } } }); (await service.prepare(project, sourceFor({ config }), NO_ARTIFACTS))._unsafeUnwrap(); diff --git a/test/portal-template.test.ts b/test/portal-template.test.ts index 5c5c4f321..51aba5680 100644 --- a/test/portal-template.test.ts +++ b/test/portal-template.test.ts @@ -16,6 +16,7 @@ import { GENERATED_INCLUDES_DIRECTORY_NAME } from '../src/types/portal/page-frag import { PortalIdentity } from '../src/types/portal/portal-config'; import type { BuildPaths } from '../portal-template/portal-config'; import type { CodeSamplesFile as TemplateCodeSamplesFile } from '../portal-template/src/lib/code-samples.server'; +import { languageAliases } from '../portal-template/src/lib/languages'; import type { Portal } from '../portal-template/src/lib/portal-types'; /** True only when the two types are identical, every nested field and union member included. */ @@ -232,12 +233,7 @@ describe('portal template packaging', () => { /** The language ids the bundle imports a grammar for. */ const bundledIds = (): string[] => [...source().matchAll(/shiki\/dist\/langs\/([\w-]+)\.mjs/g)].map((m) => m[1]); - const keys = (): Set => { - const text = source(); - const block = /const aliases[^{]*{([\s\S]*?)\n};/.exec(text); - const aliasKeys = [...(block?.[1] ?? '').matchAll(/^\s*'?([\w#-]+)'?\s*:/gm)].map((m) => m[1]); - return new Set([...bundledIds(), ...aliasKeys]); - }; + const keys = (): Set => new Set([...bundledIds(), ...Object.keys(languageAliases)]); it('names every grammar it imports by a file that exists', async () => { const shiki = path.dirname(createRequire(import.meta.url).resolve('shiki/package.json')); @@ -265,8 +261,7 @@ describe('portal template packaging', () => { }); it('points every alias at a language it actually bundles', () => { - const block = /const aliases[^{]*{([\s\S]*?)\n};/.exec(source()); - const targets = [...(block?.[1] ?? '').matchAll(/:\s*'([\w-]+)'/g)].map((m) => m[1]); + const targets = Object.values(languageAliases); const bundled = new Set(bundledIds()); expect(targets).to.not.be.empty; diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts new file mode 100644 index 000000000..8b04e0057 --- /dev/null +++ b/test/portal-template/analytics.test.ts @@ -0,0 +1,772 @@ +import { expect } from 'chai'; +import { Analytics, pageLocation, PortalEventName, PortalEvents } from '../../portal-template/src/lib/analytics'; +import type { PortalAnalytics } from '../../portal-template/src/lib/portal-types'; +import { Adapter, adapters } from '../../portal-template/src/lib/vendor-tags'; + +// The list is written out here, not imported: the test is the contract, and a name the module drops fails it. +const KEPT_NAMES = [ + '_gl', + 'gclid', + 'gbraid', + 'wbraid', + 'gad_source', + 'dclid', + 'fbclid', + 'msclkid', + 'ttclid', + 'twclid', + 'li_fat_id', + 'mc_cid', + '_hsenc', + '_hsmi' +]; + +describe('pageLocation', () => { + const page = 'https://docs.test/guides/quickstart'; + + it('drops the query and the # part', () => { + expect(pageLocation(`${page}?tab=python&page=2#install`, [])).to.equal(page); + expect(pageLocation(`${page}#install`, [])).to.equal(page); + }); + + it('keeps campaign tags', () => { + expect(pageLocation(`${page}?utm_source=newsletter&utm_medium=email&session=abc`, [])).to.equal( + `${page}?utm_source=newsletter&utm_medium=email` + ); + }); + + it('keeps HubSpot ad tags', () => { + expect(pageLocation(`${page}?hsa_acc=1&hsa_cam=2&session=abc`, [])).to.equal(`${page}?hsa_acc=1&hsa_cam=2`); + }); + + it('keeps each ad-click and cross-domain tag', () => { + for (const name of KEPT_NAMES) { + expect(pageLocation(`${page}?${name}=x&session=abc`, []), name).to.equal(`${page}?${name}=x`); + } + }); + + it("keeps the customer's own names", () => { + expect(pageLocation(`${page}?campaign_id=7&session=abc`, ['campaign_id'])).to.equal(`${page}?campaign_id=7`); + }); + + it('drops a name that only starts with a kept one', () => { + expect(pageLocation(`${page}?gclidx=1`, [])).to.equal(page); + }); + + // No platform reads it from the address, and a customer can add a name but cannot take one out. + it('drops ref, which sites use for codes of their own, unless the customer keeps it', () => { + expect(pageLocation(`${page}?ref=invite-4821`, [])).to.equal(page); + expect(pageLocation(`${page}?ref=newsletter`, ['ref'])).to.equal(`${page}?ref=newsletter`); + }); + + it('leaves the address otherwise unchanged', () => { + expect(pageLocation(page, [])).to.equal(page); + expect(pageLocation('https://docs.test/', [])).to.equal('https://docs.test/'); + expect(pageLocation('https://docs.test/docs/api/pets/Get%20Pets', [])).to.equal( + 'https://docs.test/docs/api/pets/Get%20Pets' + ); + expect(pageLocation('http://localhost:3000/guides/quickstart', [])).to.equal( + 'http://localhost:3000/guides/quickstart' + ); + }); +}); + +describe('PortalEvents', () => { + // The compiler holds this table to the interface: a missing event, a missing key, or an extra key on an event with + // keys does not compile; an event with no keys takes none at report(). + const events: { [E in PortalEventName]: Record } = { + docs_page_view: { page_title: true }, + docs_markdown_copy: {}, + docs_plugin_install: {}, + docs_sdk_download: { language: true }, + docs_code_copy: { language: true }, + docs_search: { search_term: true, result: true, result_count: true }, + docs_not_found: { page_referrer: true }, + docs_api_request: { endpoint: true, status: true, duration_ms: true } + }; + + // Customers build GTM triggers and GA4 reports on these. They are plain text here, apart from the interface, so + // a rename or a new key is a change made in this list on purpose, never the side effect of a refactor. + it('ships exactly these events, each with exactly these keys', () => { + expect(Object.entries(events).map(([name, keys]) => [name, Object.keys(keys)])).to.deep.equal([ + ['docs_page_view', ['page_title']], + ['docs_markdown_copy', []], + ['docs_plugin_install', []], + ['docs_sdk_download', ['language']], + ['docs_code_copy', ['language']], + ['docs_search', ['search_term', 'result', 'result_count']], + ['docs_not_found', ['page_referrer']], + ['docs_api_request', ['endpoint', 'status', 'duration_ms']] + ]); + }); + + it('names every event docs_ plus lowercase snake_case, at most 40 characters', () => { + for (const name of Object.keys(events)) { + expect(name).to.match(/^docs_[a-z0-9_]+$/); + expect(name.length, name).to.be.at.most(40); + } + }); + + // GA4 takes at most 25 parameters per event, and report() adds page_location to each. + it('gives every event at most 24 keys, so 25 with page_location', () => { + for (const [name, keys] of Object.entries(events)) { + expect(Object.keys(keys).length, name).to.be.at.most(24); + } + }); +}); + +interface FakeScript { + async: boolean; + src: string; + textContent: string; +} + +interface FakeWindow { + location: URL & { reload: () => void }; + dataLayer?: unknown[]; + gtag?: (...command: unknown[]) => void; +} + +/** A page in the browser: the `window` and `document` the module reads, and the scripts the loader appends. */ +function browser(href: string, title = 'Quickstart | Acme API', referrer = '') { + const scripts: FakeScript[] = []; + let reloads = 0; + const window: FakeWindow = { location: Object.assign(new URL(href), { reload: () => (reloads += 1) }) }; + const document = { + title, + referrer, + createElement: (): FakeScript => ({ async: false, src: '', textContent: '' }), + head: { + append: (script: FakeScript) => scripts.push(script), + querySelector: (selector: string) => scripts.find((script) => selector === `script[src="${script.src}"]`) ?? null + } + }; + Object.assign(globalThis, { window, document }); + return { + window, + scripts, + dataLayer: () => window.dataLayer ?? [], + reloads: () => reloads, + go: (next: string, nextTitle = title) => { + window.location.href = next; + document.title = nextTitle; + } + }; +} + +const isArguments = (entry: unknown) => Object.prototype.toString.call(entry) === '[object Arguments]'; +const isPlainObject = (value: unknown): value is Record => + typeof value === 'object' && value !== null && !Array.isArray(value) && !isArguments(value); +const gtagCalls = (entries: unknown[]) => + entries.filter(isArguments).map((entry) => Array.from(entry as ArrayLike)); +const pageViews = (entries: unknown[]) => + entries.filter((entry) => isPlainObject(entry) && entry.event === 'docs_page_view'); +/** What the data layer reads as, once GTM has merged every push: objects recursively, `null` replacing. */ +function mergedLikeGtm(entries: unknown[]): Record { + const merge = (into: Record, from: Record): Record => { + for (const [key, value] of Object.entries(from)) { + const current = into[key]; + into[key] = isPlainObject(value) && isPlainObject(current) ? merge({ ...current }, value) : value; + } + return into; + }; + return entries.filter(isPlainObject).reduce(merge, {}); +} + +const none: PortalAnalytics = { googleTagManager: null, googleAnalytics: null, keepQueryParams: [] }; +const withGtm = (environment: { auth: string; preview: string } | null = null): PortalAnalytics => ({ + ...none, + googleTagManager: { containerId: 'GTM-ABC123', environment } +}); +const withGa4: PortalAnalytics = { ...none, googleAnalytics: { measurementId: 'G-ABC123' } }; +const withBoth: PortalAnalytics = { + ...none, + googleTagManager: withGtm().googleTagManager, + googleAnalytics: withGa4.googleAnalytics +}; +const GTM_SCRIPT = 'https://www.googletagmanager.com/gtm.js?id=GTM-ABC123'; +const GA4_SCRIPT = 'https://www.googletagmanager.com/gtag/js?id=G-ABC123'; + +describe('Analytics', () => { + const quickstart = 'https://docs.test/guides/quickstart'; + const quickstartView = { + event: 'docs_page_view', + docs: { page_title: 'Quickstart | Acme API', page_location: quickstart } + }; + const global = globalThis as { window?: unknown; document?: unknown }; + + afterEach(() => { + delete global.window; + delete global.document; + }); + + describe('with neither vendor set', () => { + it('pushes a reset entry and one clean page view entry, and nothing else', () => { + const page = browser(`${quickstart}?utm_source=newsletter&tab=python#install`); + const analytics = new Analytics(none); + + analytics.start(); + analytics.reportPageView(); + + expect(page.dataLayer()).to.deep.equal([ + { docs: null }, + { + event: 'docs_page_view', + docs: { page_title: 'Quickstart | Acme API', page_location: `${quickstart}?utm_source=newsletter` } + } + ]); + expect(page.window.gtag).to.be.undefined; + expect(page.scripts).to.be.empty; + }); + + it('writes to a data layer the page already has', () => { + const page = browser(quickstart); + const existing = { 'host-tag': true }; + page.window.dataLayer = [existing]; + const analytics = new Analytics(none); + + analytics.start(); + analytics.reportPageView(); + + expect(page.dataLayer()).to.deep.equal([existing, { docs: null }, quickstartView]); + }); + }); + + describe('with Google Tag Manager', () => { + it('pushes the gtm.start entry first, inserts gtm.js, then pushes the page view', () => { + const page = browser(quickstart); + const analytics = new Analytics(withGtm()); + + analytics.start(); + analytics.reportPageView(); + + const [start, reset, view, ...rest] = page.dataLayer(); + expect(start).to.have.property('event', 'gtm.js'); + expect(start).to.have.property('gtm.start').that.is.a('number'); + expect(reset).to.deep.equal({ docs: null }); + expect(view).to.deep.equal(quickstartView); + expect(rest).to.be.empty; + expect(page.scripts.map((script) => script.src)).to.deep.equal([GTM_SCRIPT]); + expect(page.scripts[0].async).to.be.true; + expect(page.window.gtag).to.be.undefined; + }); + + it("escapes the container's ID and the environment's values in the tag's address", () => { + const page = browser(quickstart); + const setting = { containerId: 'GTM-A&B', environment: { auth: 'a&b', preview: 'env 3' } }; + + new Analytics({ ...none, googleTagManager: setting }).start(); + + expect(page.scripts.map((script) => script.src)).to.deep.equal([ + 'https://www.googletagmanager.com/gtm.js?id=GTM-A%26B>m_auth=a%26b>m_preview=env%203>m_cookies_win=x' + ]); + }); + + it("loads the container's environment when one is set", () => { + const page = browser(quickstart); + + new Analytics(withGtm({ auth: 'abc123', preview: 'env-3' })).start(); + + expect(page.scripts.map((script) => script.src)).to.deep.equal([ + `${GTM_SCRIPT}>m_auth=abc123>m_preview=env-3>m_cookies_win=x` + ]); + }); + }); + + describe('with Google Analytics', () => { + it('pushes js and config with its own page view off, and inserts gtag.js', () => { + const page = browser(quickstart); + + new Analytics(withGa4).start(); + + const [js, config, ...rest] = gtagCalls(page.dataLayer()); + expect(js[0]).to.equal('js'); + expect(js[1]).to.be.an.instanceOf(Date); + expect(config).to.deep.equal(['config', 'G-ABC123', { send_page_view: false }]); + expect(rest).to.be.empty; + expect(page.scripts.map((script) => script.src)).to.deep.equal([GA4_SCRIPT]); + expect(page.window.gtag).to.be.a('function'); + }); + + it('sends each page view as page_view, without the prefix, after the reset and event entries', () => { + const page = browser(quickstart); + const analytics = new Analytics(withGa4); + + analytics.start(); + analytics.reportPageView(); + + const entries = page.dataLayer(); + expect(entries).to.have.length(6); + expect(entries[2]).to.deep.equal({ docs: null }); + expect(entries[3]).to.deep.equal(quickstartView); + expect(gtagCalls(entries.slice(4))).to.deep.equal([ + ['set', { page_location: quickstart }], + ['event', 'page_view', quickstartView.docs] + ]); + }); + + it("gives GA4's own events the reported address of each page, never the one in the address bar", () => { + const page = browser('https://docs.test/api/pets/listPets?code=x&state=y#access_token=z', 'List pets'); + const analytics = new Analytics(withGa4); + + analytics.start(); + analytics.reportPageView(); + page.go(`${quickstart}?utm_source=mail&tab=python#install`); + analytics.reportPageView(); + analytics.report('docs_markdown_copy', {}); + + expect(gtagCalls(page.dataLayer()).filter((command) => command[0] === 'set')).to.deep.equal([ + ['set', { page_location: 'https://docs.test/api/pets/listPets' }], + ['set', { page_location: `${quickstart}?utm_source=mail` }] + ]); + }); + + it('pushes Arguments objects, which gtag.js reads, never arrays of the same values', () => { + const page = browser(quickstart); + const analytics = new Analytics(withGa4); + + analytics.start(); + analytics.reportPageView(); + + expect(page.dataLayer().filter(isArguments)).to.have.length(4); + expect(page.dataLayer().some(Array.isArray)).to.be.false; + }); + + it("escapes the measurement ID in the tag's address", () => { + const page = browser(quickstart); + + new Analytics({ ...none, googleAnalytics: { measurementId: 'G-A#B' } }).start(); + + expect(page.scripts.map((script) => script.src)).to.deep.equal([ + 'https://www.googletagmanager.com/gtag/js?id=G-A%23B' + ]); + }); + + it('uses a gtag the page already defines, rather than replacing it', () => { + const page = browser(quickstart); + const calls: unknown[][] = []; + const existing = (...command: unknown[]) => { + calls.push(command); + }; + page.window.gtag = existing; + const analytics = new Analytics(withGa4); + + analytics.start(); + analytics.reportPageView(); + + expect(page.window.gtag).to.equal(existing); + expect(calls.map((command) => command[0])).to.deep.equal(['js', 'config', 'set', 'event']); + expect(page.dataLayer().filter(isArguments)).to.be.empty; + }); + + it("sends through the page's gtag from a second instance, as a config save under portal serve makes", () => { + const page = browser(quickstart); + new Analytics(withGa4).start(); + const second = new Analytics(withGa4); + second.start(); + + second.report('docs_markdown_copy', {}); + + expect(gtagCalls(page.dataLayer()).map((command) => command[0])).to.deep.equal(['js', 'config', 'event']); + }); + }); + + describe('with both vendors', () => { + it('pushes every setup entry once, gtm.start first, before the first event', () => { + const page = browser(quickstart); + const analytics = new Analytics(withBoth); + + analytics.start(); + analytics.reportPageView(); + + const entries = page.dataLayer(); + expect(entries).to.have.length(7); + expect(entries[0]).to.have.property('event', 'gtm.js'); + expect(gtagCalls(entries.slice(1, 3)).map((command) => command[0])).to.deep.equal(['js', 'config']); + expect(entries[3]).to.deep.equal({ docs: null }); + expect(entries[4]).to.deep.equal(quickstartView); + expect(gtagCalls(entries.slice(5)).map((command) => command[0])).to.deep.equal(['set', 'event']); + expect(gtagCalls([entries[6]])[0]).to.deep.equal(['event', 'page_view', quickstartView.docs]); + expect(page.scripts.map((script) => script.src)).to.deep.equal([GTM_SCRIPT, GA4_SCRIPT]); + }); + + it('starts once per page, for a second start and for a second instance alike', () => { + const page = browser(quickstart); + const analytics = new Analytics(withBoth); + + analytics.start(); + analytics.start(); + new Analytics(withBoth).start(); + + expect(page.dataLayer()).to.have.length(3); + expect(page.scripts).to.have.length(2); + expect(page.reloads()).to.equal(0); + }); + + it('reloads the page for a start with other vendors, as a config save under portal serve makes', () => { + const page = browser(quickstart); + new Analytics(withGtm()).start(); + + new Analytics(withBoth).start(); + + expect(page.reloads()).to.equal(1); + expect(page.dataLayer()).to.have.length(1); + expect(page.scripts.map((script) => script.src)).to.deep.equal([GTM_SCRIPT]); + }); + }); + + describe('after a playground sign-in', () => { + it('reports with the OAuth answer stripped from page_location', () => { + const page = browser('https://docs.test/api/pets/listPets#access_token=xyz&state=123', 'List pets'); + const analytics = new Analytics(withBoth); + + analytics.start(); + analytics.reportPageView(); + + expect(pageViews(page.dataLayer())).to.deep.equal([ + { + event: 'docs_page_view', + docs: { page_title: 'List pets', page_location: 'https://docs.test/api/pets/listPets' } + } + ]); + }); + }); + + describe('on the page a playground sign-in returned to', () => { + const answered = 'https://docs.test/api/pets/listPets?code=abc&state=123'; + + it('holds the tags back while the answer is in the address, and loads them once the playground took it out', () => { + const page = browser(answered, 'List pets'); + const analytics = new Analytics(withBoth); + + analytics.start(); + analytics.reportPageView(); + analytics.loadTags(); + + expect(page.scripts).to.be.empty; + expect(pageViews(page.dataLayer())).to.have.length(1); + + page.go('https://docs.test/api/pets/listPets'); + analytics.loadTags(); + analytics.reportPageView(); + + expect(page.scripts.map((script) => script.src)).to.deep.equal([GTM_SCRIPT, GA4_SCRIPT]); + expect(pageViews(page.dataLayer())).to.have.length(1); + }); + }); + + describe('on the OAuth callback', () => { + for (const href of [ + 'https://docs.test/oauth/callback?code=abc&state=123', + 'https://docs.test/oauth/callback/?code=abc&state=123', + 'https://docs.test/oauth/callback#access_token=xyz&state=123' + ]) { + it(`holds the tags and the page view back at ${href}, and inserts the tags on the next page`, () => { + const page = browser(href); + const analytics = new Analytics(withBoth); + + analytics.start(); + analytics.reportPageView(); + + expect(page.dataLayer()).to.have.length(3); + expect(pageViews(page.dataLayer())).to.be.empty; + expect(page.scripts).to.be.empty; + + page.go(quickstart); + analytics.reportPageView(); + analytics.reportPageView(); + + expect(page.scripts.map((script) => script.src)).to.deep.equal([GTM_SCRIPT, GA4_SCRIPT]); + expect(pageViews(page.dataLayer())).to.have.length(1); + }); + + it(`sends nothing for any event reported at ${href}`, () => { + const page = browser(href); + const analytics = new Analytics(withBoth); + analytics.start(); + + analytics.report('docs_code_copy', { language: 'cURL' }); + analytics.report('docs_markdown_copy', {}); + + expect(page.dataLayer()).to.have.length(3); + expect(gtagCalls(page.dataLayer()).map((command) => command[0])).to.deep.equal(['js', 'config']); + }); + } + }); + + describe('every adapter', () => { + const suite: { + vendor: keyof typeof adapters; + settings: PortalAnalytics; + pageViewCall: (entries: unknown[]) => void; + }[] = [ + { + vendor: 'googleTagManager', + settings: withGtm(), + // The data layer entry is the call; GTM sends nothing of its own. + pageViewCall: (entries) => expect(entries.filter(isArguments)).to.be.empty + }, + { + vendor: 'googleAnalytics', + settings: withGa4, + pageViewCall: (entries) => expect(gtagCalls(entries).at(-1)?.slice(0, 2)).to.deep.equal(['event', 'page_view']) + } + ]; + + it('is covered by this suite', () => { + expect(suite.map((row) => row.vendor)).to.have.members(Object.keys(adapters)); + }); + + for (const { vendor, settings, pageViewCall } of suite) { + describe(vendor, () => { + const adapter = (): Adapter => adapters[vendor](settings) ?? expect.fail(`${vendor} builds no adapter`); + + it('builds no adapter from settings without its vendor', () => { + expect(adapters[vendor](none)).to.be.null; + }); + + it('turns no session recording or input capture on, nor so much as names them', () => { + browser(quickstart); + const pushed: unknown[] = []; + adapter().setup(pushed); + + // A later adapter that has to name them, to turn them off, says here how it does. + const named = /record|capture|replay/i; + const entries = pushed.map((entry) => (isArguments(entry) ? Array.from(entry as ArrayLike) : entry)); + expect(JSON.stringify(entries)).to.not.match(named); + expect(adapter().script).to.not.match(named); + }); + + it("turns the vendor's own page view off in its setup", () => { + browser(quickstart); + const pushed: unknown[] = []; + + adapter().setup(pushed); + + expect(pushed).to.not.be.empty; + for (const entry of pushed) { + expect(entry).to.not.have.property('event', 'page_view'); + const [command, , options] = isArguments(entry) ? Array.from(entry as ArrayLike) : []; + if (command === 'config') expect(options).to.include({ send_page_view: false }); + } + }); + + it('maps docs_page_view to its page view call', () => { + const page = browser(quickstart); + const analytics = new Analytics(settings); + + analytics.start(); + analytics.reportPageView(); + + expect(pageViews(page.dataLayer())).to.have.length(1); + pageViewCall(page.dataLayer()); + }); + + it('receives nothing holding code=, token= or a # part from a report made with an OAuth answer in the address', () => { + const page = browser('https://docs.test/api/pets/listPets?code=x&state=y#access_token=z', 'List pets'); + const analytics = new Analytics(settings); + + analytics.start(); + analytics.report('docs_page_view', { page_title: 'List pets' }); + + const received = JSON.stringify( + page.dataLayer().map((entry) => (isArguments(entry) ? Array.from(entry as ArrayLike) : entry)) + ); + expect(received).to.include('https://docs.test/api/pets/listPets'); + expect(received).to.not.match(/code=|token=|#/); + }); + + it('inserts only https scripts, none inline', () => { + expect(adapter().script).to.match(/^https:\/\//); + const page = browser(quickstart); + + new Analytics(settings).start(); + + expect(page.scripts).to.not.be.empty; + for (const script of page.scripts) { + expect(script.src).to.match(/^https:\/\//); + expect(script.textContent).to.equal(''); + } + }); + }); + } + }); + + describe('report', () => { + it('pushes a reset entry right before every event entry, which holds event and docs only', () => { + const page = browser(quickstart); + const analytics = new Analytics(none); + analytics.start(); + + analytics.report('docs_page_view', { page_title: 'A' }); + analytics.report('docs_page_view', { page_title: 'B' }); + + const entries = page.dataLayer(); + expect(entries).to.have.length(4); + for (const index of [1, 3]) { + expect(entries[index - 1]).to.deep.equal({ docs: null }); + expect(Object.keys(entries[index] as object)).to.deep.equal(['event', 'docs']); + } + }); + + it("clears the previous event's details for a tag that reads the merged data layer", () => { + const page = browser(quickstart); + const analytics = new Analytics(none); + analytics.start(); + analytics.report('docs_code_copy', { language: 'python' }); + analytics.report('docs_page_view', { page_title: 'B' }); + + expect(mergedLikeGtm(page.dataLayer()).docs).to.deep.equal({ page_title: 'B', page_location: quickstart }); + const withoutResets = page.dataLayer().filter((entry) => !(isPlainObject(entry) && entry.docs === null)); + expect(mergedLikeGtm(withoutResets).docs).to.have.property('language', 'python'); + }); + + it('reports the page the caller names, not the one the address has moved on to', () => { + const page = browser(quickstart); + const analytics = new Analytics(none); + page.go('https://docs.test/guides/authentication'); + + analytics.report( + 'docs_search', + { search_term: 'auth', result: '/guides/authentication', result_count: 3 }, + quickstart + ); + + expect(page.dataLayer().at(-1)).to.have.nested.property('docs.page_location', quickstart); + }); + }); + + // The root effect calls this once on mount and once per page change the router renders. + describe('reportPageView', () => { + const components = 'https://docs.test/guides/components'; + + it('sends the current page, each with its own title', () => { + const page = browser(quickstart); + const analytics = new Analytics(none); + analytics.start(); + + analytics.reportPageView(); + page.go(components, 'Components | Acme API'); + analytics.reportPageView(); + + expect(pageViews(page.dataLayer())).to.deep.equal([ + quickstartView, + { event: 'docs_page_view', docs: { page_title: 'Components | Acme API', page_location: components } } + ]); + }); + + it('sends none when only the # part or the query changed, or nothing changed', () => { + const page = browser(quickstart); + const analytics = new Analytics(none); + analytics.start(); + + analytics.reportPageView(); + page.go(`${quickstart}#install`); + analytics.reportPageView(); + page.go(`${quickstart}?tab=python`); + analytics.reportPageView(); + analytics.reportPageView(); + + expect(pageViews(page.dataLayer())).to.have.length(1); + }); + + it('sends three for A, then B, then A', () => { + const page = browser(quickstart); + const analytics = new Analytics(none); + analytics.start(); + + analytics.reportPageView(); + page.go(components); + analytics.reportPageView(); + page.go(quickstart); + analytics.reportPageView(); + + expect( + pageViews(page.dataLayer()).map((view) => (view as { docs: { page_location: string } }).docs.page_location) + ).to.deep.equal([quickstart, components, quickstart]); + }); + }); + describe('reportNotFound', () => { + const missing = 'https://docs.acme.com/guides/missing'; + const referrers = (entries: unknown[]) => + entries + .filter((entry) => isPlainObject(entry) && entry.event === 'docs_not_found') + .map((entry) => (entry as { docs: { page_referrer: string } }).docs.page_referrer); + + it('names the portal page the reader left for it, whatever the document says', () => { + const page = browser( + 'https://docs.acme.com/guides/quickstart', + 'Quickstart', + 'https://www.google.com/search?q=acme+docs' + ); + const analytics = new Analytics(none); + analytics.reportPageView(); + page.go(missing); + analytics.reportPageView(); + + analytics.reportNotFound(); + + expect(referrers(page.dataLayer())).to.deep.equal(['https://docs.acme.com/guides/quickstart']); + expect(page.dataLayer().at(-1)).to.have.nested.property('docs.page_location', missing); + }); + + it('names the page left when the missing page’s own view is yet to be reported', () => { + const page = browser( + 'https://docs.acme.com/guides/quickstart', + 'Quickstart', + 'https://www.google.com/search?q=acme+docs' + ); + const analytics = new Analytics(none); + analytics.reportPageView(); + page.go(missing); + + analytics.reportNotFound(); + analytics.reportPageView(); + + expect(referrers(page.dataLayer())).to.deep.equal(['https://docs.acme.com/guides/quickstart']); + }); + + it('names the referrer without its query or # part on a first load, and nothing when the browser sends none', () => { + const fromSearch = browser(missing, 'Not found', 'https://www.google.com/search?q=acme+docs#top'); + new Analytics(none).reportNotFound(); + const typedIn = browser(missing, 'Not found'); + new Analytics(none).reportNotFound(); + + expect(referrers(fromSearch.dataLayer())).to.deep.equal(['https://www.google.com/search']); + expect(referrers(typedIn.dataLayer())).to.deep.equal(['']); + }); + + it('reports a missing page once, however often its page mounts, and the next missing page again', () => { + const page = browser(missing); + const analytics = new Analytics(none); + + analytics.reportNotFound(); + analytics.reportNotFound(); + page.go('https://docs.acme.com/guides/also-missing'); + analytics.reportNotFound(); + + expect(referrers(page.dataLayer())).to.deep.equal(['', '']); + }); + + it('reports a missing page again when the reader comes back to it from another page', () => { + const page = browser('https://docs.acme.com/guides/quickstart'); + const analytics = new Analytics(none); + analytics.reportPageView(); + page.go(missing); + analytics.reportNotFound(); + analytics.reportPageView(); + analytics.reportNotFound(); + page.go('https://docs.acme.com/guides/quickstart'); + analytics.reportPageView(); + page.go(missing); + analytics.reportPageView(); + analytics.reportNotFound(); + + expect(referrers(page.dataLayer())).to.deep.equal([ + 'https://docs.acme.com/guides/quickstart', + 'https://docs.acme.com/guides/quickstart' + ]); + expect(pageViews(page.dataLayer())).to.have.length(4); + }); + }); +}); diff --git a/test/portal-template/api-request.test.ts b/test/portal-template/api-request.test.ts new file mode 100644 index 000000000..d8b33d37d --- /dev/null +++ b/test/portal-template/api-request.test.ts @@ -0,0 +1,54 @@ +import { expect } from 'chai'; +import type { FetchErrorResult, FetchResponseResult } from 'fumadocs-openapi/playground'; +import { apiRequest } from '../../portal-template/src/lib/api-request'; + +describe('apiRequest', () => { + const endpoint = 'GET /{operation}'; + // The request's own address, which holds filled-in values: never reported. + const url = 'https://api.acme.com/v1/calc/SUM?x=4&api_key=s3cret'; + const response = (status: number, duration: number): FetchResponseResult => ({ + type: 'response', + url, + status, + headers: new globalThis.Headers({ 'x-key': 's3cret' }), + body: new ArrayBuffer(0), + duration, + text: () => 's3cret' + }); + const clientError: FetchErrorResult = { type: 'client_error', url, message: 'Failed to fetch' }; + + it('reports a response by its status and its own duration, rounded', () => { + expect(apiRequest(endpoint, response(200, 123.4), 1000, 9000)).to.deep.equal({ + endpoint, + status: '200', + duration_ms: 123 + }); + }); + + // One GA4 dimension holds both forms, so a report filters on `status = 500` and on `status = client_error` alike. + it('reports the status as text either way: the HTTP status in digits, or client_error', () => { + for (const status of [200, 204, 404, 500]) { + expect(apiRequest(endpoint, response(status, 1), null, 0).status).to.equal(String(status)); + } + expect(apiRequest(endpoint, clientError, null, 0).status).to.equal('client_error'); + }); + + it('times a request that never reached the API from when it was sent', () => { + expect(apiRequest(endpoint, clientError, 1000, 1250)).to.deep.equal({ + endpoint, + status: 'client_error', + duration_ms: 250 + }); + }); + + it('gives no duration to a request that failed before it was sent', () => { + expect(apiRequest(endpoint, clientError, null, 1250)).to.deep.include({ status: 'client_error', duration_ms: 0 }); + }); + + it('carries the endpoint, the status and the duration, and nothing of the request', () => { + const reported = apiRequest(endpoint, response(401, 8), null, 0); + + expect(Object.keys(reported).sort()).to.deep.equal(['duration_ms', 'endpoint', 'status']); + expect(JSON.stringify(reported)).to.not.contain('s3cret'); + }); +}); diff --git a/test/portal-template/languages.test.ts b/test/portal-template/languages.test.ts new file mode 100644 index 000000000..d726f8c80 --- /dev/null +++ b/test/portal-template/languages.test.ts @@ -0,0 +1,66 @@ +import { expect } from 'chai'; +import { bundledLanguage, languageId, reportedAliases } from '../../portal-template/src/lib/languages'; +import { Language } from '../../src/types/sdk/generate'; + +describe('languageId', () => { + // A download and a copy both send this, so one GA4 dimension holds one set of values. + it('is the key of every language the CLI generates an SDK in', () => { + for (const language of Object.values(Language)) { + expect(languageId(language)).to.equal(language); + } + }); + + it('names a language by its ID, whichever alias the block was written with', () => { + expect(['ts', 'cs', 'c#', 'py', 'bash', 'sh', 'yml'].map(languageId)).to.deep.equal([ + 'typescript', + 'csharp', + 'csharp', + 'python', + 'shellscript', + 'shellscript', + 'yaml' + ]); + }); + + it('reads a name or an alias written in capitals as the same language', () => { + expect(['TypeScript', 'TS', 'C#', 'JSON'].map(languageId)).to.deep.equal([ + 'typescript', + 'typescript', + 'csharp', + 'json' + ]); + }); + + it('sends a language the bundle does not know in lowercase, so one language is one value', () => { + expect(languageId('plaintext')).to.equal('plaintext'); + expect(['rust', 'Rust', 'Kotlin'].map(languageId)).to.deep.equal(['rust', 'rust', 'kotlin']); + }); + + it('names a language outside the bundle by its ID too, whichever short name the block was written with', () => { + expect(['kt', 'KT', 'rs', 'c++', 'ps1', 'dockerfile'].map(languageId)).to.deep.equal([ + 'kotlin', + 'kotlin', + 'rust', + 'cpp', + 'powershell', + 'docker' + ]); + }); + + // A page's own block in no language reports `plaintext`; a description's reports `text`. + it('reports a block in no language as plaintext, by any of the names Shiki has for it', () => { + expect(['text', 'txt', 'plain', 'plaintext'].map(languageId)).to.deep.equal(Array(4).fill('plaintext')); + }); + + it('gives each short name outside the bundle the ID Shiki gives it, and shadows no bundled name', async () => { + const { bundledLanguagesInfo } = (await import('shiki/bundle/full')) as { + bundledLanguagesInfo: { id: string; aliases?: string[] }[]; + }; + + for (const [alias, id] of Object.entries(reportedAliases)) { + expect(bundledLanguage(alias), alias).to.be.null; + if (id === 'plaintext') continue; + expect(bundledLanguagesInfo.find((entry) => entry.id === id)?.aliases, `${alias} for ${id}`).to.include(alias); + } + }); +}); diff --git a/test/portal-template/oauth-callback.test.ts b/test/portal-template/oauth-callback.test.ts index a370e8dc1..7d016570b 100644 --- a/test/portal-template/oauth-callback.test.ts +++ b/test/portal-template/oauth-callback.test.ts @@ -1,7 +1,13 @@ import { expect } from 'chai'; import type { SecuritySchemeObject } from 'fumadocs-openapi'; import { requestOAuthToken } from 'fumadocs-openapi/playground'; -import { oauthCallback, oauthCallbackPath, takeStartingPage } from '../../portal-template/src/lib/oauth-callback'; +import { + holdsOAuthAnswer, + isOAuthCallbackPath, + oauthCallback, + oauthCallbackPath, + takeStartingPage +} from '../../portal-template/src/lib/oauth-callback'; import { OAUTH_CALLBACK_ADDRESS } from '../../src/types/portal/content-tree'; // The CLI refuses a page of the user's at the address the template serves the callback at. @@ -16,6 +22,45 @@ describe('oauthCallbackPath', () => { * callback takes the note from the same place. The playground's flow is run here, in a stand-in * tab, so a move of the note, as 12.5.7 made from a cookie, fails this test and not a portal. */ +describe('isOAuthCallbackPath', () => { + it('is the callback at the root, and under a base path', () => { + expect(isOAuthCallbackPath('/oauth/callback')).to.be.true; + expect(isOAuthCallbackPath('/docs/oauth/callback', '/docs/')).to.be.true; + }); + + // A static host may answer `/oauth/callback` at `/oauth/callback/`. + it('is the callback with a trailing slash', () => { + expect(isOAuthCallbackPath('/oauth/callback/')).to.be.true; + expect(isOAuthCallbackPath('/docs/oauth/callback/', '/docs/')).to.be.true; + }); + + it('is not the callback at the root when the portal is under a base path, nor any other page', () => { + expect(isOAuthCallbackPath('/oauth/callback', '/docs/')).to.be.false; + expect(isOAuthCallbackPath('/guides/quickstart')).to.be.false; + expect(isOAuthCallbackPath('/oauth/callback/more')).to.be.false; + }); +}); + +describe('holdsOAuthAnswer', () => { + const at = (href: string) => holdsOAuthAnswer(new URL(href)); + + it('holds on the callback, with or without an answer', () => { + expect(at('https://docs.test/oauth/callback')).to.be.true; + expect(at('https://docs.test/oauth/callback?code=abc&state=123')).to.be.true; + }); + + it('holds on a page a sign-in returned to, with a code, a token or an error', () => { + expect(at('https://docs.test/api/pets/listPets?code=abc&state=123')).to.be.true; + expect(at('https://docs.test/api/pets/listPets#access_token=xyz&token_type=Bearer&state=123')).to.be.true; + expect(at('https://docs.test/api/pets/listPets?error=access_denied&state=123')).to.be.true; + }); + + it('does not hold on any other address, a query or a # part of its own included', () => { + expect(at('https://docs.test/api/pets/listPets')).to.be.false; + expect(at('https://docs.test/guides/quickstart?utm_source=mail&code=SAVE10#install')).to.be.false; + }); +}); + describe('takeStartingPage', () => { const origin = 'https://docs.test'; const pathname = '/api/pets/pets/listPets'; diff --git a/test/portal-template/search-report.test.ts b/test/portal-template/search-report.test.ts new file mode 100644 index 000000000..31fa82466 --- /dev/null +++ b/test/portal-template/search-report.test.ts @@ -0,0 +1,64 @@ +import { expect } from 'chai'; +import { searchOutcome, type SearchDialogState } from '../../portal-template/src/lib/search-report'; + +describe('searchOutcome', () => { + const closed: SearchDialogState = { + open: false, + loading: false, + typed: true, + picked: '', + term: 'pets', + resultCount: 3 + }; + + it('waits while the dialog is open, and while the last keystrokes’ results load after it closed', () => { + expect(searchOutcome({ ...closed, open: true })).to.deep.equal({ ended: false }); + expect(searchOutcome({ ...closed, loading: true })).to.deep.equal({ ended: false }); + }); + + it('reports a typed term with the count shown once the results are in', () => { + expect(searchOutcome(closed)).to.deep.equal({ + ended: true, + report: { search_term: 'pets', result: '', result_count: 3 } + }); + }); + + // Fumadocs hands over the pick before the close renders, so a pick made with the hotkey's term counts too. + it('reports the result picked, typed or not', () => { + const picked = 'https://docs.acme.com/api/pets/listPets'; + + expect(searchOutcome({ ...closed, typed: false, picked })).to.deep.equal({ + ended: true, + report: { search_term: 'pets', result: picked, result_count: 3 } + }); + }); + + // Every event's page_location has this shape, so a report can join a search to the page it led to. + it('reports the result as a whole address, without the # part of a heading hit', () => { + const picked = 'https://docs.acme.com/docs/guides/intro#install'; + + expect(searchOutcome({ ...closed, picked })).to.have.nested.property( + 'report.result', + 'https://docs.acme.com/docs/guides/intro' + ); + }); + + it('ends without a report when the reader neither typed nor picked, or left no term', () => { + expect(searchOutcome({ ...closed, typed: false })).to.deep.equal({ ended: true, report: null }); + expect(searchOutcome({ ...closed, term: ' ' })).to.deep.equal({ ended: true, report: null }); + }); + + it('reports the term without the spaces around it', () => { + expect(searchOutcome({ ...closed, term: ' list pets ' })).to.have.nested.property( + 'report.search_term', + 'list pets' + ); + }); + + it('reports at most the 100 characters of a term that GA4 keeps', () => { + expect(searchOutcome({ ...closed, term: 'k'.repeat(300) })).to.have.nested.property( + 'report.search_term', + 'k'.repeat(100) + ); + }); +}); diff --git a/test/prompts/portal/prepare-project.test.ts b/test/prompts/portal/prepare-project.test.ts index 419d40e96..7dacc65f7 100644 --- a/test/prompts/portal/prepare-project.test.ts +++ b/test/prompts/portal/prepare-project.test.ts @@ -12,6 +12,19 @@ describe('PreparePortalProjectPrompts', () => { sinon.restore(); }); + it('says what to turn off in GA4, where, and why', () => { + const warn = sinon.stub(log, 'warn'); + + new PreparePortalProjectPrompts().googleAnalyticsCountsPageChanges(); + + expect(stripVTControlCharacters(String(warn.firstCall.args[0]))).to.equal( + "Google Analytics is set, so the portal sends its own page views. In GA4, turn off the stream's " + + '"Page changes based on browser history events" (Admin → Data streams → your stream → Enhanced ' + + 'measurement → Page views → advanced settings), or every page change counts twice. ' + + 'See the analytics page on https://docs.apimatic.io/v4/.' + ); + }); + // A run delivers everything or nothing, so a gap is the server's to fix. it('names what the artifacts left out, and says to try again', () => { const error = sinon.stub(log, 'error'); diff --git a/test/types/apimatic-config/schema.test.ts b/test/types/apimatic-config/schema.test.ts index 4626ee62e..14718590d 100644 --- a/test/types/apimatic-config/schema.test.ts +++ b/test/types/apimatic-config/schema.test.ts @@ -99,7 +99,13 @@ describe('apimatic.schema.json', () => { { label: 'Home', url: '/' } ] }, - ai: { pageActions: false } + ai: { pageActions: false }, + analytics: { + googleTagManager: { containerId: 'GTM-ABC123', environment: { auth: 'abc', preview: 'env-3' } }, + googleAnalytics: { measurementId: 'G-ABC123' }, + keepQueryParams: ['campaign_id'] + }, + seo: { googleSiteVerification: 'abc' } } ], ['an address with a port', { site: { url: 'https://docs.example.com:8443' } }], @@ -117,7 +123,37 @@ describe('apimatic.schema.json', () => { ['a link through a parent segment', { navigation: { links: [{ label: 'Start', url: '/guides/../start' }] } }], ['a link with two slashes in its query', { navigation: { links: [{ label: 'Next', url: '/start?next=//x' }] } }], ['a context plugin hosted elsewhere', { pluginUrl: 'https://plugins.acme.test/calc.zip?v=2' }], - ['a plugin address with several query parameters', { pluginUrl: 'https://s3.test/calc.zip?a=1&b=2' }] + ['a plugin address with several query parameters', { pluginUrl: 'https://s3.test/calc.zip?a=1&b=2' }], + ['a GTM container', { analytics: { googleTagManager: { containerId: 'GTM-ABC123' } } }], + [ + 'a GTM container with an environment', + { + analytics: { googleTagManager: { containerId: 'GTM-ABC123', environment: { auth: 'abc', preview: 'env-3' } } } + } + ], + ['a GA4 stream', { analytics: { googleAnalytics: { measurementId: 'G-ABC123' } } }], + [ + 'both vendors, with spaces around the IDs', + { + analytics: { + googleTagManager: { containerId: ' GTM-ABC123 ' }, + googleAnalytics: { measurementId: ' G-ABC123 ' } + } + } + ], + ['a kept query parameter name', { analytics: { keepQueryParams: ['campaign_id'] } }], + ['an empty analytics block', { analytics: {} }], + ['a verification value', { seo: { googleSiteVerification: 'abc_123-XYZ' } }], + // The vendors' formats are theirs to check, so each ID and value is any non-blank string. + ['a lowercase container ID', { analytics: { googleTagManager: { containerId: 'gtm-abc123' } } }], + [ + 'an environment value with a space, and a preview without env-', + { analytics: { googleTagManager: { containerId: 'GTM-1', environment: { auth: 'a b', preview: '3' } } } } + ], + ['a Universal Analytics ID as the measurement ID', { analytics: { googleAnalytics: { measurementId: 'UA-1' } } }], + ['a kept name with a space, and an OAuth answer name', { analytics: { keepQueryParams: ['a b', 'code'] } }], + ['an empty list of kept names', { analytics: { keepQueryParams: [] } }], + ['a verification value with a space', { seo: { googleSiteVerification: 'abc 123' } }] ]; const invalid: [string, object][] = [ @@ -219,7 +255,41 @@ describe('apimatic.schema.json', () => { ['a plugin address without a host', { pluginUrl: 'https://' }], ['a plugin address that is not a string', { pluginUrl: 7 }], ['a plugin address with a space', { pluginUrl: 'https://plugins.acme.test/my plugin.zip' }], - ['a plugin address with trailing whitespace', { pluginUrl: 'https://plugins.acme.test/calc.zip ' }] + ['a plugin address with trailing whitespace', { pluginUrl: 'https://plugins.acme.test/calc.zip ' }], + ['analytics that is not an object', { analytics: 'GTM-ABC123' }], + ['an unknown vendor', { analytics: { posthog: {} } }], + ['a bare container ID', { analytics: { googleTagManager: 'GTM-ABC123' } }], + ['a GTM block without its ID', { analytics: { googleTagManager: {} } }], + ['a blank container ID', { analytics: { googleTagManager: { containerId: ' ' } } }], + [ + 'a key beside the container ID', + { analytics: { googleTagManager: { containerId: 'GTM-ABC123', serverUrl: 'x' } } } + ], + [ + 'an environment that is not an object', + { analytics: { googleTagManager: { containerId: 'GTM-ABC123', environment: 'env-3' } } } + ], + [ + 'an environment without its preview', + { analytics: { googleTagManager: { containerId: 'GTM-ABC123', environment: { auth: 'abc' } } } } + ], + ['a GA4 block without its ID', { analytics: { googleAnalytics: {} } }], + ['a measurement ID that is not a string', { analytics: { googleAnalytics: { measurementId: 7 } } }], + ['kept names that are not a list', { analytics: { keepQueryParams: 'campaign_id' } }], + ['a kept name that is not a string', { analytics: { keepQueryParams: [1] } }], + ['seo that is not an object', { seo: 'abc' }], + ['analytics that is null', { analytics: null }], + [ + 'an environment without its auth', + { analytics: { googleTagManager: { containerId: 'GTM-ABC123', environment: { preview: 'env-3' } } } } + ], + [ + 'a GA4 block with a key beside the ID', + { analytics: { googleAnalytics: { measurementId: 'G-ABC123', debug: true } } } + ], + ['a blank kept name', { analytics: { keepQueryParams: [' '] } }], + ['an unknown seo key', { seo: { foo: 1 } }], + ['a blank verification value', { seo: { googleSiteVerification: ' ' } }] ]; for (const [label, block] of valid) { diff --git a/test/types/portal-source-context.test.ts b/test/types/portal-source-context.test.ts index 27d6e4998..cc3c6f4b3 100644 --- a/test/types/portal-source-context.test.ts +++ b/test/types/portal-source-context.test.ts @@ -49,7 +49,7 @@ describe('PortalSourceContext', () => { const REQUIRED_LANGUAGES = /^'languages' must name at least one SDK language/; - const resolve = () => new PortalSourceContext(new DirectoryPath(root)).resolve(); + const resolve = () => new PortalSourceContext(new DirectoryPath(root)).resolve({ analytics: true }); /** The ignored navigation files as the warning names them, relative to the source directory. */ const ignored = (source: PortalSource): string[] => @@ -349,7 +349,7 @@ describe('PortalSourceContext', () => { writeConfig({ brand: { colors: { primary: '#1d4ed8' } } }); const resolved = (await resolve())._unsafeUnwrap(); - const reloaded = (await context().resolveSettings(resolved.suggestedSite))._unsafeUnwrap(); + const reloaded = (await context().resolveSettings(resolved.suggestedSite, { analytics: true }))._unsafeUnwrap(); expect(reloaded.config.toJSON()).to.deep.equal(resolved.config.toJSON()); expect(reloaded.config.siteTitle()).to.equal(resolved.config.siteTitle()); @@ -359,7 +359,7 @@ describe('PortalSourceContext', () => { it('holds the file to the rules resolve holds it to', async () => { writeConfig({}); - const errors = (await context().resolveSettings(null))._unsafeUnwrapErr(); + const errors = (await context().resolveSettings(null, { analytics: true }))._unsafeUnwrapErr(); expect(errors).to.deep.equal({ kind: 'invalidConfig', @@ -371,13 +371,39 @@ describe('PortalSourceContext', () => { it('reports a file the block names that is not on disk', async () => { writeConfig({ site: { name: 'Calc' }, brand: { favicon: 'static/favicon.ico' } }); - expect(missingFiles(await context().resolveSettings(null))).to.deep.equal([ + expect(missingFiles(await context().resolveSettings(null, { analytics: true }))).to.deep.equal([ ['portal.brand.favicon', 'static/favicon.ico', null] ]); }); + it('leaves out the vendor tags under --no-analytics, as resolve does, and keeps the query names to keep', async () => { + writeConfig({ + site: { name: 'Calc' }, + analytics: { googleTagManager: { containerId: 'GTM-ABC123' }, keepQueryParams: ['campaign_id'] } + }); + const off = { analytics: false }; + + const resolved = (await new PortalSourceContext(new DirectoryPath(root)).resolve(off))._unsafeUnwrap(); + const reloaded = (await context().resolveSettings(null, off))._unsafeUnwrap(); + const kept = (await context().resolveSettings(null, { analytics: true }))._unsafeUnwrap(); + + for (const { config } of [resolved, reloaded]) { + expect(config.identity().analytics).to.deep.equal({ + googleTagManager: null, + googleAnalytics: null, + keepQueryParams: ['campaign_id'] + }); + } + expect(kept.config.identity().analytics.googleTagManager).to.deep.equal({ + containerId: 'GTM-ABC123', + environment: null + }); + }); + it('reports a file removed while the preview runs', async () => { - expect((await context().resolveSettings(null))._unsafeUnwrapErr()).to.deep.equal({ kind: 'missingConfig' }); + expect((await context().resolveSettings(null, { analytics: true }))._unsafeUnwrapErr()).to.deep.equal({ + kind: 'missingConfig' + }); }); }); @@ -1531,7 +1557,9 @@ describe('PortalSourceContext', () => { // Named, because nothing suggests a site when the specifications are not read again. writeFile({ portal: { site: { name: 'Calc' } }, languages: { csharp: {} }, plugin: {} }); - const reloaded = (await new PortalSourceContext(new DirectoryPath(root)).resolveSettings(null))._unsafeUnwrap(); + const reloaded = ( + await new PortalSourceContext(new DirectoryPath(root)).resolveSettings(null, { analytics: true }) + )._unsafeUnwrap(); expect(generated(reloaded)).to.deep.equal(['sdks/index.mdx', 'sdks/csharp.mdx', 'context-plugin/index.mdx']); }); @@ -2601,11 +2629,11 @@ describe('PortalSourceContext', () => { it('writes a source directory it accepts itself, once a language is named', async () => { await scaffold(writeSpec({ title: 'Petstore', version: '1' })); - const unnamed = (await new PortalSourceContext(source).resolve())._unsafeUnwrapErr(); + const unnamed = (await new PortalSourceContext(source).resolve({ analytics: true }))._unsafeUnwrapErr(); expect(unnamed.kind === 'invalidConfig' ? unnamed.errors : []).to.have.lengthOf(1); addLanguages(); - const resolved = (await new PortalSourceContext(source).resolve())._unsafeUnwrap(); + const resolved = (await new PortalSourceContext(source).resolve({ analytics: true }))._unsafeUnwrap(); expect(resolved.config.siteTitle()).to.equal('Petstore'); expect(resolved.specs.map((spec) => spec.slug)).to.deep.equal(['petstore']); expect(resolved.contentDirectory).to.not.be.null; @@ -2630,10 +2658,10 @@ describe('PortalSourceContext', () => { it('writes a block that resolves to the portal an empty block makes', async () => { await scaffold(writeSpec({ title: 'Petstore', version: '1', description: 'All the pets.' })); addLanguages(); - const scaffolded = (await new PortalSourceContext(source).resolve())._unsafeUnwrap().config; + const scaffolded = (await new PortalSourceContext(source).resolve({ analytics: true }))._unsafeUnwrap().config; write('project/src/apimatic.json', JSON.stringify({ portal: {}, languages: LANGUAGES })); - const empty = (await new PortalSourceContext(source).resolve())._unsafeUnwrap().config; + const empty = (await new PortalSourceContext(source).resolve({ analytics: true }))._unsafeUnwrap().config; expect(scaffolded.toJSON()).to.deep.equal(empty.toJSON()); expect(scaffolded.identity()).to.deep.equal(empty.identity()); @@ -2671,7 +2699,7 @@ describe('PortalSourceContext', () => { addLanguages(); const contentFiles = fs.readdirSync(path.join(source.toString(), 'content')).sort(); - const scaffolded = (await new PortalSourceContext(source).resolve())._unsafeUnwrap(); + const scaffolded = (await new PortalSourceContext(source).resolve({ analytics: true }))._unsafeUnwrap(); expect(contentFiles).to.deep.equal(['index.md', 'nav.json']); expect(scaffolded.contentNotices.ignoredNavigationFiles).to.deep.equal([]); @@ -2788,7 +2816,7 @@ describe('PortalSourceContext', () => { await adopt(); - const resolved = (await new PortalSourceContext(source).resolve())._unsafeUnwrap(); + const resolved = (await new PortalSourceContext(source).resolve({ analytics: true }))._unsafeUnwrap(); expect(resolved.config.siteTitle()).to.equal('Petstore'); // The one that was there, and no copy of it beside itself. expect(fs.readdirSync(path.join(source.toString(), 'spec'))).to.deep.equal(['petstore.json']); @@ -2901,7 +2929,7 @@ describe('PortalSourceContext', () => { await adopt(); expect(portalBlock().site.name).to.equal(name); - const resolved = (await new PortalSourceContext(source).resolve())._unsafeUnwrap(); + const resolved = (await new PortalSourceContext(source).resolve({ analytics: true }))._unsafeUnwrap(); expect(resolved.config.siteTitle()).to.equal(name); }); }); @@ -2920,7 +2948,7 @@ describe('PortalSourceContext', () => { await adopt(); expect(portalBlock().site.name).to.equal('Alpha'); - expect((await new PortalSourceContext(source).resolve()).isOk()).to.be.true; + expect((await new PortalSourceContext(source).resolve({ analytics: true })).isOk()).to.be.true; }); }); }); diff --git a/test/types/portal/portal-config.test.ts b/test/types/portal/portal-config.test.ts index 6f0e692f3..d90e1cbce 100644 --- a/test/types/portal/portal-config.test.ts +++ b/test/types/portal/portal-config.test.ts @@ -395,6 +395,178 @@ describe('PortalConfig', () => { }); }); + describe('analytics', () => { + const gtm = 'portal.analytics.googleTagManager'; + const ga = 'portal.analytics.googleAnalytics'; + const keep = 'portal.analytics.keepQueryParams'; + + it('tells the browser to load nothing when the block sets nothing', () => { + expect(config({}).identity().analytics).to.deep.equal({ + googleTagManager: null, + googleAnalytics: null, + keepQueryParams: [] + }); + }); + + it('keeps both vendors with their IDs trimmed, the environment and every kept name, an OAuth answer’s included', () => { + const analytics = { + googleTagManager: { containerId: ' GTM-ABC123 ', environment: { auth: 'a1_b-2', preview: 'env-3' } }, + googleAnalytics: { measurementId: ' G-ABC123 ' }, + keepQueryParams: ['campaign_id', ' code '] + }; + + expect(config({ analytics }).identity().analytics).to.deep.equal({ + googleTagManager: { containerId: 'GTM-ABC123', environment: { auth: 'a1_b-2', preview: 'env-3' } }, + googleAnalytics: { measurementId: 'G-ABC123' }, + keepQueryParams: ['campaign_id', 'code'] + }); + }); + + it('refuses a block, a vendor or an environment that is not an object, as a bare ID is the likely slip', () => { + expect(errorsOf({ analytics: 'GTM-ABC123' })).to.deep.equal(["'portal.analytics' must be a JSON object."]); + expect(errorsOf({ analytics: { googleTagManager: 'GTM-ABC123' } })).to.deep.equal([ + `'${gtm}' must be a JSON object with 'containerId'.` + ]); + expect(errorsOf({ analytics: { googleAnalytics: 'G-ABC123' } })).to.deep.equal([ + `'${ga}' must be a JSON object with 'measurementId'.` + ]); + expect( + errorsOf({ analytics: { googleTagManager: { containerId: 'GTM-ABC123', environment: 'env-3' } } }) + ).to.deep.equal([`'${gtm}.environment' must be a JSON object with 'auth' and 'preview'.`]); + }); + + it('requires each ID as a non-empty string, and leaves its format to the vendor', () => { + expect(errorsOf({ analytics: { googleTagManager: {}, googleAnalytics: {} } })).to.deep.equal([ + `'${gtm}.containerId' is required.`, + `'${ga}.measurementId' is required.` + ]); + expect( + errorsOf({ analytics: { googleTagManager: { containerId: ' ' }, googleAnalytics: { measurementId: 1 } } }) + ).to.deep.equal([ + `'${gtm}.containerId' must be a non-empty string.`, + `'${ga}.measurementId' must be a non-empty string.` + ]); + expect( + config({ analytics: { googleTagManager: { containerId: 'gtm-abc123' } } }).identity().analytics.googleTagManager + ).to.deep.equal({ containerId: 'gtm-abc123', environment: null }); + }); + + it('requires both environment values as non-empty strings', () => { + const withEnvironment = (environment: unknown) => + errorsOf({ analytics: { googleTagManager: { containerId: 'GTM-ABC123', environment } } }); + + expect(withEnvironment({})).to.deep.equal([ + `'${gtm}.environment.auth' is required.`, + `'${gtm}.environment.preview' is required.` + ]); + expect(withEnvironment({ auth: '', preview: 3 })).to.deep.equal([ + `'${gtm}.environment.auth' must be a non-empty string.`, + `'${gtm}.environment.preview' must be a non-empty string.` + ]); + }); + + it('names an unknown key beside a vendor or an environment like any other', () => { + expect( + errorsOf({ + analytics: { + posthog: {}, + googleTagManager: { + containerId: 'GTM-ABC123', + serverUrl: 'x', + environment: { auth: 'a', preview: 'env-1', url: 'x' } + }, + googleAnalytics: { measurementId: 'G-ABC123', debug: true } + } + }) + ).to.deep.equal([ + "'portal.analytics.posthog' is not a 'portal' setting.", + `'${gtm}.serverUrl' is not a 'portal' setting.`, + `'${gtm}.environment.url' is not a 'portal' setting.`, + `'${ga}.debug' is not a 'portal' setting.` + ]); + }); + + it('takes a list of kept names, each a non-empty string', () => { + expect(errorsOf({ analytics: { keepQueryParams: 'campaign_id' } })).to.deep.equal([ + `'${keep}' must be a list of query parameter names.` + ]); + expect(errorsOf({ analytics: { keepQueryParams: ['', ' ', 1] } })).to.deep.equal([ + `'${keep}[0]' must be a non-empty string.`, + `'${keep}[1]' must be a non-empty string.`, + `'${keep}[2]' must be a non-empty string.` + ]); + }); + + it('reports every fault at once, unknown keys first', () => { + expect( + errorsOf({ + analytics: { + posthog: {}, + googleTagManager: { containerId: '' }, + googleAnalytics: 'G-1', + keepQueryParams: [1] + } + }) + ).to.deep.equal([ + "'portal.analytics.posthog' is not a 'portal' setting.", + `'${gtm}.containerId' must be a non-empty string.`, + `'${ga}' must be a JSON object with 'measurementId'.`, + `'${keep}[0]' must be a non-empty string.` + ]); + }); + + it('tells the browser to load neither vendor without them, and still which names to keep', () => { + const analytics = { + googleTagManager: { containerId: 'GTM-ABC123' }, + googleAnalytics: { measurementId: 'G-ABC123' }, + keepQueryParams: ['campaign_id'] + }; + const portal = config({ analytics }); + + expect(portal.withoutVendors().identity()).to.deep.equal({ + ...portal.identity(), + analytics: { googleTagManager: null, googleAnalytics: null, keepQueryParams: ['campaign_id'] } + }); + }); + + it('refuses a null block, and an environment without its auth value', () => { + expect(errorsOf({ analytics: null })).to.deep.equal(["'portal.analytics' must be a JSON object."]); + expect( + errorsOf({ analytics: { googleTagManager: { containerId: 'GTM-ABC123', environment: { preview: 'env-3' } } } }) + ).to.deep.equal([`'${gtm}.environment.auth' is required.`]); + }); + + it('keeps an empty list of names as none', () => { + expect(config({ analytics: { keepQueryParams: [] } }).identity().analytics.keepQueryParams).to.deep.equal([]); + }); + + it('uses Google Analytics only with a measurement ID', () => { + expect(config({}).usesGoogleAnalytics()).to.be.false; + expect(config({ analytics: { googleTagManager: { containerId: 'GTM-ABC123' } } }).usesGoogleAnalytics()).to.be + .false; + expect(config({ analytics: { googleAnalytics: { measurementId: 'G-ABC123' } } }).usesGoogleAnalytics()).to.be + .true; + }); + }); + + describe('seo', () => { + it('carries the verification value to the browser, or null without one', () => { + expect(config({ seo: { googleSiteVerification: 'abc_123-XYZ' } }).identity().seo).to.deep.equal({ + googleSiteVerification: 'abc_123-XYZ' + }); + expect(config({}).identity().seo).to.deep.equal({ googleSiteVerification: null }); + }); + + it('refuses a block that is not an object, and a blank value', () => { + expect(errorsOf({ seo: 'abc' })).to.deep.equal(["'portal.seo' must be a JSON object."]); + expect(errorsOf({ seo: null })).to.deep.equal(["'portal.seo' must be a JSON object."]); + expect(errorsOf({ seo: { foo: 1 } })).to.deep.equal(["'portal.seo.foo' is not a 'portal' setting."]); + expect(errorsOf({ seo: { googleSiteVerification: ' ' } })).to.deep.equal([ + "'portal.seo.googleSiteVerification' must be a non-empty string." + ]); + }); + }); + describe('pluginUrl', () => { const REFUSED = "'portal.pluginUrl' must be an address starting with 'https://', with no spaces, for example " + @@ -486,7 +658,9 @@ describe('PortalConfig', () => { { label: 'Status', url: 'https://status.example.com', external: true }, { label: 'Changelog', url: '/changelog', external: false } ], - pageActions: false + pageActions: false, + analytics: { googleTagManager: null, googleAnalytics: null, keepQueryParams: [] }, + seo: { googleSiteVerification: null } }); }); @@ -499,7 +673,9 @@ describe('PortalConfig', () => { favicon: null, colorMode: 'both', links: [], - pageActions: true + pageActions: true, + analytics: { googleTagManager: null, googleAnalytics: null, keepQueryParams: [] }, + seo: { googleSiteVerification: null } }); });