Smithery is now a part of Arcade.dev! Read more in our announcement here
Core concepts for Fullstory's Analytics Events API (trackEvent). Platform-agnostic guide covering event naming, property types, rate limits, and best practices...
Implementation Files: This document covers core concepts. For code examples, see:
- SKILL-WEB.md — JavaScript/TypeScript (Browser)
- SKILL-MOBILE.md — iOS, Android, Flutter, React Native
Fullstory's Analytics Events API allows developers to send custom event data that captures meaningful user actions and business moments. Unlike automatic capture which records all interactions, trackEvent lets you define semantically meaningful events with rich context that can be used for:
Analytics events are especially valuable for capturing data that isn't visible in the DOM or native view hierarchy:
This makes trackEvent the bridge between your application's internal state and Fullstory's observability.
| API | Purpose | Data Type | Example |
|---|---|---|---|
trackEvent |
Discrete actions/moments | "What happened" | "Order Completed", "Feature Used" |
setProperties (user) |
User attributes | "Who they are" | plan: "enterprise" |
setProperties (page) |
Page context | "Where they are" | pageName: "Checkout" |
| Element Properties | Interaction context | "What they clicked" | productId: "SKU-123" |
Key principle: Events capture moments in time. Page properties capture state that persists across interactions.
✅ Use trackEvent for:
❌ Don't use trackEvent for:
| Scenario | Use Event | Use Page Property |
|---|---|---|
| API call failed at 2:03pm | ✅ API Error Occurred |
❌ |
| User is viewing product SKU-123 | ❌ | ✅ productId: "SKU-123" |
| Component took 850ms to render | ✅ Slow Render Detected |
❌ |
| User has 3 items in cart | ❌ | ✅ cartItemCount: 3 |
| User completed checkout | ✅ Order Completed |
❌ |
| User is on the checkout flow | ❌ | ✅ flowName: "checkout" |
Rule of thumb: If the data remains true while the user interacts with the page, it's a page property. If it's something that happened, it's an event.
Fullstory recommends semantic event naming following industry standards:
[Object] [Action]
Examples:
- "Product Added"
- "Order Completed"
- "Feature Enabled"
- "Search Performed"
- "Video Played"
- "Subscription Started"
- "Trial Converted"
| Rule | Good | Bad |
|---|---|---|
| Use Object + Action | "Product Added" | "click" |
| Be specific | "Checkout Started" | "action" |
| Use past tense for actions | "Order Completed" | "Order Complete" |
| Keep under 250 chars | "CTA Clicked" | "User clicked on the primary..." |
| Avoid redundancy | "Feature Used" | "Feature Feature Used" |
E-commerce:
SaaS:
Engagement:
Technical/System (non-DOM data):
Every event can include rich contextual properties that enable deep analysis.
| Rule | Good | Bad |
|---|---|---|
| Use snake_case | product_id |
productId, ProductID |
| Be descriptive | shipping_method |
sm |
| Include units | duration_ms |
duration |
| Avoid PII | user_segment |
email |
| Type | Description | Examples |
|---|---|---|
str |
String value | "blue", "premium" |
strs |
Array of strings | ["red", "blue", "green"] |
int |
Integer | 42, -5, 0 |
ints |
Array of integers | [1, 2, 3] |
real |
Float/decimal | 99.99, -3.14 |
reals |
Array of reals | [10.5, 20.0] |
bool |
Boolean | true, false |
bools |
Array of booleans | [true, false] |
date |
ISO8601 date | "2024-01-15T00:00:00Z" |
dates |
Array of dates | ["2024-01-01", "2024-02-01"] |
Fullstory auto-infers types, but explicit schemas ensure accuracy:
| Value | Auto-Inferred | With Schema |
|---|---|---|
"42" |
str |
Can force to int |
42 |
int |
Confirmed int |
42.0 |
real |
Confirmed real |
"2024-01-15" |
str |
Can force to date |
| Limit | Value |
|---|---|
| Event name | Max 250 characters |
| Properties payload | Max 512KB |
| Property name | Max 256 characters |
| Type | Limit |
|---|---|
| Sustained | 60 calls per user per page per minute |
| Burst | 40 calls per second |
| Array Type | Indexed? | Notes |
|---|---|---|
Strings (strs) |
✅ Yes | Searchable |
Integers (ints) |
✅ Yes | Searchable |
Reals (reals) |
✅ Yes | Searchable |
Booleans (bools) |
✅ Yes | Searchable |
Dates (dates) |
✅ Yes | Searchable |
| Objects | ❌ No | NOT indexed (except Order Completed products) |
Before implementing an event, answer:
For events that might fire multiple times (form submissions, button clicks):
Strategy: Track a unique key (e.g., order_id) and skip if seen recently
For events with duration (video watched, form completed):
Strategy: Track start time, calculate duration on completion
Include: duration_ms, completed (bool), cancel_reason (if abandoned)
| Symptom | Cause | Solution |
|---|---|---|
| No events in Fullstory | SDK not loaded | Verify SDK initialization |
| Events truncated | Name > 250 chars | Shorten event name |
| Events dropped | Rate limit exceeded | Throttle high-frequency events |
| Events missing | Properties > 512KB | Reduce payload size |
| Symptom | Cause | Solution |
|---|---|---|
| Can't search by property | Wrong type | Use explicit schema |
| Property shows as string | Number in quotes | Pass actual number |
| Date not queryable | Wrong format | Use ISO8601 format |
| Array not searchable | Array of objects | Flatten to primitive arrays |
| Wrong | Right | Issue |
|---|---|---|
"$99.99" |
99.99 |
Currency symbol in number |
"3 items" |
3 |
Text in number |
"yes" |
true |
String instead of boolean |
"today" |
"2024-01-15T00:00:00Z" |
Not ISO8601 |
Event where name = "Order Completed"
Event where name = "Order Completed" and revenue > 100
Event where name = "Feature Used" and feature_name = "advanced_export"
Event where name = "Order Completed" and user.plan = "enterprise"
Event where name = "Checkout Abandoned" and abandoned_at_step = 2
When helping developers implement Analytics Events:
Always emphasize:
Common mistakes to watch for:
Questions to ask developers:
Platform routing:
