Understanding Events - Zixflow Docs

Events are the foundation of your data — they record every action users take in your application. This guide explains what events are, the different types you can track, and best practices for naming and structuring them.

What is an Event?

An event is a timestamped record of something that happened in your product. It’s like a digital breadcrumb trail that captures every meaningful action your users take. Think of events as the verbs of your data model. While user attributes describe who someone is (their name, email, plan type), events describe what they do (clicked, purchased, logged in, shared).

The Simple Definition

If you can describe it as “User did X at time Y,” it’s an event. Examples:

“Sarah added Red Sneakers to cart at 2:30 PM” → Event: Added to Cart
“John upgraded to Pro plan at 10:15 AM” → Event: Upgraded Plan
“Anonymous visitor viewed pricing page at 3:45 PM” → Event: Viewed Pricing Page

Why Events Matter

Events are powerful because they let you:

Understand user behavior: See exactly what users do in your product
Measure what matters: Count how many people signed up, purchased, or churned
Build conversion funnels: Track the path from first visit to purchase
Trigger automated workflows: Send email when user abandons cart
Personalize experiences: “You recently viewed these items”
Calculate business metrics: Revenue, engagement, retention rates

What Every Event Captures

Each event in Zixflow automatically records:

Who did it → userId (if known) or anonymousId (if not)
What they did → Event name like “Purchased” or “Signed Up”
When it happened → Timestamp, precise to the millisecond
Where it happened → Platform (web/iOS/Android), location, device type
How they did it → Context like browser, screen size, app version
Custom details → Properties you add (product name, price, category)

Event Structure

Here’s what a typical event looks like:

{
  "event_name": "Added to Cart",
  "user_id": "sarah@example.com",
  "timestamp": "2026-05-04T14:32:15Z",
  "properties": {
    "product_name": "Red Sneakers",
    "product_id": "prod_789",
    "price": 89.99,
    "currency": "USD",
    "quantity": 1
  },
  "context": {
    "platform": "web",
    "browser": "Chrome",
    "screen_size": "1920x1080",
    "country": "United States"
  }
}

Key parts:

event_name: The action that happened
properties: Custom details about this specific action
context: Automatically captured information about the user’s environment
timestamp: Exactly when it occurred

What makes events powerful: Once stored in Zixflow, you can search across millions of events instantly to find patterns, build segments, or trigger campaigns.

Event Types

Zixflow supports four types of events. Each serves a different purpose in tracking user behavior:

1. Track Events (Custom Actions)

What: The events you define based on what matters to your business. This is your primary event type for tracking user behavior. When to use:

User lifecycle milestones: Signed Up, Completed Onboarding, Upgraded Plan
Feature usage: Created Project, Ran Report, Exported Data
Revenue events: Subscribed, Payment Received, Refunded
Engagement: Invited Teammate, Shared Dashboard, Left Comment

Examples:

// JavaScript
Zixflow.track('Purchased', {
  order_id: 'ord_12345',
  revenue: 89.99,
  currency: 'USD',
  items: ['Red Sneakers', 'White Socks']
});

// Flutter/Dart
Zixflow.track(
  name: 'Purchased',
  properties: {
    'order_id': 'ord_12345',
    'revenue': 89.99,
    'currency': 'USD',
    'items': ['Red Sneakers', 'White Socks']
  }
);

What you can do with track events:

Build segments: “Users who purchased in the last 30 days”
Trigger campaigns: “Send thank-you email after Purchase event”
Run analytics: “What % of signups complete a purchase?”
Measure conversion: Track funnel from signup → activation → purchase ‘items’: [‘Red Sneakers’, ‘White Socks’], }, );

---

### 2. **Screen Events** (Mobile Navigation)

**What:** When a user views a screen in your mobile app (iOS, Android, React Native, Flutter).

**When to use:** Mobile applications where you want to track navigation flow.

**Examples:**
- `Home Screen`
- `Product Details`
- `Shopping Cart`
- `Checkout`
- `Profile Settings`

**Auto-tracking:** Our SDK can automatically track screen views when configured. You can also manually track specific screens.

**Database table:** `profile_events` with `event_type = 2` (screen)

