You're three months into tracking 147 custom events across your app. Marketing wants to measure retention by completed actions. Product needs funnel drop-off visibility. Finance requires revenue reconciliation. Your dashboard shows user_signup, UserSignUp, sign_up_complete, and signup_success as four separate events that should have been one.
This isn't a configuration mistake. It's what happens when event taxonomy design starts as "let's just track what we need right now" instead of "let's build a system that scales for 18 months." The result is duplicate events, inconsistent naming, broken funnels, and eventually a rebuild that halts reporting for weeks.
Below are the design decisions that separate event taxonomies that last from those that collapse within the first year.
Why Most App Event Taxonomies Get Rebuilt
Most event tracking fails the same way. A growth team needs signup conversion, so they fire signup_complete. Three weeks later, product needs onboarding completion, so they add onboarding_done. Finance wants gross revenue tracked separately from net, but purchase_complete only captures transaction totals. Six months in, you have 80+ events with overlapping definitions, inconsistent parameters, and no clear hierarchy.
The cost compounds quickly:
Marketing can't compare campaign performance because event names changed between quarters
Product analytics needs custom SQL because standard funnels don't recognise the six different ways "signup" was instrumented
When Apple's ATT made SKAN the main iOS signal, teams found their event priority mapping was impossible because half their "critical" events were duplicates
The teams that avoid this designed their event structure before implementation, not during it.
Design Principle 1: Standard Events vs Custom Events
The first decision is which actions use standard event names and which need custom instrumentation. Every in-app event you track either maps to a category ad networks already understand or needs its own mapping.
Standard events cover the core lifecycle: install, app_open, registration, purchase, add_to_cart, level_achieved, tutorial_complete. Meta, Google, and TikTok all recognise equivalents of these, so a standard purchase event with the right parameters (currency, value, transaction ID) is simple to map to each network's postback.
Custom events are necessary when your business model has milestones that don't fit standard categories:
A fintech app needs
kyc_verification_completebecause regulatory compliance is a core conversion stepA mobility app needs
ride_requestedseparate fromride_startedbecause booking intent matters independently of fulfilmentA gaming app needs progression events because monetisation patterns change by stage
The trade-off is maintenance. Custom events need explicit postback rules, SKAN conversion value mapping, and cohort definitions for each channel. Use standard events wherever they fit, and reserve custom events for business-critical milestones. For which events are worth sending to ad networks at all, see which in-app events actually predict LTV.
Validation rule: if you can't explain in one sentence why a custom event must exist instead of a standard event with custom parameters, you probably don't need it. payment_method_added with method: upi is cleaner than separate upi_added, card_added, and netbanking_added events.
Design Principle 2: Naming Conventions That Scale
Naming conventions decide whether your taxonomy stays maintainable. The point isn't personal preference; it's consistency across engineering, analytics, and marketing, who all reference the same events.
Our recommendation is snake_case with a hierarchical category_action_object structure: checkout_initiated_cart, payment_completed_transaction, subscription_renewed_monthly, profile_updated_email.
Hierarchy groups related events. Filter your dashboard for
checkout_and you see the whole purchase funnel without memorising names, which matters once you pass 100 events.Versioning prevents breaking changes. If "active user" changes from "opened app" to "completed key action", track
session_started_v1andsession_started_v2side by side during migration so historical reporting stays continuous.Avoid the patterns that fail: camelCase (capitalised inconsistently by different developers), spaces (break SQL and exports), abbreviations like
chk_init(cryptic once the original developer leaves), and mixed formats.
The same discipline applies to campaign naming; our guide to a creative tagging taxonomy that scales uses the same principles. To test your naming, export your event list alphabetically. If related events aren't grouped together, or you need a lookup table to remember what events mean, the convention is failing.
Design Principle 3: Parameter Standards
An event without parameters is just a counter. Parameters provide the context that makes analysis possible: which product, what price, which campaign, which user segment.
Define required and optional parameters with strict type consistency. For purchase_completed, required parameters are value (number), currency (ISO string), and transaction_id (unique string). Optional ones might include payment_method, item_count, discount_applied, and user_ltv_segment.
Type consistency prevents analysis errors. If value is sometimes "₹299" and sometimes 299, revenue reports break. If currency is sometimes "INR" and sometimes "rupees", aggregation fails.
Standard parameter types:
value: number (decimal), monetary amount
currency: string (ISO 4217, uppercase), always three letters
transaction_id: string (unique), used for deduplication
item_id: string (SKU or internal ID)
category: string (predefined list)
timestamp: integer (Unix epoch)
user_id: string (hashed if PII)
Parameter names should follow the event convention: if you fire checkout_initiated, the cart value parameter is cart_value, not cartValue.
Keep a parameter schema document that lists every parameter's name, type, allowed values, and whether it's required. The Linkrunner Events tab shows each event with its parameters, so QA can spot type mismatches before launch.
Design Principle 4: Revenue Event Architecture
Revenue events need the most precision because they feed financial reporting and ROAS. The key decisions are gross versus net revenue and how to handle multiple currencies.
Track gross revenue on the initial transaction, then fire separate events for refunds and fees. This keeps an audit trail and lets you calculate both gross and net without reprocessing history.
Initial transaction:
purchase_completedwithvalue: 299,currency: INR,transaction_id: txn_abc123,payment_method: upiRefund:
refund_processedwithvalue: -299,currency: INR,original_transaction_id: txn_abc123,refund_reason: customer_requestFee:
fee_appliedwithvalue: -29.90,currency: INR,transaction_id: txn_abc123,fee_type: platform_commission
Gross revenue is the sum of purchase_completed, net revenue subtracts refunds and fees, and refund rate is refund events divided by purchases.
Use ISO 4217 codes and consistent decimal precision. Store values in the smallest currency unit where possible (paise, cents) to avoid floating-point errors, and for multi-currency apps include a USD-normalised amount alongside the local one. Don't compute "net revenue" on the purchase event by subtracting estimated fees in real time: fees change and refunds arrive days later, so your history becomes wrong.
Example: Fintech App Event Hierarchy
Here's how this works for a fintech funnel: signup, KYC, first transaction, retention.
Signup:
registration_initiated(source,platform)phone_number_entered(country_code)otp_sent(attempt_number)registration_completed, standard event (user_id,signup_duration_seconds)
KYC:
kyc_initiated(verification_method: aadhaar|pan|passport)kyc_document_uploaded(document_type,upload_attempt)kyc_verification_complete, custom event (verification_time_seconds,verification_method)
Transactions:
wallet_loaded(value,currency,payment_method)first_transaction_completed, custom activation event (value,currency,transaction_type,time_since_registration_hours)transaction_completed, recurring (value,currency,transaction_type,recipient_type)
Retention: app_opened_day_7 and transaction_completed_day_30, each with cohort_date and running totals.
This hierarchy answers real business questions: how many users complete KYC, the median time from signup to first transaction, how many D7 actives still transact at D30, and which channels bring users who activate fastest. All KYC events start with kyc_, value is always a number, and time_since_ parameters always use the same units.
How to Handle Edge Cases
Failed events: track failures explicitly instead of inferring them from missing successes. Use
{action}_failed(for examplepayment_failed) withfailure_reason,error_code, andretry_attempt, so you can see how many users succeed after several tries.Partial completions: a five-step signup needs an event per step (
phone_entered,otp_verified,profile_created,terms_accepted,registration_completed), each withstep_numberandtotal_steps, so you see exactly where users drop off.Time-based events: retention milestones and lifecycle changes (dormant, churned, reactivated) should be generated server-side on a fixed daily schedule, with
cohort_date,milestone_day, and status fields. Server-side generation covers users who never open the app, which SDK events can't.
Validation and QA
A taxonomy means nothing until you confirm the implementation matches the spec.
Before implementation, write a test plan with the full event list, the parameter schema, test scenarios for main flows and edge cases, and acceptance criteria. It becomes the contract between engineering, product, and marketing: if an event isn't in the plan, it doesn't ship.
In staging, test each critical event for:
The standard path, with all required parameters present
Missing required parameters and wrong types (a string where a number belongs)
Edge values: zero, negative, very large, special characters
Duplicate firing and deduplication
Offline firing, queuing, and retry
Linkrunner's SDK Console and Events tab let developers watch test events and their parameters arrive, which makes these checks quick.
After launch, monitor:
Volume: with 10k DAU and 3 to 5 sessions per user,
app_openshould fire roughly 30k to 50k times a dayCompleteness: required parameters present on 99%+ of events
Distributions: spikes in ₹0 transactions or 10k-second sessions signal data quality problems
Funnel stability: if
registration_initiatedtoregistration_completedfalls from 45% to 20%, something broke
Alert on volume drops over 20% day on day, missing-parameter rates over 1%, and funnel swings over 30%. The goal is to catch breaks within 24 hours, not three weeks later when marketing asks why attribution stopped working. If you forward events to other systems, the choice between webhooks, postbacks and server-to-server affects where those checks need to run.
Making Event Taxonomy Maintainable Long-Term
Documentation: keep one source of truth (Notion, Confluence, Google Doc) listing every event's purpose, parameters, and where it fires. Update it before implementing new events, not after.
Version control: track taxonomy changes with version numbers and a change log, so it's clear why
purchase_completed_v2exists and when v1 retires.Governance: small teams can rely on engineering and product review. Larger teams should require a one-page proposal for any new custom event: why it's needed, its parameters, and the business question it answers.
Audits every 6 months: list all events, check firing frequency, flag events with under 100 fires a month, verify parameter usage, and archive what isn't useful. Aim to keep active events under 100 unless your business logic genuinely needs more.
What Makes an Event Taxonomy Last
Taxonomies that survive share a few traits: one naming convention from day one, explicit parameter schemas with types, a hierarchy that groups related events, and governance that stops ad-hoc events. Taxonomies that fail are built reactively, mix formats, add parameters without type standards, and never check implementation against the spec.
A lasting taxonomy isn't about predicting every future event. It's about patterns new events can follow without special cases, so adding one becomes mechanical rather than a design debate.
Request a demo from Linkrunner to see how the Events tab and SDK Console help you QA your taxonomy before launch.
Frequently Asked Questions
How do I design an event taxonomy for product analytics?
Start from the business questions you need answered, then list the user actions that answer them. Name events with one convention (snake_case, category_action_object), define required and optional parameters with fixed types, and document everything before engineering instruments it. Validate in staging before launch and audit every 6 months.
How many events should a mobile app track?
Most apps can cover their funnels with well under 100 active events if they use parameters for variations instead of separate events. If your list keeps growing, audit for duplicates and events that rarely fire, and archive the ones nobody uses.
Should event names use snake_case or camelCase?
Use snake_case. It reads clearly in code, dashboards, and SQL, sorts related events together, and avoids the inconsistent capitalisation that creeps into camelCase when several developers instrument events. Whatever you choose, use it for every event and parameter.
