Canonical Event Catalog

Canonical events are the standard event vocabulary that Gurulu uses across every platform. Whether an event fires from the JavaScript web tracker, the iOS SDK, or the Android SDK, it carries the same name, the same required properties, and the same semantic meaning.

This cross-platform consistency is what lets Gurulu merge data from different sources into a single timeline, build funnels that span devices, and power AI-driven insights without manual mapping.

Gurulu ships with 18 standard events organized into five categories: Core, Acquisition, Revenue, Engagement, and Retention.

Standard Events

Core

$pageviewA page or screen is viewed.
Required
urlstring
titlestring
Optional
referrerstring
duration_msnumber
$session_startA new session begins.
Required
session_idstring
Optional
landing_pagestring
utm_sourcestring
$session_endA session ends or times out.
Required
session_idstring
duration_msnumber
Optional
page_countnumber
$identifyAssociates the current visitor with a known identity.
Required
user_idstring
Optional
emailstring
namestring
planstring

Acquisition

$signupA new account or profile is created.
Required
methodstring
Optional
referral_codestring
planstring
$loginUser authenticates into the product.
Required
methodstring
Optional
two_factorboolean
$inviteUser invites another person to the product.
Required
channelstring
Optional
invite_codestring

Revenue

$purchaseA completed transaction or order.
Required
amountnumber
currencystring
Optional
order_idstring
itemsarray
couponstring
$subscribeUser starts a recurring subscription.
Required
planstring
amountnumber
currencystring
Optional
intervalstring
trialboolean
$upgradeUser upgrades to a higher plan.
Required
from_planstring
to_planstring
Optional
amountnumber
currencystring
$refundA refund is issued for a prior transaction.
Required
amountnumber
currencystring
Optional
order_idstring
reasonstring

Engagement

$searchUser performs a search query.
Required
querystring
Optional
result_countnumber
filtersobject
$clickUser clicks a tracked element.
Required
elementstring
Optional
selectorstring
textstring
$form_submitA form is submitted.
Required
form_idstring
Optional
form_namestring
field_countnumber
$downloadUser downloads a file or resource.
Required
file_urlstring
Optional
file_typestring
file_sizenumber
$shareUser shares content via a social or copy action.
Required
channelstring
Optional
content_idstring
urlstring

Retention

$feedbackUser submits a rating, review, or NPS score.
Required
scorenumber
Optional
commentstring
typestring
$churnUser cancels their subscription or deletes their account.
Required
reasonstring
Optional
planstring
tenure_daysnumber

SDK Usage Examples

Below are tracking examples for three key events across all supported platforms.

$purchase

Web SDK
gurulu.track('$purchase', {
  amount: 49.99,
  currency: 'USD',
  order_id: 'ORD-1234',
  items: [{ sku: 'WIDGET-01', qty: 2 }],
});
iOS SDK
Gurulu.track("$purchase", properties: [
  "amount": 49.99,
  "currency": "USD",
  "order_id": "ORD-1234",
  "items": [["sku": "WIDGET-01", "qty": 2]]
])
Android SDK
Gurulu.track("$purchase", mapOf(
  "amount" to 49.99,
  "currency" to "USD",
  "order_id" to "ORD-1234",
  "items" to listOf(mapOf("sku" to "WIDGET-01", "qty" to 2))
))

$signup

Web SDK
gurulu.track('$signup', {
  method: 'email',
  referral_code: 'FRIEND20',
});
iOS SDK
Gurulu.track("$signup", properties: [
  "method": "apple_id",
  "plan": "free"
])
Android SDK
Gurulu.track("$signup", mapOf(
  "method" to "google",
  "plan" to "free"
))

$search

Web SDK
gurulu.track('$search', {
  query: 'wireless headphones',
  result_count: 42,
  filters: { category: 'electronics', price_max: 100 },
});
iOS SDK
Gurulu.track("$search", properties: [
  "query": "wireless headphones",
  "result_count": 42
])
Android SDK
Gurulu.track("$search", mapOf(
  "query" to "wireless headphones",
  "result_count" to 42
))

Event Naming Conventions

$ prefix -- Reserved for system-defined canonical events. Do not use the $ prefix for your own custom events.
snake_case -- Custom events must use lowercase snake_case: video_played, cart_updated.
Automatic normalization -- Gurulu recognizes common naming patterns and maps them to canonical events automatically:
Your event nameMapped to
order_completed$purchase
registration_complete$signup
user_login$login
plan_upgraded$upgrade
subscription_started$subscribe
query_searched$search
file_downloaded$download
content_shared$share
nps_submitted$feedback
account_cancelled$churn

Normalization is applied at ingestion time. You can override or disable any mapping rule.

Custom Event Mapping

If your codebase uses event names that do not match the default normalization rules, you can configure custom mappings in the dashboard.

Setting up mappings

  1. Go to Settings → Event Mappings in the dashboard.
  2. Click Add Mapping.
  3. Enter the source event name (e.g. checkout_done) and select the canonical target (e.g. $purchase).
  4. Optionally map source properties to canonical properties.
  5. Save. The mapping applies to all future events and can be back-filled on historical data.

Mapping via API

curl -X POST https://gurulu.io/api/event-mappings \
  -H "Authorization: Bearer gsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "siteId": "YOUR_SITE_ID",
    "source": "checkout_done",
    "target": "$purchase",
    "propertyMap": {
      "total": "amount",
      "curr": "currency"
    }
  }'

Default mapping rules

When a new site is created, Gurulu enables a set of default mapping rules that cover the most common naming patterns from popular analytics tools (Google Analytics, Mixpanel, Amplitude, Segment). These defaults can be edited or disabled at any time from Settings → Event Mappings.

For information on tracking events and building funnels, see Events & Funnels. For SDK installation, see Mobile SDKs.

Edit this page