**SDK call:**
```dart
// Flutter - Manual screen tracking
Zixflow.instance.screen(
  title: 'Product Details',
  properties: {
    'product_id': 'prod_789',
    'category': 'Shoes',
  },
);

Use cases:

Conversion funnel analysis: Signup → Activation → Paid conversion
Feature adoption tracking: % of users who’ve used Feature X
Campaign trigger conditions: “User upgraded to Pro” → Send thank-you email

What: When a user views a page on your website or web application. When to use: Web applications, marketing sites, content platforms. Examples:

/ (Homepage)
/pricing (Pricing page)
/blog/getting-started (Blog post)
/product/red-sneakers (Product page)
/checkout (Checkout page)

Auto-tracking: Can be configured to automatically track page views with our JavaScript SDK. Database table: profile_events with event_type = 3 (page) SDK call:

// JavaScript - Manual page tracking
Zixflow.page({
  name: 'Product Details',
  properties: {
    path: '/product/red-sneakers',
    url: 'https://store.example.com/product/red-sneakers',
    referrer: 'https://google.com/search',
    title: 'Red Sneakers - Example Store'
  }
});

Common use cases:

Track marketing campaign effectiveness
Understand content engagement
Build page-view funnels
Identify high-exit pages

4. Identify Events (User Identification)

What: Special event that links anonymous browsing history to a known user profile. Triggers identity resolution and profile creation/update. When to use:

Immediately after signup (new user)
On login (returning user)
When you learn identifying info (email capture via newsletter signup)

What happens on identify():

Creates or updates the user’s profile with the information you provide
Records when this identification happened (for audit purposes)
Identity merge: If you include both userId and anonymousId, Zixflow automatically:
- Finds all anonymous activity from this visitor
- Links it to the identified user profile
- Updates the user’s complete history
- Prevents duplicate merges (processes once)

SDK call:

// JavaScript - After signup/login
Zixflow.identify({
  userId: 'sarah@example.com',
  traits: {
    name: 'Sarah Johnson',
    email: 'sarah@example.com',
    plan: 'pro',
    created_at: '2026-05-04T10:00:00Z'
  }
});

// Flutter - After signup/login
Zixflow.instance.identify(
  userId: 'sarah@example.com',
  traits: {
    'name': 'Sarah Johnson',
    'email': 'sarah@example.com',
    'plan': 'pro',
    'created_at': '2026-05-04T10:00:00Z',
  },
);

What happens behind the scenes:

Creates or updates user profile with provided information
Records when identification occurred
If both userId + anonymousId provided:
- Triggers identity merge workflow (see Users & Identity)
- All anonymous events linked to identified user
- System prevents duplicate merges automatically
Subsequent events from this device/session use user_id instead of anonymous_id

Event Properties Explained

Properties add context to events. They answer: “What details matter about this action?”

Property Structure

Properties are key-value pairs attached to events:

Zixflow.track({
  name: 'Purchased',
  properties: {
    // Order info
    order_id: 'ord_12345',
    revenue: 89.99,
    currency: 'USD',
    
    // Product info
    product_name: 'Red Sneakers',
    product_id: 'prod_789',
    category: 'Shoes',
    
    // Context
    payment_method: 'credit_card',
    shipping_method: 'express',
    coupon_code: 'SAVE10'
  }
});

Common Property Patterns

Product properties:

product_id: Unique identifier
product_name: Human-readable name
sku: Stock keeping unit
category: Product category
brand: Manufacturer/brand
price: Unit price
currency: USD, EUR, etc.

Transaction properties:

order_id: Unique order identifier
revenue: Total amount
tax: Tax amount
shipping: Shipping cost
discount: Discount applied
payment_method: How they paid

User action context:

source: Where did they come from? (homepage, search, email)
referrer: Full referrer URL
search_term: What they searched for
filter_applied: Active filters
sort_order: How they sorted results

Keep It Simple

Rule of thumb: Only track properties you’ll actually use for:

Personalization (“You viewed Red Sneakers”)
Analysis (“Average order value by payment method”)
Triggered campaigns (“Coupon code was used”)

Don’t over-track:

❌ 50 properties per event (too much)
❌ Duplicate data (if it’s a user attribute, don’t put it in every event)
❌ Sensitive PII (passwords, credit card numbers, SSNs)

System vs Custom Events

System Events (Auto-Generated)

These events are created automatically by the system — you don’t need to call track() for them.

Device Lifecycle Events

Sent automatically by the SDK and routed to the device_logs table (not the main events table):

Event Name	When it fires
`Application Installed`	First launch after install
`Application Opened`	App moves to foreground
`Application Backgrounded`	App moves to background
`Application Foregrounded`	App returns from background (distinct from cold open)
`Application Crashed`	SDK detects an unhandled crash on next launch
`Device Created or Updated`	SDK registers or updates device info with Zixflow
`Device Registered`	Device token successfully registered for push
`Device Updated`	Device attributes changed (new OS version, app update, token rotation)

These events are stored with a 30-day retention window. They feed device health monitoring and platform analytics, but are separate from your business events.

User Lifecycle Events

These are server-side lifecycle events that change the state of a user profile. They carry no trait data — only the user ID and the action:

Lifecycle Event	Effect on profile
`User Deleted`	Sets `is_deleted = true` + cascades deactivation to all linked devices
`User Suppressed`	Sets `is_suppressed = true` — blocks all outbound messages on every channel
`User Unsuppressed`	Clears the suppressed flag — message delivery resumes

User Deleted and User Suppressed/Unsuppressed are triggered server-side (via the Track API v1 or your backend). You cannot trigger them from the client SDK.

Device Deletion

Lifecycle Event	Effect
`Device Deleted`	Soft delete: sets `active = false`, `push_enabled = false` on the device record

This stops push notifications being sent to that device without permanently removing the record.

Custom Events (You Define)

Everything else! You decide what matters for your business:

User actions: Clicked, Viewed, Purchased, Shared
Product usage: Feature used, Setting changed, Export created
Business events: Trial started, Plan upgraded, Referral sent
Content engagement: Article read, Video watched, Comment posted

When NOT to Use Events

Events are for actions. Attributes are for facts. Don’t confuse the two!

❌ Wrong: Tracking State Changes as Events

Bad example:

// DON'T DO THIS
Zixflow.track({ name: 'Became Premium User' });
Zixflow.track({ name: 'Email Changed to sarah@example.com' });
Zixflow.track({ name: 'Name Changed to Sarah Johnson' });

Why it’s wrong: These are attribute updates, not actions the user took.

✅ Right: Update Attributes + Track Action Event

Good example:

// Update the attribute (WHO they are)
Zixflow.setProfileAttributes({
  plan: 'premium',
  email: 'sarah@example.com',
  name: 'Sarah Johnson'
});

// Track the action (WHAT they did)
Zixflow.track({ 
  name: 'Upgraded Plan',
  properties: {
    from_plan: 'free',
    to_plan: 'premium'
  }
});

Why it’s right: The attribute stores the current state. The event records that the upgrade happened (for analytics and triggers).

Rule of Thumb

Use attributes for:

Current state: email, name, plan, status
Computed values: total_purchases, last_login, lifetime_value
Demographics: age, location, company

Use events for:

Actions: clicked, viewed, purchased, upgraded
One-time occurrences: signed_up, cancelled, shared
Timestamps: when things happened

Privacy Considerations

What NOT to Track

Never put these in event names or properties:

❌ Passwords or credentials
❌ Credit card numbers
❌ Social security numbers
❌ Medical information
❌ Full date of birth (age range is okay)

What’s Safe to Track

✅ User actions and behavior (clicked, viewed, purchased)
✅ Product data (names, prices, categories)
✅ Transaction IDs (order_id, session_id)
✅ Aggregated data (count, average, total)
✅ Email addresses (if user consented)
✅ Device information (platform, OS version) Users have the right to:

Access their data: Export all events via API
Delete their data: Remove all events and profile via DELETE /api/v1/customers/:id
Opt out: Stop tracking via unsubscribe/opt-out flags

Next: Learn how anonymous visitors become identified users → Users & Identity

​What is an Event?

​The Simple Definition

​Why Events Matter

​What Every Event Captures

​Event Structure

​Event Types

​1. Track Events (Custom Actions)

​3. Page Events (Web Navigation)

​4. Identify Events (User Identification)

​Event Properties Explained

​Property Structure

​Common Property Patterns

​Keep It Simple

​System vs Custom Events

​System Events (Auto-Generated)

​Device Lifecycle Events

​User Lifecycle Events

​Device Deletion

​Custom Events (You Define)

​When NOT to Use Events

​❌ Wrong: Tracking State Changes as Events

​✅ Right: Update Attributes + Track Action Event

​Rule of Thumb

​Privacy Considerations

​What NOT to Track

​What’s Safe to Track

​GDPR/CCPA Compliance