Merge pull request #7841 from logto-io/gao-init-posthog

feat(console): init posthog

Author: gao-sun

packages/console/package.json

@@ -89,6 +89,7 @@
     "overlayscrollbars-react": "^0.5.0",
     "postcss": "^8.4.39",
     "postcss-modules": "^6.0.0",
+    "posthog-js": "^1.268.6",
     "prettier": "^3.5.3",
     "prism-react-renderer": "^2.4.1",
     "prop-types": "^15.8.1",

packages/console/src/App.tsx

@@ -7,7 +7,8 @@ import {
   TenantScope,
 } from '@logto/schemas';
 import { conditionalArray } from '@silverhand/essentials';
-import { useContext, useMemo } from 'react';
+import { PostHogProvider, usePostHog } from 'posthog-js/react';
+import { useContext, useEffect, useMemo } from 'react';
 import { Helmet } from 'react-helmet';
 import { createBrowserRouter, RouterProvider } from 'react-router-dom';
 
@@ -21,7 +22,7 @@ import 'react-color-palette/css';
 
 import CloudAppRoutes from '@/cloud/AppRoutes';
 import AppLoading from '@/components/AppLoading';
-import { isCloud } from '@/consts/env';
+import { isCloud, postHogHost, postHogKey } from '@/consts/env';
 import { cloudApi, getManagementApi, meApi } from '@/consts/resources';
 import { ConsoleRoutes } from '@/containers/ConsoleRoutes';
 
