Keep page feedback from readers who decline cookies

.github/workflows/build-docs.yml

@@ -81,8 +81,17 @@ jobs:
       - name: Test C API 404 fallback
         run: yarn test:not-found
 
+      # This build checks the site; it does not publish it. On the main branch
+      # it gets the feedback widget's fallback endpoint so the check covers the
+      # configuration the published site runs with. Pull-request builds (whose
+      # ref is refs/pull/...) get empty values, which disable the fallback; the
+      # widget still works without it. The published site gets its values from
+      # the job that publishes it.
       - name: Build documentation
         run: yarn build
+        env:
+          DOCS_FEEDBACK_ENDPOINT: ${{ github.ref == 'refs/heads/main' && vars.DOCS_FEEDBACK_ENDPOINT || '' }}
+          DOCS_FEEDBACK_TOKEN: ${{ github.ref == 'refs/heads/main' && secrets.DOCS_FEEDBACK_TOKEN || '' }}
 
       # Asserts what the widget actually sends to Algolia: the API reference is
       # reachable on the served version and absent on frozen legacy versions.

.github/workflows/docs-preview.yml

@@ -31,6 +31,9 @@ jobs:
       - name: Install dependencies
         run: yarn install --frozen-lockfile
 
+      # DOCS_FEEDBACK_ENDPOINT / DOCS_FEEDBACK_TOKEN are deliberately NOT set
+      # here: a preview must not post reader feedback into the production
+      # feedback sheet. preview_build also forces them off in the config.
       - name: Build documentation
         run: yarn build
         env:

docusaurus.config.ts

@@ -1008,6 +1008,22 @@ const config: Config = {
   // The search widget's whole view of docusaurus_tag, derived above and passed
   // through so SearchBar never constructs one of these strings itself.
   customFields: {
+    // The Apps Script Web App that receives feedback from readers on whose
+    // page PostHog is not loaded -- it is loaded behind the cookie banner, so
+    // their comments reached nothing at all. Empty disables the fallback and
+    // the widget behaves exactly as it did before.
+    //
+    // Set from the environment so a redeploy of the Web App (which changes the
+    // URL) needs no code change, and so a fork or a preview build does not
+    // silently post into the production sheet. The job that publishes the
+    // production site sets it; every other build leaves it unset, and a
+    // preview build forces it off even if the variable leaks into its
+    // environment.
+    feedbackEndpoint: isPreviewBuild ? "" : process.env.DOCS_FEEDBACK_ENDPOINT ?? "",
+    // Not a secret: it ships in the client bundle. It only filters untargeted
+    // requests; any limit on abuse has to be enforced by the receiving
+    // endpoint.
+    feedbackToken: isPreviewBuild ? "" : process.env.DOCS_FEEDBACK_TOKEN ?? "",
     // Major typed in a query -> tag of the version a reader is actually served.
     versionTagByMajor,
     // A docs version's tag -> the API-reference tag(s) that document it, so a

src/components/PageFeedback/direct.ts

@@ -0,0 +1,71 @@
+/**
+ * The fallback for a comment PostHog could not take because it is not loaded.
+ *
+ * WHY THIS EXISTS. The widget's events go to PostHog, which is loaded BEHIND
+ * the consent banner: until a reader accepts cookies, `window.posthog` does
+ * not exist and the capture reports `not-loaded`. So a reader who declines
+ * and then spends two minutes writing us a paragraph leaves no trace of it
+ * anywhere.
+ *
+ * ONLY WHEN POSTHOG IS NOT LOADED. Never beside a successful capture, so a
+ * consenting reader's comment is not recorded twice under two timestamps; and
+ * never when the reader has explicitly opted out of capturing in PostHog (or
+ * when PostHog threw and that cannot be ruled out). An opt-out is a refusal,
+ * not a delivery problem to route around.
+ *
+ * WHERE IT GOES. An Apps Script Web App deployed to accept anonymous requests,
+ * which appends the comment to a spreadsheet. The endpoint must accept
+ * requests from a reader's browser without any sign-in. The widget's note
+ * tells the reader this before they send, whenever this path applies.
+ *
+ * WHAT IT SENDS. The four fields the widget already sends to PostHog, plus
+ * the token, and nothing else in the body. Like any web request, it also
+ * carries the browser's IP address and user agent to the receiving server.
+ */
+
+type DirectFeedback = {
+  url: string;
+  title: string;
+  helpful: boolean | null;
+  comment: string;
+};
+
+/**
+ * `no-cors`, and what that costs.
+ *
+ * An Apps Script Web App does not answer a cross-origin preflight, so a normal
+ * JSON POST never leaves the browser. `text/plain` keeps the request "simple"
+ * and no-cors lets it through — at the price of an opaque response we cannot
+ * read. So this reports whether the request was DISPATCHED, not whether it
+ * arrived.
+ *
+ * An Apps Script that answers with an error, or was redeployed to a new URL,
+ * still resolves here. So on this path the widget's copy says only that the
+ * note was sent ("Thanks — your note was sent."), never that it reached the
+ * team.
+ */
+export async function sendDirectFeedback(
+  endpoint: string,
+  token: string,
+  payload: DirectFeedback,
+): Promise<boolean> {
+  if (!endpoint) return false;
+  try {
+    await fetch(endpoint, {
+      method: 'POST',
+      mode: 'no-cors',
+      // Deliberately text/plain: application/json would trigger a preflight
+      // the Web App cannot answer.
+      headers: { 'Content-Type': 'text/plain;charset=utf-8' },
+      // `keepalive` so the request is still dispatched if the reader navigates
+      // away mid-send (no-cors cannot confirm it arrived).
+      keepalive: true,
+      body: JSON.stringify({ ...payload, token }),
+    });
+    return true;
+  } catch {
+    // Offline, blocked, or refused. The caller tells the reader plainly and
+    // keeps their text in the box.
+    return false;
+  }
+}