Firebase Custom Events

Custom events track actions specific to your app that Firebase's automatic tracking does not cover. Every app has unique user interactions — completing a quiz, skipping a tutorial, changing a setting, uploading a file. Custom events capture these moments so you understand exactly how users engage with your product.

When to Create a Custom Event

Create a custom event when a user action matters for your business and no standard Firebase event covers it. Ask yourself: "Would knowing how many users did this change how I build the product?" If yes, track it.

Standard events (use these first):
- login, sign_up, purchase, search, share

Custom events (when standard ones don't fit):
- quiz_completed
- tutorial_skipped
- dark_mode_toggled
- export_clicked
- subscription_cancelled
- feature_unlocked

Naming Custom Events

Firebase event names follow these rules:

• Use letters, numbers, and underscores only
• Must start with a letter
• Maximum 40 characters
• Case-sensitive — ButtonClick and button_click are different events
• Use snake_case consistently: quiz_completed, not QuizCompleted or quizCompleted

Logging Custom Events with Parameters

Every event can carry parameters that describe the context of the action. Parameters help you understand not just that something happened, but how it happened:

import { logEvent } from "firebase/analytics";
import { analytics } from "./firebase";

// Quiz completed with details
logEvent(analytics, "quiz_completed", {
  quiz_name: "Firebase Basics",
  score: 85,
  time_taken_seconds: 240,
  passed: true
});

// File exported with format info
logEvent(analytics, "file_exported", {
  format: "pdf",
  file_size_kb: 450,
  page: "reports"
});

// Feature used
logEvent(analytics, "dark_mode_toggled", {
  new_state: "on",
  previous_state: "off"
});

Parameter Rules

• Maximum 25 parameters per event
• Parameter names: up to 40 characters, snake_case
• String values: up to 100 characters
• Numeric values: any number
• Boolean values: use true/false or 1/0

Tracking a User Journey with Events

A sequence of events tells the story of a user's path through a feature. Track each step to identify where users struggle:

// User starts onboarding
logEvent(analytics, "onboarding_started");

// User completes step 1
logEvent(analytics, "onboarding_step_completed", { step: 1, step_name: "profile" });

// User completes step 2
logEvent(analytics, "onboarding_step_completed", { step: 2, step_name: "preferences" });

// User skips step 3
logEvent(analytics, "onboarding_step_skipped", { step: 3, step_name: "tutorial" });

// User finishes
logEvent(analytics, "onboarding_completed", { steps_skipped: 1 });

If Analytics shows most users trigger onboarding_step_skipped at step 3, that step needs improvement — either it is too complex or not valuable enough to warrant the time.

Funnel Analysis

Funnels track how many users progress through a series of steps. Define a funnel in the Firebase Console under Analytics > Funnels:

Checkout Funnel:
Step 1: view_cart
Step 2: begin_checkout
Step 3: add_shipping_info
Step 4: add_payment_info
Step 5: purchase

If 1000 users reach Step 1 but only 200 complete Step 5,
80% drop off somewhere. The funnel shows exactly which step
loses the most users.

User Properties for Segmentation

Combine custom events with user properties to analyze behavior by segment:

import { setUserProperties, logEvent } from "firebase/analytics";

// Set property when user upgrades
setUserProperties(analytics, { plan: "premium" });

// Now all events from this user are tagged as premium
// In Analytics, filter quiz_completed by plan == "premium"
// to see if premium users score higher than free users

Registering Custom Dimensions in Google Analytics

Custom event parameters appear in raw event data by default, but to use them as dimensions in Analytics reports, register them in Google Analytics:

1. Open Google Analytics (analytics.google.com)
2. Go to Configure > Custom definitions
3. Click Create custom dimension
4. Enter the parameter name exactly as used in logEvent
5. Save

After registration (takes up to 24 hours), the parameter appears as a filterable dimension in Analytics reports.

Key Takeaway

Custom events capture user actions specific to your app's logic. Name them in snake_case, attach relevant parameters to add context, and use sequences of events to map user journeys. Track funnel steps to identify drop-off points. Register event parameters as custom dimensions in Google Analytics to use them as report filters. Custom events transform usage data into product decisions.