Cross-Platform Event Tracking: One Event Catalog for Web, iOS, and Android

If your web team calls it "purchase_completed", your iOS team calls it "orderPlaced", and your Android team calls it "buy_event", you do not have analytics -- you have three incompatible data silos. Cross-platform event tracking starts with a shared vocabulary, and it is one of the hardest problems in product analytics because it requires coordination across teams, codebases, and release cycles.

Gurulu solves this with a canonical event catalog: a standardized set of 18 events that work identically across Web, iOS, and Android. Each event has a typed schema, platform-specific SDK helpers, and automatic normalization for legacy event names. This guide walks you through the catalog, the SDKs, and the setup process.

The Problem With Inconsistent Events

When event names differ across platforms, every downstream system breaks. Funnels that span web and mobile cannot be built because the steps have different names. Attribution models miscount conversions because a purchase on iOS is invisible to the web-centric model. CRM segments exclude mobile users because the qualifying event does not exist in their platform's namespace. And when a product manager asks "how many users completed onboarding?", the data team spends two days reconciling three different event schemas before they can answer.

The root cause is almost always the same: each platform team instrumented events independently, without a shared specification. By the time someone notices the inconsistency, there are months of historical data locked into incompatible schemas.

Gurulu's Canonical Event Catalog

Gurulu defines 18 standard events, each prefixed with $ to distinguish them from custom events. These events cover the core user lifecycle: acquisition, activation, engagement, monetization, and retention. Every Gurulu SDK -- Web, iOS, and Android -- implements these events with identical names, identical property schemas, and identical semantics.

// Gurulu Canonical Events (subset of 18)
$page_view    // Web, iOS, Android
$session_start
$sign_up
$login
$purchase
$add_to_cart
$search
$share
$app_install  // iOS, Android only
$first_open   // iOS, Android only

Typed SDK Helpers

Each SDK provides typed helper functions for canonical events. Instead of passing raw strings and hoping the property names match, you get compile-time checks and autocomplete. The SDK validates property types at runtime and logs warnings in development mode if required properties are missing. This catches instrumentation bugs before they reach production.

// Web (JavaScript)
import { gurulu } from '@gurulu/web';
gurulu.track('$purchase', {
  value: 49.99,
  currency: 'USD',
  items: [{ id: 'sku_001', name: 'Pro Plan' }],
});

// iOS (Swift)
import GuruluSDK

Gurulu.track("$purchase", properties: [
  "value": 49.99,
  "currency": "USD",
  "items": [["id": "sku_001", "name": "Pro Plan"]]
])

// Android (Kotlin)
import io.gurulu.sdk.Gurulu

Gurulu.track("\$purchase", mapOf(
  "value" to 49.99,
  "currency" to "USD",
  "items" to listOf(mapOf("id" to "sku_001", "name" to "Pro Plan"))
))

Notice that the event name, property keys, and property types are identical across all three platforms. When these events arrive at Gurulu's ingest endpoint, they are stored in the same schema regardless of source. Funnels, attribution, and CRM segments work across platforms without any additional mapping.

Normalization Mapping

If you have an existing codebase with non-standard event names, you do not need to rewrite all your instrumentation at once. Gurulu supports normalization mapping: a configuration that automatically translates incoming event names to their canonical equivalents. You can define mappings in the dashboard under Settings, or via the API.

// Normalization mapping examples
order_completed    → $purchase
signed_up          → $sign_up
item_added_to_cart → $add_to_cart
page_loaded        → $page_view
user_registered    → $sign_up

Normalization happens at ingest time, before events are stored. This means your historical data uses canonical names from the moment you enable mapping, even if your code still sends the old names. Over time, you can migrate your instrumentation to use canonical names directly and remove the mappings.

Setting Up Cross-Platform Tracking

Step one: install the Gurulu SDK on each platform. The Web SDK is a script tag or npm package. The iOS SDK is available via Swift Package Manager or CocoaPods. The Android SDK is on Maven Central. Each SDK initializes with your site ID and token, and auto-tracks page views, session starts, and app lifecycle events.

Step two: instrument your key events using canonical names. Start with the events that matter most for your business -- typically $sign_up, $purchase, and $add_to_cart. Use the typed helpers to ensure consistency. Do not try to instrument all 18 events at once; start with your conversion funnel and expand.

Step three: configure normalization mappings for any legacy events you cannot rename immediately. This gives you unified analytics across platforms while you gradually migrate your codebase. Most teams complete the migration in two to four sprints, working through one platform at a time.