Core concepts for Fullstory's Element Properties API. Platform-agnostic guide covering API Defined Elements, property inheritance, schema types, and best practices. See SKILL-WEB.md and SKILL-MOBILE.md for implementation examples.
Implementation Files: This document covers core concepts. For code examples, see:
- SKILL-WEB.md — JavaScript/TypeScript (Browser)
- SKILL-IOS.md — iOS (Swift/SwiftUI)
- SKILL-ANDROID.md — Android (Kotlin/Java)
- SKILL-REACT-NATIVE.md — React Native
- SKILL-FLUTTER.md — Flutter (Dart)
Fullstory's Element Properties API allows developers to capture custom properties on UI elements that can be used for search, filtering, grouping, and analytics. Unlike standard attributes which are only used for CSS selectors, element properties become first-class data points for analysis, similar to user properties, page properties, and event properties.
Key capabilities:
data-fs-element attribute (web) or FS.setAttribute (mobile)| Type | Purpose | Searchable | Example |
|------|---------|------------|---------|
| Attributes | CSS selectors, element matching | ❌ No | class="btn-primary" |
| Element Properties | Filtering, grouping, analytics | ✅ Yes | productId: "SKU-123" |
✅ Good use cases:
❌ Avoid for:
This is one of the most powerful features of Element Properties:
Two-way inheritance:
┌─────────────────────────────────────────────────────────────────────┐
│ FORM (element="checkout-form") │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ SHIPPING SELECT (selectedShipping="express") │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ PAYMENT SELECT (selectedPayment="credit_card") │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ GIFT WRAP CHECKBOX (giftWrap="true") │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ SUBMIT BUTTON (element="submit-order") │ │
│ │ ─────────────────────────────────────────────────────── │ │
│ │ When clicked, captures ALL properties from siblings: │ │
│ │ • selectedShipping: "express" │ │
│ │ • selectedPayment: "credit_card" │ │
│ │ • giftWrap: true │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Why this matters for analytics:
Key Insight: Define element properties on individual form fields, and the submit button will automatically capture the full form state. This eliminates the need to manually aggregate form data.
| Type | Description | Examples |
|------|-------------|----------|
| str | String value | "foo", "bar", "foo@bar" |
| strs | Array of strings | ["foo", "bar"] |
| int | Integer | 0, -123, 45 |
| ints | Array of integers | [0, 1, 2] |
| real | Float/decimal | 12.345, -0.5 |
| reals | Array of reals | [12.345, 1] |
| bool | Boolean | true, false, 1, 0, t, f |
| bools | Array of booleans | [true, false] |
| date | ISO8601 date/datetime | "2006-01-02T15:04:05Z" |
| dates | Array of dates | ["2006-01-02", "2006-01-02T15:04:05Z"] |
| Type | Correct | Incorrect |
|------|---------|-----------|
| real | 199.99 | "$199.99" (no currency symbols) |
| int | 5 | "5 items" (no units/text) |
| bool | true or "true" | "yes", "Yes", "Y" |
| date | "2024-01-15T00:00:00Z" | "today", "Jan 15" |
| Limit | Value | |-------|-------| | Active API Defined Elements | Max 1,000 (archived don't count) | | Properties per single interaction | Max 50 unique | | Properties across all interactions | Max 500 unique |
Container (e.g., product card)
├── Properties: productId, productName, price, category
└── Button (e.g., "Add to Cart")
└── Inherits all container properties
└── Button interaction captures full product context
Form Container
├── Properties: formType, formStep, userTier
├── Field 1
│ ├── Inherits form properties
│ └── Own properties: fieldName, isRequired, fieldType
├── Field 2
│ └── Same pattern
└── Submit Button
└── Inherits form properties + captures all field properties
List Container
├── Properties: listType, totalItems, filterApplied
└── List Item (repeated)
├── Inherits list properties
└── Own properties: itemId, itemName, position
For all platforms, follow this order:
data-fs-element or equivalent)Setting the schema before values may cause timing issues with property capture.
| Do | Don't |
|----|-------|
| Use clean numeric values | Include currency symbols ($, €) |
| Use boolean true/false | Use "yes"/"no" strings |
| Use ISO8601 for dates | Use human-readable dates |
| Use name override for readability | Use raw attribute names |
| Focus on business-relevant data | Capture debug/technical data |
prepareForReuse() (iOS), onBindViewHolder (Android)| Symptom | Common Causes | Solutions | |---------|---------------|-----------| | No properties captured | Schema set before values | Always set values before schema | | No properties captured | Invalid JSON in schema | Use proper JSON builders, not manual strings | | No properties captured | Attribute doesn't exist | Verify all schema attributes exist | | No properties captured | Hit property limits | Check 50/500 limits |
| Symptom | Common Causes | Solutions |
|---------|---------------|-----------|
| Stale data | View/cell reuse not handled | Implement prepareForReuse or clear in bind |
| Old attributes remain | Attributes not cleared | Track and clear previous attributes |
| Wrong timing | Attributes set at wrong lifecycle point | Set in appropriate lifecycle methods |
| Symptom | Common Causes | Solutions | |---------|---------------|-----------| | Numbers show as strings | Values contain non-numeric chars | Strip formatting before setting | | Booleans show as strings | Using "yes"/"no" | Use "true"/"false" strings | | Dates not queryable | Wrong format | Use ISO8601 format |
name overridedata-fs-element (web) or equivalent (mobile)When helping developers implement Element Properties:
Always emphasize:
name overrideCommon mistakes to watch for:
Questions to ask developers:
Platform routing:
npx skills add fullstorydev/fullstory-element-properties下载完整 Skill 目录，包含 SKILL.md 及所有相关文件
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer