feat(react): add Firebase Analytics hooks with tests

docs.json

@@ -78,6 +78,57 @@
         }
       ]
     },
+    {
+      "tab": "react",
+      "group": "Analytics",
+      "pages": [
+        {
+          "title": "Getting Started",
+          "href": "/react/analytics"
+        },
+        {
+          "group": "Hooks",
+          "pages": [
+            {
+              "href": "/react/analytics/hooks/useGetGoogleAnalyticsClientIdQuery",
+              "title": "useGetGoogleAnalyticsClientIdQuery"
+            },
+            {
+              "href": "/react/analytics/hooks/useIsSupportedQuery",
+              "title": "useIsSupportedQuery"
+            },
+            {
+              "href": "/react/analytics/hooks/useLogEventMutation",
+              "title": "useLogEventMutation"
+            },
+            {
+              "href": "/react/analytics/hooks/useSetAnalyticsCollectionEnabledMutation",
+              "title": "useSetAnalyticsCollectionEnabledMutation"
+            },
+            {
+              "href": "/react/analytics/hooks/useSetConsentMutation",
+              "title": "useSetConsentMutation"
+            },
+            {
+              "href": "/react/analytics/hooks/useSetCurrentScreenMutation",
+              "title": "useSetCurrentScreenMutation"
+            },
+            {
+              "href": "/react/analytics/hooks/useSetDefaultEventParametersMutation",
+              "title": "useSetDefaultEventParametersMutation"
+            },
+            {
+              "href": "/react/analytics/hooks/useSetUserIdMutation",
+              "title": "useSetUserIdMutation"
+            },
+            {
+              "href": "/react/analytics/hooks/useSetUserPropertiesMutation",
+              "title": "useSetUserPropertiesMutation"
+            }
+          ]
+        }
+      ]
+    },
     {
       "tab": "react",
       "group": "Authentication",

docs/react/analytics/hooks/useGetGoogleAnalyticsClientIdQuery.mdx

@@ -0,0 +1,30 @@
+---
+title: useGetGoogleAnalyticsClientIdQuery
+---
+
+Retrieve the Google Analytics client ID for a Firebase Analytics instance.
+
+## Usage
+
+```tsx
+import { getAnalytics } from "firebase/analytics";
+import {
+  analyticsQueryKeys,
+  useGetGoogleAnalyticsClientIdQuery,
+} from "@tanstack-query-firebase/react/analytics";
+
+const analytics = getAnalytics(app);
+
+const { data: clientId, isLoading } = useGetGoogleAnalyticsClientIdQuery(
+  analytics,
+  {
+    queryKey: analyticsQueryKeys.googleAnalyticsClientId(analytics.app.name),
+  },
+);
+```
+
+## Notes
+
+- Wraps Firebase [`getGoogleAnalyticsClientId`](https://firebase.google.com/docs/reference/js/analytics.md#getgoogleanalyticsclientid).
+- Requires a caller-provided `queryKey`.
+- Disable the query until Analytics is initialized with `enabled: !!analytics` if needed.

docs/react/analytics/hooks/useIsSupportedQuery.mdx

@@ -0,0 +1,29 @@
+---
+title: useIsSupportedQuery
+---
+
+Check whether Firebase Analytics is supported in the current environment.
+
+## Usage
+
+```tsx
+import {
+  analyticsQueryKeys,
+  useIsSupportedQuery,
+} from "@tanstack-query-firebase/react/analytics";
+
+const { data: supported, isLoading } = useIsSupportedQuery({
+  queryKey: analyticsQueryKeys.isSupported(),
+  staleTime: Number.POSITIVE_INFINITY,
+});
+
+if (supported) {
+  // Safe to call getAnalytics()
+}
+```
+
+## Notes
+
+- Wraps Firebase [`isSupported`](https://firebase.google.com/docs/reference/js/analytics.md#issupported).
+- Does not accept an `Analytics` instance.
+- Requires a caller-provided `queryKey`.

docs/react/analytics/hooks/useLogEventMutation.mdx

@@ -0,0 +1,46 @@
+---
+title: useLogEventMutation
+---
+
+Log a Google Analytics event via Firebase Analytics.
+
+## Usage
+
+```tsx
+import { getAnalytics } from "firebase/analytics";
+import { useLogEventMutation } from "@tanstack-query-firebase/react/analytics";
+
+const analytics = getAnalytics(app);
+const { mutate: logAnalyticsEvent } = useLogEventMutation(analytics);
+
+logAnalyticsEvent({
+  eventName: "login",
+  eventParams: { method: "email" },
+});
+```
+
+## Screen tracking
+
+Prefer a `screen_view` event over the deprecated `useSetCurrentScreenMutation`:
+
+```tsx
+logAnalyticsEvent({
+  eventName: "screen_view",
+  eventParams: {
+    firebase_screen: "Home",
+    firebase_screen_class: "HomeScreen",
+  },
+});
+```
+
+## Global events
+
+Apply an event to all Google Analytics properties on the page with `callOptions.global`:
+
+```tsx
+logAnalyticsEvent({
+  eventName: "purchase",
+  eventParams: { transaction_id: "T123", value: 9.99, currency: "USD" },
+  callOptions: { global: true },
+});
+```

docs/react/analytics/hooks/useSetAnalyticsCollectionEnabledMutation.mdx

@@ -0,0 +1,22 @@
+---
+title: useSetAnalyticsCollectionEnabledMutation
+---
+
+Enable or disable Google Analytics collection for an app on the current device.
+
+## Usage
+
+```tsx
+import { getAnalytics } from "firebase/analytics";
+import { useSetAnalyticsCollectionEnabledMutation } from "@tanstack-query-firebase/react/analytics";
+
+const analytics = getAnalytics(app);
+const { mutate: setCollectionEnabled } =
+  useSetAnalyticsCollectionEnabledMutation(analytics);
+
+// Opt user out of analytics collection
+setCollectionEnabled(false);
+
+// Re-enable after consent is granted
+setCollectionEnabled(true);
+```

docs/react/analytics/hooks/useSetConsentMutation.mdx

@@ -0,0 +1,23 @@
+---
+title: useSetConsentMutation
+---
+
+Set end-user consent state for Google Analytics across all gtag references on the page.
+
+## Usage
+
+```tsx
+import { useSetConsentMutation } from "@tanstack-query-firebase/react/analytics";
+
+const { mutate: setAnalyticsConsent } = useSetConsentMutation();
+
+setAnalyticsConsent({
+  analytics_storage: "granted",
+  ad_storage: "denied",
+});
+```
+
+## Notes
+
+- Wraps Firebase [`setConsent`](https://firebase.google.com/docs/reference/js/analytics.md#setconsent).
+- This is a module-level API and does not require an `Analytics` instance.

docs/react/analytics/hooks/useSetCurrentScreenMutation.mdx

@@ -0,0 +1,34 @@
+---
+title: useSetCurrentScreenMutation
+---
+
+Set the current screen name via gtag config.
+
+<Info>
+This hook wraps a deprecated Firebase API. Prefer [`useLogEventMutation`](/react/analytics/hooks/useLogEventMutation) with `eventName: "screen_view"` for new code.
+</Info>
+
+## Usage
+
+```tsx
+import { getAnalytics } from "firebase/analytics";
+import { useSetCurrentScreenMutation } from "@tanstack-query-firebase/react/analytics";
+
+const analytics = getAnalytics(app);
+const { mutate: setScreen } = useSetCurrentScreenMutation(analytics);
+
+setScreen({ screenName: "Home" });
+```
+
+## Recommended alternative
+
+```tsx
+import { useLogEventMutation } from "@tanstack-query-firebase/react/analytics";
+
+const { mutate: logAnalyticsEvent } = useLogEventMutation(analytics);
+
+logAnalyticsEvent({
+  eventName: "screen_view",
+  eventParams: { firebase_screen: "Home" },
+});
+```

docs/react/analytics/hooks/useSetDefaultEventParametersMutation.mdx

@@ -0,0 +1,22 @@
+---
+title: useSetDefaultEventParametersMutation
+---
+
+Set default event parameters applied to every Analytics event on the page.
+
+## Usage
+
+```tsx
+import { useSetDefaultEventParametersMutation } from "@tanstack-query-firebase/react/analytics";
+
+const { mutate: setDefaultParams } = useSetDefaultEventParametersMutation();
+
+setDefaultParams({ session_id: "abc123", debug_mode: true });
+setDefaultParams({ campaign: "spring_sale" });
+```
+
+## Notes
+
+- Wraps Firebase [`setDefaultEventParameters`](https://firebase.google.com/docs/reference/js/analytics.md#setdefaulteventparameters).
+- This is a module-level API and does not require an `Analytics` instance.
+- Parameters persist for subsequent automatic and manual events on the page.

docs/react/analytics/hooks/useSetUserIdMutation.mdx

@@ -0,0 +1,28 @@
+---
+title: useSetUserIdMutation
+---
+
+Set or clear the Google Analytics user ID for a Firebase Analytics instance.
+
+## Usage
+
+```tsx
+import { getAnalytics } from "firebase/analytics";
+import { useSetUserIdMutation } from "@tanstack-query-firebase/react/analytics";
+
+const analytics = getAnalytics(app);
+const { mutate: setAnalyticsUserId } = useSetUserIdMutation(analytics);
+
+setAnalyticsUserId({ id: user.uid });
+
+// Clear user ID on sign-out
+setAnalyticsUserId({ id: null });
+```
+
+## Global user ID
+
+Apply the user ID across all gtag properties on the page:
+
+```tsx
+setAnalyticsUserId({ id: user.uid, callOptions: { global: true } });
+```

docs/react/analytics/hooks/useSetUserPropertiesMutation.mdx

@@ -0,0 +1,31 @@
+---
+title: useSetUserPropertiesMutation
+---
+
+Set Google Analytics user properties for a Firebase Analytics instance.
+
+## Usage
+
+```tsx
+import { getAnalytics } from "firebase/analytics";
+import { useSetUserPropertiesMutation } from "@tanstack-query-firebase/react/analytics";
+
+const analytics = getAnalytics(app);
+const { mutate: setAnalyticsUserProperties } =
+  useSetUserPropertiesMutation(analytics);
+
+setAnalyticsUserProperties({
+  properties: { plan: "premium", role: "admin" },
+});
+```
+
+## Global properties
+
+Apply properties across all gtag properties on the page:
+
+```tsx
+setAnalyticsUserProperties({
+  properties: { plan: "free" },
+  callOptions: { global: true },
+});
+```