Custom Properties

Create and manage custom user properties to store additional data and enhance personalization

Custom properties allow you to store additional information about your users beyond the standard profile fields. They enable deeper personalization, better segmentation, and more targeted marketing campaigns by capturing business-specific data that matters to your organization.

What are Custom Properties?

Custom properties are additional data fields you can attach to user profiles to store:

• Business-specific Information: Customer type, account tier, industry
• Behavioral Data: Preferences, settings, usage patterns
• Calculated Values: Lifetime value, engagement score, risk rating
• External System Data: CRM IDs, support ticket counts, subscription details
• Demographic Information: Company size, job title, location details

Unlike standard user properties (name, email, phone), custom properties are completely flexible and defined by your business needs.

How Custom Properties are Created

Custom properties can be created in several ways:

1. Automatic Creation from Events

When Flywheel receives user data through events with identify: true, it automatically creates custom properties from properties within a $set object:

// When this event is received with identify: true
{
  user_id: 'user123',
  event: 'user_signup',
  identify: true,
  properties: {
    email: '[e-mail]',
    first_name: 'John',
    $set: {
      company_size: '50-100',      // → Creates "company_size" custom property
      industry: 'Technology',      // → Creates "industry" custom property
      utm_source: 'google_ads',    // → Creates "utm_source" custom property
      trial_type: 'premium'        // → Creates "trial_type" custom property
    }
  }
}

// Flywheel automatically creates custom properties for each field in $set
// Properties outside $set are not added as custom properties

Only properties within the $set object are extracted as custom properties. Standard user properties (email, first_name, last_name, phone, etc.) can still be passed at the root level of properties and will be set on the user record directly.

2. Manual Creation in Settings

Create custom properties manually for better control and organization:

1. Navigate to Settings

   • Go to Settings → Users → Custom Properties
   • Click Add Custom Property

Custom Properties Settings

Access custom properties configuration and management

2. Define the Property

   • Name: Internal name used in API calls and data
   • Display Name: Human-readable name for the UI
   • Description: Explain what the property represents
   • Type: Choose the data type (string, number, boolean, date)

3. Configure Options

   • Required: Whether the property is mandatory
   • Default Value: Set a default if no value is provided
   • Validation Rules: Set constraints on acceptable values

Property Types

Flywheel supports several property types to match your data:

String Properties

Text-based information:

{
  industry: 'Technology',
  customer_tier: 'premium',
  preferred_language: 'en',
  utm_source: 'google_ads'
}

Number Properties

Numeric values for calculations and comparisons:

{
  lifetime_value: 1250.00,
  login_count: 45,
  support_tickets: 3,
  engagement_score: 85
}

Boolean Properties

True/false flags for binary characteristics:

{
  is_premium_user: true,
  email_verified: false,
  has_mobile_app: true,
  opted_in_marketing: false
}

Date Properties

Timestamp-based information:

{
  trial_end_date: '2024-02-15T00:00:00Z',
  last_purchase_date: '2024-01-10T14:30:00Z',
  onboarding_completed_date: '2024-01-05T09:15:00Z'
}

Managing Custom Properties

Viewing Custom Properties

Access custom properties in several ways:

Settings Dashboard

• Property List: See all defined custom properties
• Usage Statistics: View which properties are most used
• Data Types: Review property types and configurations
• Validation Rules: Check constraints and requirements

User Profiles

• Individual User View: View and edit custom property values for specific users

View User Profiles

Access individual user profiles and custom property values

Editing Custom Properties

Update custom property configurations:

1. Navigate to Property Settings

   • Go to Settings → Users → Custom Properties
   • Click on the property you want to edit

Edit Custom Properties

Modify existing custom property configurations

2. Modify Configuration

   • Update display name or description
   • Change validation rules
   • Modify default values
   • Adjust property type (with caution)

3. Impact Assessment

   • Review existing data before making changes
   • Consider impact on segments and workflows
   • Test changes in staging environment first