@@ -71,8 +72,6 @@ export default App;
  * different components.
  */
 function Providers() {
-  const { currentTenantId } = useContext(TenantsContext);
-
   // For Cloud, we use Management API proxy for accessing tenant data.
   // For OSS, we directly call the tenant API with the default tenant API resource.
   const resources = useMemo(
@@ -103,58 +102,123 @@ function Providers() {
   );
 
   return (
-    <LogtoProvider
-      unstable_enableCache
-      config={{
-        endpoint: adminTenantEndpoint.href,
-        appId: adminConsoleApplicationId,
-        resources,
-        scopes,
-        prompt: [Prompt.Login, Prompt.Consent],
+    <PostHogProvider
+      apiKey={postHogKey ?? ''} // Empty key will disable PostHog
+      options={{
+        api_host: postHogHost,
+        defaults: '2025-05-24',
       }}
     >
-      <AppThemeProvider>
-        <Helmet titleTemplate={`%s - ${mainTitle}`} defaultTitle={mainTitle} />
-        <Toast />
-        <AppConfirmModalProvider>
-          <ErrorBoundary>
-            <LogtoErrorBoundary>
-              {/**
-               * If it's not Cloud (OSS), render the tenant app container directly since only default tenant is available;
-               * if it's Cloud, render the tenant app container only when a tenant ID is available (in a tenant context).
-               */}
-              {!isCloud || currentTenantId ? (
+      <LogtoProvider
+        unstable_enableCache
+        config={{
+          endpoint: adminTenantEndpoint.href,
+          appId: adminConsoleApplicationId,
+          resources,
+          scopes,
+          prompt: [Prompt.Login, Prompt.Consent],
+        }}
+      >
+        <AppThemeProvider>
+          <Helmet titleTemplate={`%s - ${mainTitle}`} defaultTitle={mainTitle} />
+          <Toast />
+          <AppConfirmModalProvider>
+            <ErrorBoundary>
+              <LogtoErrorBoundary>
                 <AppDataProvider>
-                  <AppRoutes />
+                  <GlobalScripts />
+                  <Content />
                 </AppDataProvider>
-              ) : (
-                <CloudAppRoutes />
-              )}
-            </LogtoErrorBoundary>
-          </ErrorBoundary>
-        </AppConfirmModalProvider>
-      </AppThemeProvider>
-    </LogtoProvider>
+              </LogtoErrorBoundary>
+            </ErrorBoundary>
+          </AppConfirmModalProvider>
+        </AppThemeProvider>
+      </LogtoProvider>
+    </PostHogProvider>
   );
 }
 
-/** Renders different routes based on the user's onboarding status. */
-function AppRoutes() {
+function Content() {
   const { tenantEndpoint } = useContext(AppDataContext);
-  const { isLoaded } = useCurrentUser();
+  const { isLoaded, user } = useCurrentUser();
   const { isAuthenticated } = useLogto();
+  const { currentTenantId, currentTenant } = useContext(TenantsContext);
+  const postHog = usePostHog();
+
+  useEffect(() => {
+    if (isLoaded) {
+      postHog.identify(user?.id);
+    }
+    // We don't reset user info here because this component includes some anonymous pages.
+    // Resetting user info may cause issues when the user switches between anonymous and
+    // authenticated pages.
+    // Reset user info in the sign-out logic instead.
+  }, [isLoaded, postHog, user]);
+
+  /**
+   * The `useEffect` below sets the PostHog group properties based on:
+   *
+   * 1. If `currentTenant` is available, since it contains rich data, set the group with both ID
+   *   and necessary properties.
+   * 2. If only `currentTenantId` is available, set the group with only ID. This usually happens
+   *   when the URL contains a tenant ID but the tenant data is not loaded yet or the tenant is
+   *   unavailable to the user.
+   * 3. If neither is available, reset all group properties. This usually happens when the user is
+   *   not in a tenant context.
+   *
+   * @caveat
+   * We need to identify group when window is reactivated (tab switch or window switch)
+   * since one user may access different tenants in different tabs or windows.
+   *
+   * Currently, PostHog DOES capture the correct group when the user switches tabs or windows
+   * since it reads the properties from the memory if existing, but just in case it doesn't work
+   * in the future, we add this logic here.
+   *
+   * See {https://github.com/PostHog/posthog-js/blob/b5eb605/packages/core/src/posthog-core-stateless.ts#L778-L783 | posthog-js source code}
+   * for details at the time of writing.
+   */
+  useEffect(() => {
+    const captureGroups = () => {
+      if (currentTenant) {
+        postHog.group('tenant', currentTenantId, {
+          name: currentTenant.name,
+        });
+      } else if (currentTenantId) {
+        postHog.group('tenant', currentTenantId);
+      } else {
+        postHog.resetGroups();
+      }
+    };
+
+    captureGroups();
+
+    const handleVisibilityChange = () => {
+      if (document.visibilityState === 'visible') {
+        captureGroups();
+      }
+    };
 
-  // Authenticated user should load onboarding data before rendering the app.
-  // This looks weird and it will be refactored soon by merging the onboarding
-  // routes with the console routes.
-  if (!tenantEndpoint || (isCloud && isAuthenticated && !isLoaded)) {
-    return <AppLoading />;
+    document.addEventListener('visibilitychange', handleVisibilityChange);
+
+    return () => {
+      document.removeEventListener('visibilitychange', handleVisibilityChange);
+    };
+  }, [postHog, currentTenantId, currentTenant]);
+
+  /**
+   * If it's not Cloud (OSS), render the tenant app container directly since only default tenant is available;
+   * if it's Cloud, render the tenant app container only when a tenant ID is available (in a tenant context).
+   */
+  if (!isCloud || currentTenantId) {
+    // Authenticated user should load onboarding data before rendering the app.
+    // This looks weird and it can be refactored by merging the onboarding
+    // routes with the console routes.
+    if (!tenantEndpoint || (isCloud && isAuthenticated && !isLoaded)) {
+      return <AppLoading />;
+    }
+
+    return <ConsoleRoutes />;
   }
 
-  return (
-    <>
-      <GlobalScripts />
-      <ConsoleRoutes />
-    </>
-  );
+  return <CloudAppRoutes />;
 }

packages/console/src/components/Topbar/UserInfo/index.tsx

@@ -1,5 +1,4 @@
 import { builtInLanguageOptions as consoleBuiltInLanguageOptions } from '@logto/phrases';
-import { useLogto } from '@logto/react';
 import { Theme } from '@logto/schemas';
 import classNames from 'classnames';
 import { useRef, useState } from 'react';
@@ -20,6 +19,7 @@ import Spacer from '@/ds-components/Spacer';
 import { Ring as Spinner } from '@/ds-components/Spinner';
 import useCurrentUser from '@/hooks/use-current-user';
 import useRedirectUri from '@/hooks/use-redirect-uri';
+import useSignOut from '@/hooks/use-sign-out';
 import useTenantPathname from '@/hooks/use-tenant-pathname';
 import useUserPreferences from '@/hooks/use-user-preferences';
 import { DynamicAppearanceMode } from '@/types/appearance-mode';
@@ -30,7 +30,7 @@ import UserInfoSkeleton from './UserInfoSkeleton';
 import styles from './index.module.scss';
 
 function UserInfo() {
-  const { signOut } = useLogto();
+  const { signOut } = useSignOut();
   const { getUrl } = useTenantPathname();
   const { t } = useTranslation(undefined, { keyPrefix: 'admin_console' });
   const { user, isLoading: isLoadingUser } = useCurrentUser();

packages/console/src/consts/env.ts

@@ -19,3 +19,5 @@ export const consoleEmbeddedPricingUrl =
   'https://logto.io/console-embedded-pricing';
 
 export const inkeepApiKey = normalizeEnv(import.meta.env.INKEEP_API_KEY);
+export const postHogKey = normalizeEnv(import.meta.env.POSTHOG_PUBLIC_KEY);
+export const postHogHost = normalizeEnv(import.meta.env.POSTHOG_PUBLIC_HOST);

packages/console/src/contexts/TenantsProvider.tsx

@@ -63,7 +63,13 @@ type Tenants = {
   removeTenant: (tenantId: string) => void;
   /** Update a tenant by ID if it exists in the current tenants data. */
   updateTenant: (tenantId: string, data: Partial<TenantResponse>) => void;
-  /** The current tenant ID parsed from the URL. */
+  /**
+   * The current tenant ID parsed from the URL.
+   *
+   * - If it's a non-cloud deployment, it will always be `default`.
+   * - For cloud deployment, if it's `''`, the user is not in a tenant context (e.g. in onboarding
+   * routes).
+   */
   currentTenantId: string;
   currentTenant?: TenantResponse;
   /** Indicates if the current tenant is a development tenant. */

packages/console/src/hooks/use-api.ts

@@ -27,6 +27,8 @@ import { TenantsContext } from '@/contexts/TenantsProvider';
 import { useConfirmModal } from '@/hooks/use-confirm-modal';
 import useRedirectUri from '@/hooks/use-redirect-uri';
 
+import useSignOut from './use-sign-out';
+
 export class RequestError extends Error {
   constructor(
     public readonly status: number,
@@ -45,7 +47,7 @@ export type StaticApiProps = {
 };
 
 const useGlobalRequestErrorHandler = (toastDisabledErrorCodes?: LogtoErrorCode[]) => {
-  const { signOut } = useLogto();
+  const { signOut } = useSignOut();
   const { show } = useConfirmModal();
   const { t } = useTranslation(undefined, { keyPrefix: 'admin_console' });
 

packages/console/src/hooks/use-sign-out.ts

@@ -0,0 +1,28 @@
+import { useLogto } from '@logto/react';
+import { usePostHog } from 'posthog-js/react';
+import { useCallback } from 'react';
+
+/**
+ * A hook that returns a wrapped `signOut` function from `useLogto` with necessary cleanup logic.
+ *
+ * Unless you have special needs, you should always use this hook instead of `useLogto` directly.
+ */
+const useSignOut = () => {
+  const { signOut: logtoSignOut } = useLogto();
+  const postHog = usePostHog();
+
+  const signOut = useCallback<ReturnType<typeof useLogto>['signOut']>(
+    async (postSignOutRedirectUri) => {
+      postHog.resetGroups(); // Not sure if this is needed, but just in case.
+      postHog.reset();
+      return logtoSignOut(postSignOutRedirectUri);
+    },
+    [logtoSignOut, postHog]
+  );
+  return {
+    /** A wrapped version of `useLogto`'s `signOut` with necessary cleanup logic. */
+    signOut,
+  };
+};
+
+export default useSignOut;

packages/console/src/pages/Profile/containers/DeleteAccountModal/components/FinalConfirmationModal/index.tsx

@@ -1,4 +1,3 @@
-import { useLogto } from '@logto/react';
 import { ResponseError } from '@withtyped/client';
 import { useContext, useState } from 'react';
 import { useTranslation } from 'react-i18next';
@@ -10,6 +9,7 @@ import { TenantsContext } from '@/contexts/TenantsProvider';
 import Button from '@/ds-components/Button';
 import ModalLayout from '@/ds-components/ModalLayout';
 import useRedirectUri from '@/hooks/use-redirect-uri';
+import useSignOut from '@/hooks/use-sign-out';
 import modalStyles from '@/scss/modal.module.scss';
 
 import styles from '../../index.module.scss';
@@ -29,7 +29,7 @@ export default function FinalConfirmationModal({
   onClose,
 }: Props) {
   const { t } = useTranslation(undefined, { keyPrefix: 'admin_console.profile.delete_account' });
-  const { signOut } = useLogto();
+  const { signOut } = useSignOut();
   const { removeTenant } = useContext(TenantsContext);
   const postSignOutRedirectUri = useRedirectUri('signOut');
   const [isDeleting, setIsDeleting] = useState(false);

packages/console/vite.config.ts

@@ -52,6 +52,8 @@ const buildConfig = (mode: string): UserConfig => ({
       process.env.CONSOLE_EMBEDDED_PRICING_URL
     ),
     'import.meta.env.INKEEP_API_KEY': JSON.stringify(process.env.INKEEP_API_KEY),
+    'import.meta.env.POSTHOG_PUBLIC_KEY': JSON.stringify(process.env.POSTHOG_PUBLIC_KEY),
+    'import.meta.env.POSTHOG_PUBLIC_HOST': JSON.stringify(process.env.POSTHOG_PUBLIC_HOST),
     // `@withtyped/client` needs this to be defined. We can optimize this later.
     'process.env': {},
   },