Attributes - Zixflow Docs

Attributes store the current state of users, devices, and events. Understanding when to use attributes vs events is critical for building an effective data model that supports both analytics and personalization.

What are Attributes?

Attributes are facts that describe who a user is, what device they’re on, or what happened in an event. Think of them as the labels on a record — name, email, plan type, device model, event revenue. While events are verbs (actions), attributes are adjectives (descriptions).

The Simple Definition

If you can describe it as “This user IS X” or “This event HAS property Y,” it’s an attribute. Examples:

“Sarah’s email is sarah@example.com” → User attribute: email
“John’s plan type is Enterprise” → User attribute: plan_type
“This device is an iPhone 15 Pro on iOS 17” → Device attribute: model, os_version
“This purchase had revenue of $89.99” → Event property: revenue

Why Attributes Matter

Attributes are essential because they enable:

Personalization: "Hi {{name}}, your {{plan}} trial expires in {{days_remaining}} days"
Targeting: Send campaigns only to users matching specific criteria
Context: Understand who’s behind each event (“This purchase was from an Enterprise customer”)
Enrichment: Connect user data from your CRM, support system, or other tools
Current state queries: “How many Pro plan users do we have right now?”

The Key Difference: State vs Action

Attributes store current state (one value that changes over time):

User’s current email: sarah@example.com → changes if they update it
User’s current plan: pro → changes when they upgrade to enterprise
Last login date: 2026-05-04 → updates every time they log in

Events record actions (immutable history):

Event: Updated Email at 2026-01-15 → never changes, always part of history
Event: Upgraded Plan at 2026-03-20 → permanent record of this action
Event: Logged In at 2026-05-04 10:30:15 → specific moment captured

The rule: Use attributes when you need to know “what IS true about this user right now.” Use events when you need to know “what DID this user do.”

Real-World Example

Sarah’s user attributes:

{
  email: "sarah@example.com",          // Current email
  name: "Sarah Johnson",               // Current name
  plan_type: "enterprise",             // Current plan (was 'pro' before)
  company: "Acme Corp",                 // Current company
  signup_date: "2026-01-15",           // Doesn't change
  total_purchases: 12,                  // Increments with each purchase
  lifetime_value: 1247.88,              // Calculated from all purchases
  last_login_at: "2026-05-04T10:30:15Z" // Updates each login
}

Sarah’s event history:

[
  { event: "Signed Up",        timestamp: "2026-01-15T09:00:00Z" },
  { event: "Purchased",        timestamp: "2026-01-20T14:30:00Z", amount: 89.99 },
  { event: "Upgraded Plan",    timestamp: "2026-03-20T11:15:00Z", from: "pro", to: "enterprise" },
  { event: "Purchased",        timestamp: "2026-05-01T16:45:00Z", amount: 149.99 },
  { event: "Logged In",        timestamp: "2026-05-04T10:30:15Z" }
  // ... 100 more events
]

Notice:

Attributes show her current state: She’s enterprise now (not pro)
Events show her complete history: We can see she upgraded on March 20th
Together they give the full picture: Who she is + What she’s done

Attributes vs Events: The Data Modeling Decision

Events = Actions (verbs) → user.track('Upgraded Plan')
Attributes = State (adjectives) → user.plan_type = 'enterprise'

The Rule

Use attributes when:

You need current state: “What plan are they on right now?”
You need to personalize: "Hi {{name}}, your trial ends {{trial_ends_at}}"
It’s a fact about the user: Demographics, account info, preferences

Use events when:

You need to trigger workflows: “When user upgrades → send thank-you email”
You need analytics: “How many users upgraded this month?”
You need history: “When did they last log in?”
It’s an action: Clicked, viewed, purchased, upgraded

Common Mistake: Tracking State as Events

❌ Wrong:

// Don't do this
track('Email Changed', { new_email: 'user@new-domain.com' });
track('Became Enterprise Customer');
track('Credit Card Updated');

Why it’s wrong: These are state updates, not user actions. You’re creating noise in your event stream. ✅ Right:

// Update the attribute
setProfileAttributes({
  email: 'user@new-domain.com',
  plan_type: 'enterprise',
  payment_method_updated_at: '2026-05-04T10:00:00Z'
});

