@convex-internal/web-analytics 1.0.3 → 1.1.1

package/README.md

@@ -14,14 +14,13 @@ provider.
 
 The provider starts analytics in production, except on localhost, syncs
 consent to PostHog, and shows the consent banner when the visitor has not
-chosen yet. Pass `posthogConfig` for site-specific options, such as the
-website's `dub_id` campaign param:
+chosen yet.
 
-```tsx
-<WebAnalyticsProvider posthogConfig={{ custom_campaign_params: ["dub_id"] }}>
-  {children}
-</WebAnalyticsProvider>
-```
+PostHog already copies standard campaign params (UTMs, `gclid`, `rdt_cid`,
+`fbclid`, and other common click IDs) from the landing URL onto events. This
+package also captures `dub_id`. After consent, PostHog creates an anonymous
+person profile. Campaign params still available at that point can be stored as
+`$initial_*`, supporting person-level attribution before login.
 
 ### `capture`
 

package/dist/WebAnalyticsProvider.d.ts

@@ -1,22 +1,17 @@
-import { type PostHogConfig } from "posthog-js";
 import { type ReactNode } from "react";
-export type { PostHogConfig };
+export declare const POSTHOG_PUBLIC_PROJECT_TOKEN = "phc_JDNTRxeh2li2sQTRO0IcOYMJcp8fPs5nTK9TU751nQK";
 /**
- * `"unknown"` until the cookie has been read on the client (SSR and first
- * render). `"undecided"` when there is no recognized choice yet. `"consented"`
- * when the cookie is `true` and Global Privacy Control (GPC) is not set.
- * `"declined"` when the cookie is `false`, or while GPC is set.
- *
- * GPC does not write or change the cookie. If it is later turned off, the
- * stored cookie (or the banner, if none) applies again.
+ * `"unknown"` until the cookie has been read (SSR and first client render).
+ * `"undecided"` when it has been read and there is no recognized choice.
+ * `"consented"` when the cookie is `true` and Global Privacy Control is off.
+ * `"declined"` when the cookie is `false`, or while GPC is on.
  */
 export type ConsentStatus = "unknown" | "undecided" | "consented" | "declined";
 export interface WebAnalyticsProviderProps {
     children: ReactNode;
-    posthogConfig?: Partial<PostHogConfig>;
 }
 export declare const ConsentContext: import("react").Context<{
     consent: ConsentStatus;
     setConsent: (status: "consented" | "declined") => void;
 } | null>;
-export declare function WebAnalyticsProvider({ children, posthogConfig, }: WebAnalyticsProviderProps): import("react").JSX.Element;
+export declare function WebAnalyticsProvider({ children }: WebAnalyticsProviderProps): import("react").JSX.Element;

package/dist/WebAnalyticsProvider.js

@@ -4,9 +4,15 @@ import { posthog } from "posthog-js";
 import { createContext, useEffect } from "react";
 import { ConsentBanner } from "./ConsentBanner.js";
 import { useBooleanCookie } from "./useCookie.js";
-const COOKIE_NAME = "allowsCookies";
-const POSTHOG_KEY = "phc_JDNTRxeh2li2sQTRO0IcOYMJcp8fPs5nTK9TU751nQK";
+// PostHog project token for event ingest and feature flags. `phc_` tokens are
+// public by design (browser JS, no env var) and cannot read private project data.
+// https://posthog.com/docs/privacy#is-it-ok-for-my-api-key-to-be-exposed-and-public
+export const POSTHOG_PUBLIC_PROJECT_TOKEN = "phc_JDNTRxeh2li2sQTRO0IcOYMJcp8fPs5nTK9TU751nQK";
 const POSTHOG_HOST = "https://ap.convex.dev";
