User and Group Properties

Appcues accepts four primitive data types for user and group properties: strings, numbers, booleans, and dates. Any value passed via Appcues.identify() or Appcues.group() that doesn't match one of these types — such as arrays or nested objects — is silently ignored.

Strings

Use strings for text-based attributes like names, email addresses, plan names, or roles.

Appcues.identify("user-123", {
  name: "Ada Lovelace",
  email: "ada@example.com",
  role: "admin",
  plan: "enterprise"
});

Keep in mind:

• String comparisons are case-sensitive. "Admin" and "admin" are treated as different values. Pick a casing convention and stick with it across your codebase.
• Do not send an empty string ("") to represent a missing value. If a value doesn't exist, either omit the property entirely or send null.
• Strings that look like numbers (e.g. "42") are still treated as strings. This changes how comparisons work — the string "9" is greater than "10" in a string comparison. Send numeric values as actual numbers.

Numbers

Use numbers for counts, amounts, scores, or any quantitative attribute.

Appcues.identify("user-123", {
  totalLogins: 47,
  teamSize: 12,
  npsScore: 9,
  mrr: 249.99
});

Keep in mind:

• Send numbers as their native JavaScript type — not as strings. The number 10 is greater than 2, but the string "10" is less than "2" because string comparison is character-by-character.
• Appcues supports both integers and floating-point numbers.
• If you use a number to represent a date (UNIX timestamp), see the Dates section below for formatting requirements.

Booleans

Use booleans for true/false flags.

Appcues.identify("user-123", {
  isAdmin: true,
  hasCompletedOnboarding: false,
  emailVerified: true
});

Keep in mind:

• Send true or false — not the strings "true" or "false". Appcues uses type inference, so a string "false" is truthy in some comparison contexts and can produce unexpected targeting results.
• Booleans are useful for feature-flag targeting, onboarding status, and permission-based segmentation.

Dates

Use dates for any time-based property like sign-up dates, trial expiration, subscription renewal, or last-active timestamps.

Appcues recognizes dates in three formats. Pick one format per property and use it consistently every time you send that property:

// UNIX timestamp (seconds since epoch)
Appcues.identify("user-123", {
  createdAt: 1735689600
});

// ISO 8601
Appcues.identify("user-123", {
  createdAt: "2025-01-01T00:00:00Z"
});

// Formatted string
Appcues.identify("user-123", {
  createdAt: "Jan 1, 2025 12:00:00 AM"
});

Keep in mind:

• Appcues uses UNIX Epoch timestamps internally. Whatever format you send, it's converted to a timestamp behind the scenes.
• Unsupported formats — such as 06/20/2025, 2025/01/01, or 20-Jan-2025 — cannot be used in date-type targeting conditions. Appcues won't reject these values, but they'll be treated as plain strings, and date operators (before, after, within the last X days) won't work.
• UNIX timestamps must be non-fractional (whole seconds, not milliseconds). If your system produces millisecond timestamps, divide by 1000 before sending.
• Mixing formats for the same property across users causes inconsistent targeting. For example, if some users have createdAt as a timestamp and others have it as an ISO string, date comparisons may behave unpredictably.
• You can set the expected data type for any property in Settings > Data > Properties in Studio. This is especially helpful for UNIX timestamps, which Appcues might otherwise interpret as a number. Explicitly setting the type to "Date" ensures correct formatting in reports and targeting menus.

Objects and Arrays

Objects and arrays are not supported as property values. If you pass them, Appcues silently drops them — no error, no warning.

If you need information from a complex data structure, flatten it into individual primitive properties before calling Appcues.identify().

