Choosing keys and attributes

Selecting appropriate keys and attributes is critical for effective feature flag targeting and progressive rollouts.

Choosing a key

A well-chosen key balances consistency and risk distribution during progressive rollouts.

Key characteristics

Unique: Static 1:1 mapping to a context

Each context instance must have a unique key that always identifies the same entity.

Opaque: Non-sequential, not derived from sensitive information

Keys should not be predictable or contain sensitive data like email addresses or social security numbers.

High cardinality: Many unique values will be seen by the application

Ensure the key space is large enough to support meaningful percentage rollouts. Low cardinality (like “true”/“false”) prevents fine-grained rollout control.

Rollout consistency

The key is used as the default attribute for percentage rollouts. This applies to any attribute you plan on using for rollouts.

Example: Session consistency

To maintain consistency pre and post-login, use a session context instead of a user context for rollouts:

// Session context persists across authentication
const sessionContext = {
  kind: "session",
  key: generateSessionId(), // UUID stored in session storage
  anonymous: true
};

Configure rollouts by session key to ensure users see consistent behavior whether logged in or not.

Defining attributes

Create attributes that support your targeting and rollout use cases.

Do

Create multiple identifiers for different contexts and consistency boundaries

Define separate context kinds for user, session, device, etc., each with appropriate attributes:

const multiContext = {
  kind: "multi",
  user: {
    key: "user-123",
    name: "Jane Doe",
    createdAt: 1640000000000
  },
  session: {
    key: "session-abc",
    anonymous: true,
    startedAt: Date.now()
  }
};

Create attributes that support targeting and rollout use-cases

Include attributes you’ll actually use for targeting:

const userContext = {
  kind: "user",
  key: "user-123",
  email: "jane@example.com",
  plan: "enterprise",
  region: "us-west",
  betaTester: true
};

Define private attributes when targeting on sensitive information

Mark sensitive attributes as private to prevent them from being sent to LaunchDarkly:

const userContext = {
  kind: "user",
  key: "user-123",
  email: "jane@example.com",
  _meta: {
    privateAttributes: ["email", "ipAddress"]
  }
};

Do not

Use any values derived from PII or sensitive values as keys

Never use email addresses, phone numbers, or other PII directly as keys:

// Bad
const context = { kind: "user", key: "jane@example.com" };

// Good
const context = {
  kind: "user",
  key: "user-123",
  email: "jane@example.com",
  _meta: { privateAttributes: ["email"] }
};

Rapidly change attributes in client-side SDKs

Avoid using current timestamp or frequently changing values as attributes:

// Bad - causes excessive events
const context = {
  kind: "user",
  key: "user-123",
  lastActivity: Date.now() // Changes every render
};

// Good - use stable attributes
const context = {
  kind: "user",
  key: "user-123",
  sessionStart: sessionStartTime // Stable for session
};

Mix value types or sources for an attribute within the same project

Keep attribute types consistent across your codebase:

// Bad - inconsistent types
// iOS app sends: { plan: "enterprise" }
// Web app sends: { plan: 3 }

// Good - consistent types
// All apps send: { plan: "enterprise" }

Attribute naming conventions

Follow these conventions for consistency:

• Use camelCase for attribute names: userId, planType, isActivated
• Use clear, descriptive names: prefer accountCreationDate over acd
• Prefix boolean attributes with is, has, or can: isActive, hasAccess, canEdit
• Use standard date formats: RFC3339 strings or Unix timestamps in milliseconds

Multi-kind contexts

For complex targeting scenarios, use multi-kind contexts to evaluate against multiple entities simultaneously:

const multiContext = {
  kind: "multi",
  user: {
    key: "user-123",
    email: "jane@example.com",
    plan: "enterprise"
  },
  organization: {
    key: "org-456",
    name: "Acme Corp",
    industry: "technology"
  },
  device: {
    key: "device-789",
    platform: "iOS",
    model: "iPhone 14"
  }
};

This allows targeting rules like “serve to users in enterprise plan OR organizations in technology industry”.