Attributes vs. Events

Not sure whether to use an attribute or an event? This guide will help you decide.

Quick Comparison

	Attributes	Events
Purpose	Describe who the user is	Track what the user did
Question	"What's their current state?"	"What action did they take?"
Think of it as	Nouns & Adjectives	Verbs
Examples	plan, role, company, teamSize	project_created, file_exported
How it changes	Replaces previous value	Accumulates over time
History	Only current value stored	Full history stored
Method	Cueflow.init() / update()	Cueflow.track()

The Simple Rule

Attributes = WHO they are Events = WHAT they did

When to Use Attributes

Use attributes when you're storing information about the user:

Cueflow.init({
  id: 'user-123',

  // These are all ATTRIBUTES
  plan: 'pro',           // Current subscription
  role: 'admin',         // Current role
  company: 'Acme Inc',   // Company name
  teamSize: 50,          // Team size
  onboardingComplete: true  // Current state
});

Good for:

• Subscription plans

• User roles

• Company information

• Feature flags

• Current states (verified, active, trialing)

When to Use Events

Use events when tracking actions the user takes:

// These are all EVENTS
Cueflow.track('project_created');
Cueflow.track('file_exported', { format: 'csv' });
Cueflow.track('team_member_invited');
Cueflow.track('feature_used', { feature: 'analytics' });

Good for:

• Feature usage

• Milestone completions

• User actions

• Behaviors you want to count or time

Common Scenarios

Scenario	Attribute	Event
User is on Pro plan	plan: 'pro'	-
User upgrades to Pro	plan: 'pro'	plan_upgraded
User has 5 projects	projectCount: 5	-
User creates a project	-	project_created
User completed onboarding	onboardingComplete: true	onboarding_completed
User is an admin	role: 'admin'	-
User exports data	-	data_exported

When to Use Both

Sometimes you'll use both for the same action:

async function handleUpgrade(newPlan) {
  await api.upgradePlan(newPlan);

  // EVENT: Track that upgrade happened
  Cueflow.track('plan_upgraded', {
    from: 'free',
    to: newPlan
  });

  // ATTRIBUTE: Update current plan
  Cueflow.update({ plan: newPlan });
}

Why both?

Goal	Use
"Show message to users who upgraded in the last 7 days"	Event
"Show message to Pro users"	Attribute
"Show message to users who upgraded more than 3 times"	Event
"Show message to users who are NOT on Pro plan"	Attribute

Targeting Differences

Attribute Targeting

Simple current-state checks:

plan equals "free"
role equals "admin"
teamSize greater than 50
onboardingComplete equals false

Event Targeting

Behavior-based with time and count:

project_created has done
project_created has not done
file_exported count greater than 10
onboarding_completed first done within 7 days
feature_used last done before 30 days

Decision Flowchart

Is it something the user DID (an action)?
├── Yes → Use EVENT
│         Can it happen multiple times?
│         ├── Yes → Definitely EVENT
│         └── No → EVENT (but maybe also update an attribute)
│
└── No → Is it something the user IS (a state)?
         └── Yes → Use ATTRIBUTE

Examples by Use Case

Onboarding

What you're tracking	Type	Code
User started onboarding	Event	Cueflow.track('onboarding_started')
User completed step 2	Event	Cueflow.track('onboarding_step_completed', { step: 2 })
User finished onboarding	Event	Cueflow.track('onboarding_completed')
User has finished onboarding	Attribute	Cueflow.update({ onboardingComplete: true })

Feature Adoption

What you're tracking	Type	Code
User used the export feature	Event	Cueflow.track('export_used')
User has ever used export	Attribute	Cueflow.update({ hasUsedExport: true })
How many times user exported	Event	Query event count
User's preferred export format	Attribute	Cueflow.update({ preferredExportFormat: 'csv' })

Subscriptions

What you're tracking	Type	Code
User upgraded their plan	Event	Cueflow.track('plan_upgraded')
User's current plan	Attribute	Cueflow.update({ plan: 'pro' })
User started a trial	Event	Cueflow.track('trial_started')
User is currently trialing	Attribute	Cueflow.update({ isTrialing: true })

Summary

Remember	Attributes	Events
Question	Who is this user?	What did they do?
Grammar	Nouns (plan, role)	Verbs (created, exported)
Changes	Overwrites	Accumulates
Targeting	Current state	History & counts
Method	init() / update()	track()

Still unsure? Ask yourself: "Can this happen multiple times?"

• Yes → Event

• No, it's a current state → Attribute