User Properties

Set persistent cross-session properties on users for advanced filtering and segmentation.

Overview#

User properties are persistent key-value pairs attached to a visitor that carry across sessions. Unlike event tags (which are scoped to a single event), user properties persist indefinitely and are available in every subsequent session. Use them to enrich analytics with business context like subscription plan, user role, or lifetime value.

Setting User Properties#

Single Property#

// Set a single user property
JA.setUserProperty('plan', 'enterprise');

Multiple Properties#

// Set multiple properties at once
JA.setUserProperties({
  plan: 'enterprise',
  role: 'admin',
  company: 'Acme Inc',
  lifetime_value: 2499.99,
  signup_date: '2026-01-15',
});

Server-Side (Node.js SDK)#

import JA from '@justanalyticsapp/node';

// Set user properties from the server
JA.setUserProperties({
  userId: 'user_123',
  properties: {
    plan: 'enterprise',
    mrr: 299.99,
    team_size: 15,
    last_payment_date: '2026-03-01',
  },
});

Property Limits#

| Limit | Value | |-------|-------| | Max properties per site | 25 | | Key max length | 100 characters | | String value max length | 500 characters | | Numeric value range | Standard 64-bit float | | Allowed value types | String, Number, Boolean |

What Counts Toward the Limit#

Only unique property keys count toward the 25-property limit. Setting the same key for different visitors does not consume additional slots.

Exceeding the Limit#

If you attempt to set a 26th unique property key, the call is silently ignored and a warning is logged to the browser console (or server logs for the Node.js SDK). Delete unused properties in Settings > User Properties to free up slots.

Property Types#

| Type | Example | Use Case | |------|---------|----------| | String | "enterprise" | Plan names, roles, company names | | Number | 299.99 | Revenue, scores, counts | | Boolean | true | Feature flags, opt-in status |

Using Properties as Filters#

Once set, user properties appear as filter options across all analytics pages.

In Analytics Pages#

Open any analytics page (Overview, Analytics, Pages, Events, etc.)
Click the Filter dropdown
Under User Properties, select the property you want to filter by
Choose an operator and value

Example filters:

plan is "enterprise" -- show only enterprise users
lifetime_value greater than 1000 -- show high-value users
role is "admin" -- show only admin users

In Segments#

User properties are available as segment conditions:

Go to Segments and click Create Segment
Add a condition using User Property fields
Combine with behavioral conditions

Example segment: "Enterprise admins on mobile"

User Property: plan is "enterprise"
User Property: role is "admin"
Device Type: mobile

In Discover Queries#

User properties are available as columns, filters, and group-by fields in Discover:

Data Source: Events
Columns: plan, count(), count_unique(visitorHash)
Group By: plan
Order By: count() DESC

In Reports#

Standard and custom reports can be filtered by user properties. Scheduled reports can target specific user property values.

User Properties vs Event Tags#

Understanding the difference between user properties and event-level tags is important for choosing the right approach:

| Aspect | User Properties | Event Tags | |--------|----------------|------------| | Scope | Persistent across all sessions | Single event only | | Set by | JA.setUserProperty() | Included in JA.track() properties | | Persistence | Until explicitly changed or deleted | None (event-level only) | | Limit | 25 per site | 20 per event | | Best for | User-level attributes that rarely change | Event-specific context | | Examples | Plan tier, role, company, LTV | Button color, form name, product ID |

When to Use User Properties#

The value describes who the user is, not what they did
The value persists across sessions (e.g., subscription plan)
You want to filter all analytics by this dimension
The value changes infrequently

When to Use Event Tags#

The value describes what happened in a specific event
The value varies per event (e.g., product ID in a purchase event)
You only need it in the context of that event type
The value is specific to the action, not the user

Common Use Cases#

Subscription Plan Tracking#

// After authentication or plan change
JA.setUserProperty('plan', user.plan);       // 'free', 'pro', 'enterprise'
JA.setUserProperty('plan_started', user.planStartDate);

Then filter analytics to see behavior differences between free and paid users.

User Role Analysis#

JA.setUserProperty('role', user.role);       // 'viewer', 'editor', 'admin'
JA.setUserProperty('team_id', user.teamId);

Understand which roles use which features most frequently.

Lifetime Value Tracking#

// Update after each purchase
JA.setUserProperty('lifetime_value', user.totalSpend);
JA.setUserProperty('purchase_count', user.purchaseCount);
JA.setUserProperty('last_purchase_date', new Date().toISOString().split('T')[0]);

Segment users by value tier for targeted campaigns.

Feature Flag Tracking#

// After feature flag evaluation
JA.setUserProperties({
  ff_new_checkout: isEnabled('new_checkout'),
  ff_ai_search: isEnabled('ai_search'),
});

Measure the impact of feature flags on engagement and conversions.

Company/Account-Level Properties#

JA.setUserProperties({
  company: account.name,
  company_size: account.employeeCount,
  industry: account.industry,
  region: account.region,
});

Analyze product usage patterns by company attributes.

Go to Settings > User Properties
Click the delete icon next to the property
Confirm deletion

Deleting a property removes the key definition and frees up a slot. Historical data associated with the property is retained but no longer filterable.

Updating a Property#

Setting a property with the same key overwrites the previous value:

// User upgrades from pro to enterprise
JA.setUserProperty('plan', 'enterprise');  // overwrites 'pro'

The update takes effect immediately for all subsequent events and sessions.