|
| 1 | +import { JSX, ParameterType } from "typedoc"; |
| 2 | + |
| 3 | +const optionSiteId = "rybbitSiteId"; |
| 4 | +const optionScriptSrc = "rybbitScriptSrc"; |
| 5 | + |
| 6 | +/** |
| 7 | + * @param {import("typedoc").Application} app |
| 8 | + */ |
| 9 | +export function load(app) { |
| 10 | + |
| 11 | + // Rybbit Analytics support. |
| 12 | + // Replaces the previous Plausible plugin. Rybbit auto-tracks pageviews |
| 13 | + // (so "which page was viewed" is captured out of the box). Sites are |
| 14 | + // identified by data-site-id, not by domain. |
| 15 | + |
| 16 | + app.options.addDeclaration({ |
| 17 | + name: optionSiteId, |
| 18 | + type: ParameterType.String, |
| 19 | + help: `Rybbit Analytics site id (data-site-id). Leave empty to disable.`, |
| 20 | + }); |
| 21 | + app.options.addDeclaration({ |
| 22 | + name: optionScriptSrc, |
| 23 | + type: ParameterType.String, |
| 24 | + help: `URL of the Rybbit Analytics tracking script.`, |
| 25 | + defaultValue: "https://analytics-2.needle.tools/api/script.js", |
| 26 | + }); |
| 27 | + |
| 28 | + app.renderer.hooks.on("head.end", (ctx) => { |
| 29 | + |
| 30 | + const siteId = ctx.options.getValue(optionSiteId); |
| 31 | + if (typeof siteId !== "string") { |
| 32 | + throw TypeError( |
| 33 | + `Unexpected ${optionSiteId} type: ${JSON.stringify(siteId)}`, |
| 34 | + ); |
| 35 | + } |
| 36 | + if (siteId === "") { |
| 37 | + // No site specified -> disable analytics. |
| 38 | + return JSX.createElement(JSX.Fragment, {}); |
| 39 | + } |
| 40 | + const scriptSrc = ctx.options.getValue(optionScriptSrc); |
| 41 | + |
| 42 | + return [ |
| 43 | + JSX.createElement("script", { |
| 44 | + defer: true, |
| 45 | + src: scriptSrc, |
| 46 | + "data-site-id": siteId, |
| 47 | + }), |
| 48 | + // Rybbit auto-tracks the pageview for the current path, which already |
| 49 | + // tells us which API page was viewed. In addition we fire a custom |
| 50 | + // event carrying the page (normalized, without the version segment) |
| 51 | + // and the engine version, so we keep a per-version breakdown. |
| 52 | + JSX.createElement("script", null, JSX.createElement(JSX.Raw, { |
| 53 | + html: ` |
| 54 | + // The API docs URL has this form: |
| 55 | + // /docs/api/@needle-tools/engine/3.48.3/<actually interesting part> |
| 56 | + // so we extract the interesting part and the version. |
| 57 | + window.addEventListener("load", function () { |
| 58 | + try { |
| 59 | + if (!window.rybbit || typeof window.rybbit.event !== "function") return; |
| 60 | + const parts = window.location.pathname.split("/"); |
| 61 | + // find index of the part that looks like a version (contains two dots and the first two parts are numbers) |
| 62 | + const versionIndex = parts.findIndex((part) => { |
| 63 | + const subParts = part.split("."); |
| 64 | + return subParts.length === 3 && !isNaN(subParts[0]) && !isNaN(subParts[1]); |
| 65 | + }); |
| 66 | + if (versionIndex === -1) return; |
| 67 | + let page = parts.slice(versionIndex + 1).join("/"); |
| 68 | + if (page.startsWith("/")) page = page.slice(1); |
| 69 | + const version = parts[versionIndex]; |
| 70 | + console.debug("Rybbit api-pageview", { page, version }); |
| 71 | + window.rybbit.event("api-pageview", { page: page || "index", version }); |
| 72 | + } catch (e) { |
| 73 | + console.debug("Rybbit api-pageview error", e); |
| 74 | + } |
| 75 | + }); |
| 76 | +` |
| 77 | + })), |
| 78 | + ]; |
| 79 | + }); |
| 80 | +} |
0 commit comments