Before (won't work):

// Objects are ignored
Appcues.identify("user-123", {
  subscription: {
    plan: "pro",
    status: "active",
    renewalDate: "2025-06-01T00:00:00Z"
  }
});

After (works):

// Flatten into primitives
Appcues.identify("user-123", {
  subscriptionPlan: "pro",
  subscriptionStatus: "active",
  subscriptionRenewalDate: "2025-06-01T00:00:00Z"
});

For more complex structures like arrays of records, reduce the array to the properties you actually need for targeting:

var invoices = user.invoices || [];
var totalInvoices = invoices.length;
var lastInvoiceDate = (invoices[0] || {}).created_at;

Appcues.identify(user.id, {
  name: user.name,
  email: user.email,
  totalInvoices: totalInvoices,
  lastInvoiceDate: lastInvoiceDate
});

Null and Undefined Values

• If a property has no value, either omit it from the identify() call or send it as null.
• Do not send an empty string ("") for a missing value. An empty string is a valid string value and will match exists conditions in targeting — which is probably not what you want.
• If you previously sent a property for a user and that property no longer applies, send null to clear it. Omitting it from a later identify() call does not remove the previously stored value.

Type Consistency

Every property should have the same type for every user, every time it's sent. Appcues uses type inference to decide how to evaluate targeting conditions, and mixed types cause problems.

Common mistakes:

• Sending plan as "free" for some users and 0 for others.
• Sending createdAt as an ISO string for web users but as a UNIX timestamp for mobile users.
• Sending teamSize as the number 5 from your backend but as the string "5" from a form submission.

If you notice unexpected targeting behavior, check the user's profile in Studio to confirm the property value and type match what you expect.

Group Properties

Group properties follow the same data type rules as user properties — strings, numbers, booleans, and dates only. No objects or arrays.

Group properties are sent via Appcues.group() and describe the account or organization a user belongs to, rather than the individual user.

Appcues.group("account-456", {
  companyName: "Acme Corp",
  industry: "Technology",
  employeeCount: 4500,
  plan: "enterprise",
  accountCreatedAt: "2024-03-15T00:00:00Z"
});

Keep in mind:

• Call Appcues.identify() before Appcues.group(). The user must be identified first for the group association to work.
• Group properties are available for targeting just like user properties. Use them when every user in an account shares the same attribute (plan type, account status, renewal date).
• If you're installed via Segment, RudderStack, or Freshpaint, Appcues receives group data from your existing group() calls — no additional setup needed, as long as the source is connected to the Appcues destination.

Events

Events represent actions users take in your product. They are sent to Appcues via Appcues.track(), Click-to-Track (no-code), or through a partner integration like Segment.

Event Name (Required)

Every event must have a name. The name is the unique identifier for that event across Appcues.

Appcues.track("Clicked Purchase Button");

Keep in mind:

• Event names are case-sensitive. "Clicked Purchase Button" and "clicked purchase button" are treated as separate events.
• Do not reuse the same name for different actions. Each distinct user action should have its own event name.
• If you have Appcues installed on both web and a mobile app, use different event names for each platform. Using the same name causes events from both platforms to be pooled together, making it impossible to distinguish where the event occurred.
• Changing the format or naming convention of an event creates a new, separate event in Appcues. For example, renaming "Clicked Purchase Button" to "clicked_purchase_button" produces two distinct events.
• Establish a naming convention early (e.g. Verb + Object like "Uploaded Document", "Invited Teammate", "Updated Profile") and document it for your team.

Event Attributes (Optional)

Event attributes provide additional context about a specific occurrence of an event. They are passed as the second argument to Appcues.track().

Appcues.track("Clicked Purchase Button", {
  plan: "enterprise",
  billingCycle: "annual",
  discountApplied: true
});

Keep in mind:

• Event attributes support the same primitive types as user properties: strings, numbers, and booleans.
• Event attributes are not visible in Studio or standard reporting. They can currently only be used with Event Triggering to conditionally trigger a Flow based on the attribute values of a specific event occurrence.
• For example, you could trigger a specific Flow only when plan equals "enterprise" on a "Clicked Purchase Button" event, while ignoring occurrences where plan is "starter".
• Event Triggering is available on select plans. Check your account details page or contact the Appcues team for availability.

Event Targeting vs. Event Triggering

These are related but different concepts:

• Event targeting uses a user's event history (has the event occurred? how many times?) as a condition for showing content. It evaluates on page load.
• Event triggering shows a Flow immediately at the moment the event fires, without waiting for a page load. This is useful for single-page applications or highly responsive in-app experiences.

Both can be combined with other targeting conditions like page URL and audience rules.

Quick Reference

Common Pitfalls

Property values look right but targeting doesn't work Check the user's profile in Studio. The most common cause is a type mismatch — a number sent as a string, or a date in an unsupported format. You can also check and update the expected data type for any property in Settings > Data > Properties.

Date property isn't recognized as a date Confirm you're using one of the three supported formats. Dates like 06/20/2025 or 20-Jan-2025 are treated as plain strings. If you're sending UNIX timestamps, make sure they're in seconds, not milliseconds. Set the property's data type to "Date" in Settings > Data > Properties for correct report formatting.

Events not appearing in Studio Events appear in the Events and Properties page only after they've been triggered at least once by a real user (or in test mode). It can take up to 30 minutes for a new event to become visible.

Properties from an integration aren't showing up If you're sending data through Segment, RudderStack, or another integration, confirm the Appcues destination is connected and that the source sending the data is active. Also confirm that objects and arrays are being flattened — some integrations handle this automatically, others don't.