Firebase Analytics

Firebase Analytics collects usage and behavior data for your app. These hooks wrap the Firebase Analytics web SDK with TanStack Query for reads and writes.

Before using these hooks, ensure Analytics is enabled in your Firebase project and that the current environment supports it (Analytics is not available in all environments, such as some server-side contexts).

Setup

import { initializeApp } from "firebase/app";
import { getAnalytics } from "firebase/analytics";

// Initialize your Firebase app
initializeApp({ ... });

// Get the Analytics instance (client-side only)
const analytics = getAnalytics(app);

Use useIsSupportedQuery to check whether Analytics is supported before calling getAnalytics().

Importing

Hooks are exported from the analytics namespace:

import {
  analyticsQueryKeys,
  useLogEventMutation,
} from "@tanstack-query-firebase/react/analytics";

Most hooks accept an Analytics instance from getAnalytics() or initializeAnalytics(). Module-level Firebase APIs (setConsent, setDefaultEventParameters) are exposed as mutations that do not require an Analytics instance.

Query keys

Analytics query hooks require a caller-provided queryKey (same as Firestore). Use analyticsQueryKeys for consistent keys:

import { analyticsQueryKeys, useIsSupportedQuery } from "@tanstack-query-firebase/react/analytics";

const { data: supported } = useIsSupportedQuery({
  queryKey: analyticsQueryKeys.isSupported(),
  staleTime: Number.POSITIVE_INFINITY,
});

Logging events

Use useLogEventMutation to send Google Analytics events. For screen tracking, prefer a screen_view event over the deprecated useSetCurrentScreenMutation:

import { getAnalytics } from "firebase/analytics";
import { useLogEventMutation } from "@tanstack-query-firebase/react/analytics";

const analytics = getAnalytics(app);
const { mutate: logAnalyticsEvent } = useLogEventMutation(analytics);

logAnalyticsEvent({
  eventName: "screen_view",
  eventParams: {
    firebase_screen: "Home",
    firebase_screen_class: "HomeScreen",
  },
});

User identity and properties

Set the Analytics user ID and custom user properties with mutation hooks. Clear the user ID on sign-out by passing null:

import { useSetUserIdMutation, useSetUserPropertiesMutation } from "@tanstack-query-firebase/react/analytics";

const { mutate: setAnalyticsUserId } = useSetUserIdMutation(analytics);
const { mutate: setAnalyticsUserProperties } = useSetUserPropertiesMutation(analytics);

setAnalyticsUserId({ id: user.uid });
setAnalyticsUserProperties({ properties: { plan: "premium" } });

// On sign-out
setAnalyticsUserId({ id: null });

Consent and collection

• useSetConsentMutation — set consent state across all gtag references on the page
• useSetAnalyticsCollectionEnabledMutation — enable or disable collection for the current device
• useSetDefaultEventParametersMutation — attach default parameters to every event on the page

Available hooks

Queries

• useGetGoogleAnalyticsClientIdQuery — retrieve the Google Analytics client ID
• useIsSupportedQuery — check whether Analytics is supported in the current environment

Mutations

• useLogEventMutation — log a Google Analytics event
• useSetAnalyticsCollectionEnabledMutation — enable or disable analytics collection
• useSetConsentMutation — set end-user consent settings
• useSetCurrentScreenMutation — set the current screen name (deprecated)
• useSetDefaultEventParametersMutation — set default event parameters
• useSetUserIdMutation — set or clear the Analytics user ID
• useSetUserPropertiesMutation — set Analytics user properties