// Track the action that caused the change (if relevant)
track('Upgraded Plan', {
  from_plan: 'pro',
  to_plan: 'enterprise',
  mrr_change: 200
});

Why it’s right: Attribute stores current state for queries and personalization. Event records the action for analytics and workflow triggers.

Three Types of Attributes

1. User Attributes

User attributes are facts stored on the user profile, identified by user_id. They come in two kinds: system-defined fields (always present, set by the platform) and traits (custom key-value data you send via identify() or setProfileAttributes()).

System-Defined Fields

These fields exist on every user profile automatically:

Field	Description
`id`	Internal Sonyflake BIGINT primary key
`user_id`	Your application’s identifier for this user
`anonymous_id`	The anonymous ID before identification
`name`	From traits
`email`	From traits
`phone`	From traits
`timezone`	IANA timezone, e.g. `America/New_York`
`language`	ISO 639-1 code, e.g. `en`
`email_opt_out`	Channel opt-out status (1=not opted out, 2=opted out, 3=unknown)
`sms_opt_out`	Same 3-state model
`whatsapp_opt_out`	Same 3-state model
`rcs_opt_out`	Same 3-state model
`push_opt_out`	Same 3-state model
`*_opt_out_at`	Timestamp when each opt-out occurred
`first_seen_at`	Timestamp of first identify call
`last_seen_at`	Timestamp of most recent identify call
`last_activity_at`	Timestamp of most recent event
`is_deleted`	Set to true by `User Deleted` lifecycle event
`is_suppressed`	Set to true by `User Suppressed` lifecycle event
`deleted_at` / `suppressed_at`	When those states were applied
`first_campaign_source/medium/name/term/content`	First-touch UTM attribution
`first_referrer`	Referring URL from first visit
`signup_platform`	Platform at time of first identify
`creation_source`	How the profile was created
`external_id`	Optional external system identifier
`customer_created_at`	User’s creation time in your own system
`created_at` / `updated_at` / `processed_at`	System timestamps

Traits (Custom Attributes)

Anything you pass in traits via identify() or via setProfileAttributes() is stored as a custom trait and merged with existing data:

// On identify (signup/login)
Zixflow.instance.identify(
  userId: 'user_12345',
  traits: {
    'plan_type': 'enterprise',
    'company': 'Acme Corp',
    'mrr': 499,
    'trial_ends_at': '2026-06-01T00:00:00Z',
  },
);

// Update anytime — merges with existing traits
Zixflow.instance.setProfileAttributes({
  'last_upgraded_at': '2026-05-04T10:00:00Z',
  'feature_flags': ['beta_reports', 'new_dashboard'],
});

Traits are schema-less — you define the keys. All trait keys are automatically catalogued for use in queries and targeting.

2. Device Attributes

Device attributes are facts stored on a device record, identified by device_id (derived from the push token). Like user attributes, they split into system-defined fields and custom traits.

System-Defined Fields

Field	Description
`device_id`	Internal device ID (derived from token hash)
`token`	Push token (FCM/APNs)
`platform`	`ios` or `android`
`manufacturer`	e.g. `Apple`, `Samsung`
`model`	e.g. `iPhone 15 Pro`, `Pixel 8`
`os_name`	e.g. `iOS`, `Android`
`os_version`	e.g. `17.4.1`, `14`
`app_version`	Your app’s version string
`sdk_version`	Zixflow SDK version
`screen_width` / `screen_height` / `screen_density`	Display info
`locale`	e.g. `en-US`
`timezone`	IANA timezone
`carrier`	Mobile carrier name
`active`	`false` after `Device Deleted` lifecycle event
`push_enabled`	Whether the device can receive push
`last_used_at`	Last time SDK sent an event from this device
`created_at` / `updated_at` / `processed_at`	System timestamps

Traits (Custom Attributes)

Custom key-value data you attach to a specific device:

Zixflow.instance.setDeviceAttributes({
  'notification_categories': ['promotions', 'transactional'],
  'dark_mode_enabled': true,
  'preferred_locale': 'en-US',
});

Use cases:

Target specific app versions: “Send ‘Update Available’ push to devices on v1.x”
Platform-specific campaigns: “iOS-only feature announcement”
Notification category filtering

3. Event Properties

