@convex-internal/web-analytics 2.0.1 → 2.2.0

package/README.md

@@ -29,15 +29,35 @@ capture("www-login", undefined, {
 });
 ```
 
-### Consent banner
+### `getDistinctId`
+
+PostHog's identifier for the current visitor. After consent is granted it is
+stored in a cookie on `.convex.dev`, so every Convex site in the browser uses
+the same ID.
+
+When this helper returns a value, consent has been granted. Pass that ID to a
+third-party tool so you can match that tool's events or sessions, such as a
+support chat, back to the same visitor in PostHog.
 
-The banner shows when `consent` is `"undecided"`. It records
-`cookie_consent_shown` when it appears and `cookie_consent_decided` with
-`{ decision: "accepted" | "declined" }` just before the choice is saved.
+It's expected that a call on first load is always `undefined`, so call again
+after consent is granted.
 
-The banner stays hidden while Global Privacy Control is on, because that
-resolves `consent` to `"declined"` rather than `"undecided"`. GPC does not
-write the cookie; see [Cookie behavior](#cookie-behavior).
+It returns one of:
+
+- **`undefined`**. PostHog is not initialized (localhost, non-production, or
+  still loading), or consent has not been granted. Before consent, PostHog
+  still has a cookieless ID, but it is not stable across sites or even page
+  reloads, so returning it would create noise rather than being useful.
+- **Anonymous UUID**, such as `"019a7d8f-9190-7844-a5c0-73d461a3a5d1"`.
+  Consent has been granted but this browser has not logged into the
+  dashboard where the user is identified.
+- **Convex profile ID**, such as `"4281"`. Consent has been granted and this
+  browser has logged into the dashboard.
+
+### Consent banner
+
+The banner is visible when `consent` is `"undecided"`. It is hidden while
+`consent` is `"unknown"`, `"consented"`, or `"declined"`.
 
 Theme with `--wa-banner-*` variables on `.wa-banner`:
 
@@ -66,6 +86,15 @@ Theme with `--wa-banner-*` variables on `.wa-banner`:
 
 Buttons default to 80% opacity and go to 100% on hover or keyboard focus.
 
+### Consent events
+
+`cookie_consent_shown` is recorded when the banner appears.
+`cookie_consent_decided` is recorded with
+`{ decision: "accepted" | "declined", source: "banner" }` just before the
+choice is saved, and with `{ decision: "declined", source: "gpc" }` when
+the GPC preference is applied. Historic events without `source` are banner
+decisions.
+
 ### Cookie behavior
 
 Once the cookie has been read, `consent` is resolved in this order:

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export { capture, type CaptureOptions } from "./capture.js";
+export { getDistinctId } from "./posthog.js";
 export type { ConsentStatus } from "./consent.js";

package/dist/index.js

@@ -1 +1,2 @@
 export { capture } from "./capture.js";
+export { getDistinctId } from "./posthog.js";

package/dist/posthog.d.ts

@@ -1,4 +1,5 @@
 import type { ConsentStatus } from "./consent.js";
 export declare const POSTHOG_PUBLIC_PROJECT_TOKEN = "phc_JDNTRxeh2li2sQTRO0IcOYMJcp8fPs5nTK9TU751nQK";
 export declare function initPostHog(): void;
+export declare function getDistinctId(): string | undefined;
 export declare function syncPostHogConsent(consent: ConsentStatus): void;

package/dist/posthog.js

@@ -32,6 +32,16 @@ export function initPostHog() {
         person_profiles: "identified_only",
     });
 }
+export function getDistinctId() {
+    if (!posthog.__loaded) {
+        return undefined;
+    }
+    // Cookieless IDs change across sites and reloads, so aren't useful to return.
+    if (posthog.get_explicit_consent_status() !== "granted") {
+        return undefined;
+    }
+    return posthog.get_distinct_id();
+}
 export function syncPostHogConsent(consent) {
     if (!posthog.__loaded) {
         return;

package/dist/react/ConsentBanner.js

@@ -1,14 +1,16 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useRef } from "react";
-import { bannerCopy } from "../strings.js";
 import { capture } from "../capture.js";
+import { hasGPC } from "../consent.js";
+import { bannerCopy } from "../strings.js";
 import { useConsent } from "./useConsent.js";
 import "../banner.css";
 export function ConsentBanner() {
     const { consent, setConsent } = useConsent();
     const shouldShow = consent === "undecided";
     const wasShowing = useRef(false);
+    const recordedGPCDecision = useRef(false);
     useEffect(() => {
         if (shouldShow && !wasShowing.current) {
             // Captures once when the banner becomes visible, not on later renders.
@@ -16,13 +18,22 @@ export function ConsentBanner() {
         }
         wasShowing.current = shouldShow;
     }, [shouldShow]);
+    useEffect(() => {
+        if (consent === "declined" && hasGPC() && !recordedGPCDecision.current) {
+            recordedGPCDecision.current = true;
+            capture("cookie_consent_decided", {
+                decision: "declined",
+                source: "gpc",
+            });
+        }
+    }, [consent]);
     if (!shouldShow) {
         return null;
     }
     const decide = (decision) => {
         try {
             // Captures before the cookie write so decline is captured cookieless.
-            capture("cookie_consent_decided", { decision });
+            capture("cookie_consent_decided", { decision, source: "banner" });
         }
         finally {
             setConsent(decision === "accepted" ? "consented" : "declined");

package/dist/svelte/WebAnalytics.svelte

@@ -9,6 +9,7 @@
 
   let isReady = $state(false);
   let cookieValue = $state<boolean | undefined>(undefined);
+  let recordedGPCDecision = false;
 
   const consent = $derived(resolveConsent(isReady, cookieValue, hasGPC()));
   const shouldShowBanner = $derived(consent === "undecided");
@@ -60,6 +61,17 @@
     wasShowingBanner = shouldShowBanner;
   });
 
+  $effect(() => {
+    if (consent === "declined" && hasGPC() && !recordedGPCDecision) {
+      // GPC hides the banner, so record the decline here instead of a click.
+      recordedGPCDecision = true;
+      capture("cookie_consent_decided", {
+        decision: "declined",
+        source: "gpc",
+      });
+    }
+  });
+
   function setConsent(status: "consented" | "declined") {
     setCookie(COOKIE_NAME, status === "consented" ? "true" : "false");
     cookieValue = status === "consented";
@@ -68,7 +80,7 @@
   function decide(decision: "accepted" | "declined") {
     try {
       // Captures before the cookie write so decline is captured cookieless.
-      capture("cookie_consent_decided", { decision });
+      capture("cookie_consent_decided", { decision, source: "banner" });
     } finally {
       setConsent(decision === "accepted" ? "consented" : "declined");
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@convex-internal/web-analytics",
-  "version": "2.0.1",
+  "version": "2.2.0",
   "type": "module",
   "exports": {
     ".": {