+const COOKIE_NAME = "allowsCookies";
+// GPC wins over the stored cookie and does not write it, so turning GPC off
+// restores the saved choice (or the banner if there is none). A missing or
+// unrecognized cookie after the read defaults to `"undecided"`.
 function resolveConsent(isReady, cookieValue, gpcOptOut) {
     if (!isReady) {
         return "unknown";
@@ -23,27 +29,23 @@ function resolveConsent(isReady, cookieValue, gpcOptOut) {
     return "undecided";
 }
 export const ConsentContext = createContext(null);
-export function WebAnalyticsProvider({ children, posthogConfig, }) {
+export function WebAnalyticsProvider({ children }) {
     const { value, isReady, setValue } = useBooleanCookie(COOKIE_NAME);
     const gpcOptOut = typeof navigator !== "undefined" && navigator.globalPrivacyControl === true;
     const consent = resolveConsent(isReady, value, gpcOptOut);
+    // Initialize PostHog once, in cookieless mode. Consent is applied below.
     useEffect(() => {
-        // Prevent PostHog from initializing in development or on localhost.
+        if (posthog.__loaded) {
+            return;
+        }
+        // Keep local/dev sessions out of production PostHog data.
         if (process.env.NODE_ENV !== "production" ||
             window.location.hostname === "localhost" ||
             window.location.hostname === "127.0.0.1" ||
             window.location.hostname === "[::1]") {
             return;
         }
-        // If PostHog is already initialized, update its config.
-        if (posthog.__loaded) {
-            if (posthogConfig) {
-                posthog.set_config(posthogConfig);
-            }
-            return;
-        }
-        // Initialize PostHog.
-        posthog.init(POSTHOG_KEY, {
+        posthog.init(POSTHOG_PUBLIC_PROJECT_TOKEN, {
             api_host: POSTHOG_HOST,
             ui_host: "https://us.posthog.com/",
             // Automatically capture navigations using the History API.
@@ -53,28 +55,33 @@ export function WebAnalyticsProvider({ children, posthogConfig, }) {
             // tracking. See more: https://posthog.com/tutorials/cookieless-tracking
             opt_out_capturing_by_default: true,
             cookieless_mode: "on_reject",
-            // Site-specific options to add or override the defaults.
-            ...posthogConfig,
+            // Extends PostHog's built-in campaign params (gclid, rdt_cid, UTMs, etc.)
+            // onto events.
+            custom_campaign_params: ["dub_id"],
+            // Person profiles are enabled later, after consent is received.
+            person_profiles: "identified_only",
         });
-    }, [posthogConfig]);
-    // One-way sync: make PostHog match the resolved consent status.
+    }, []);
+    // Keep PostHog capturing in sync with consent.
     useEffect(() => {
-        // No decision yet or PostHog is not initialized.
-        if (consent === "unknown" || consent === "undecided" || !posthog.__loaded) {
+        if (!posthog.__loaded) {
             return;
         }
-        const posthogConsent = posthog.get_explicit_consent_status();
-        const targetConsent = consent === "consented" ? "granted" : "denied";
-        if (posthogConsent === targetConsent) {
+        // Skip until there's a real choice made.
+        if (consent === "unknown" || consent === "undecided") {
             return;
         }
+        // Skip opt-in/out when already in sync so returning visitors don't get a
+        // duplicate `$opt_in`.
         if (consent === "consented") {
-            // Records an `$opt_in` event, which is distinct from ConsentBanner's
-            // `cookie_consent_decided` as it also fires when we sync an existing
-            // allowsCookies cookie for returning visitors.
-            posthog.opt_in_capturing();
+            if (posthog.get_explicit_consent_status() !== "granted") {
+                posthog.opt_in_capturing();
+            }
+            // Opting in replaces the cookieless identity with a persistent one, so we
+            // create the profile afterward. This is a no-op if it already exists.
+            posthog.createPersonProfile();
         }
-        else {
+        else if (posthog.get_explicit_consent_status() !== "denied") {
             posthog.opt_out_capturing();
         }
     }, [consent]);

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { WebAnalyticsProvider, type WebAnalyticsProviderProps, type PostHogConfig, type ConsentStatus, } from "./WebAnalyticsProvider.js";
+export { WebAnalyticsProvider, type WebAnalyticsProviderProps, type ConsentStatus, } from "./WebAnalyticsProvider.js";
 export { Consented, type ConsentedProps } from "./Consented.js";
 export { useConsent } from "./useConsent.js";
 export { capture, type CaptureOptions } from "./capture.js";

package/package.json

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