Event properties are the custom key-value pairs attached to individual events. Unlike user or device attributes (which describe current state), event properties are immutable — they record the details of a specific moment in time.

Anatomy of an Event with Properties

{
  "event_name": "Order Completed",
  "user_id": "user_12345",
  "anonymous_id": null,
  "timestamp": "2026-05-04T14:32:15Z",
  "properties": {
    "order_id": "ord_789",
    "revenue": 129.99,
    "currency": "USD",
    "product_name": "Nike Air Max 90",
    "payment_method": "credit_card"
  },
  "context": {
    "platform": "ios",
    "app": { "version": "2.1.0" },
    "os": { "name": "iOS", "version": "17.4.1" },
    "device": { "model": "iPhone 15 Pro" },
    "locale": "en-US",
    "timezone": "America/New_York"
  }
}

System-Defined Event Fields

Every event has these fields set automatically:

Field	Description
`event_name`	The name you pass to `track()` / `screen()` / `page()`
Event type	Track, screen, page, or identify (set by which SDK method you call)
`user_id`	Set if user is identified
`anonymous_id`	Set if user is anonymous
`timestamp`	When the event occurred (millisecond precision)
`context`	Platform, device, OS, app version, locale, timezone — captured by SDK

Custom Properties

The properties object is fully custom — you define the keys and values:

Zixflow.instance.track('Purchased', properties: {
  'order_id': 'ord_123',
  'revenue': 89.99,
  'currency': 'USD',
  'product_name': 'Red Sneakers',
  'payment_method': 'credit_card',
});

All property keys are automatically catalogued for use in queries and campaign conditions. Note: Event properties live on the event record (with their own retention), not on the user profile. User attributes store current state; event properties describe that specific action.

Automatic Attribute Discovery

Zixflow automatically learns what attributes exist based on the data you send - no need to define a schema upfront.

How It Works

You track an event with properties:

Zixflow.track('Purchased', {
  order_id: 'ord_123',
  product_name: 'Enterprise Plan',
  revenue: 499.00,
  currency: 'USD',
  payment_method: 'credit_card'
});

Zixflow automatically:

Discovers all the property names (order_id, product_name, revenue, etc.)
Figures out their data types (order_id is text, revenue is a number)
Makes them available for querying and filtering

Now you can:

Segment: “Users who purchased where product_name = ‘Enterprise Plan’”
Analyze: “Top 10 products by revenue”
Filter: “Show events where payment_method = ‘credit_card’”

Benefits: ✅ No schema setup — Just start tracking, Zixflow learns automatically
✅ Self-documenting — See what attributes you’re actually using
✅ Type checking — Zixflow warns if data types don’t match
✅ Easy filtering — All attributes available for querying

Reserved Attribute Names

These attribute names are reserved for system use. Don’t use them as custom attributes: User-level:

id, workspace_id, user_id, email, anonymous_id
created_at, updated_at, last_seen_at

Device-level:

device_id, device_token, platform, last_seen_at

If you try to set a reserved attribute:

System logs a warning
Value is ignored (not written)
Original system value preserved

Next: Understand how events flow through Zixflow → The Data Journey

​What are Attributes?

​The Simple Definition

​Why Attributes Matter

​The Key Difference: State vs Action

​Real-World Example

​Attributes vs Events: The Data Modeling Decision

​The Rule

​Common Mistake: Tracking State as Events

​Three Types of Attributes

​1. User Attributes

​System-Defined Fields

​Traits (Custom Attributes)

​2. Device Attributes

​System-Defined Fields

​Traits (Custom Attributes)

​3. Event Properties

​Anatomy of an Event with Properties

​System-Defined Event Fields

​Custom Properties

​Automatic Attribute Discovery

​How It Works

​Reserved Attribute Names

What are Attributes?

The Simple Definition

Why Attributes Matter

The Key Difference: State vs Action

Real-World Example

Attributes vs Events: The Data Modeling Decision

The Rule

Common Mistake: Tracking State as Events

Three Types of Attributes

1. User Attributes

System-Defined Fields

Traits (Custom Attributes)

2. Device Attributes

System-Defined Fields

Traits (Custom Attributes)

3. Event Properties

Anatomy of an Event with Properties

System-Defined Event Fields

Custom Properties

Automatic Attribute Discovery

How It Works

Reserved Attribute Names