@convex-internal/web-analytics 2.1.0 → 2.2.0

package/README.md

@@ -29,6 +29,31 @@ capture("www-login", undefined, {
 });
 ```
 
+### `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.
+
+It's expected that a call on first load is always `undefined`, so call again
+after consent is granted.
+
+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

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/package.json

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