Custom Metadata
Attach user context and custom data to feedback
Custom Metadata
Attach custom data to feedback submissions to add context about the user, their session, or your application state.
Why Use Metadata?
When a user submits feedback, you often want to know:
- Who is this user? (user ID, email, name)
- What plan are they on? (free, pro, enterprise)
- What were they doing? (feature being used, experiment variant)
- What's their environment? (account ID, team, role)
Custom metadata lets you include this context automatically with every feedback submission.
Setting Metadata
Use setMetadata() to attach custom data:
UserHero.setMetadata({
userId: 'user_123',
email: 'user@example.com',
plan: 'pro',
company: 'Acme Inc',
});This data will be included with all subsequent feedback submissions until you clear it or set new data.
Common Use Cases
After User Login
async function onUserLogin(user) {
// Set metadata when user logs in
UserHero.setMetadata({
userId: user.id,
email: user.email,
name: user.displayName,
plan: user.subscription?.plan || 'free',
role: user.role,
});
}With Application Context
// Include current app state
UserHero.setMetadata({
userId: user.id,
currentPage: 'dashboard',
activeFeature: 'reports',
experimentGroup: abTest.getVariant('new-ui'),
locale: i18n.locale,
});With Team/Organization Info
UserHero.setMetadata({
userId: user.id,
organizationId: org.id,
organizationName: org.name,
teamId: team.id,
userRole: membership.role,
});Updating Metadata
Each call to setMetadata() replaces the previous metadata entirely:
// Initial metadata
UserHero.setMetadata({ userId: '123', plan: 'free' });
// Later, upgrade happens
UserHero.setMetadata({ userId: '123', plan: 'pro' });
// Now metadata is { userId: '123', plan: 'pro' }
// The 'plan' is updated, but you must include all fieldsTo merge metadata, get and spread the existing values:
// Merge new data with existing
const current = UserHero.getMetadata() || {};
UserHero.setMetadata({
...current,
newField: 'newValue',
});Clearing Metadata
Clear metadata when the user logs out:
function onLogout() {
UserHero.clearMetadata();
}Or set to null:
UserHero.setMetadata(null);Getting Current Metadata
Retrieve the currently set metadata:
const metadata = UserHero.getMetadata();
if (metadata) {
console.log('Current user:', metadata.userId);
} else {
console.log('No metadata set');
}Constraints
| Constraint | Limit |
|---|---|
| Maximum size | 5KB (serialized JSON) |
| Data type | Plain object only |
| Nested objects | Supported |
| Arrays | Supported |
Validation:
// This will fail and return false
const success = UserHero.setMetadata('not an object');
// success === false
// This will log a warning
UserHero.setMetadata({ hugeData: '...'.repeat(10000) });
// "[UserHero] Custom metadata exceeds 5KB limit. Data not set."Sensitive Data
Privacy consideration: Only include data you're comfortable appearing in your feedback dashboard. Avoid passwords, tokens, or highly sensitive PII.
Recommended:
- User ID
- Email (if user consented)
- Plan/subscription tier
- Organization ID
- Feature flags
- Experiment variants
Avoid:
- Passwords or secrets
- Credit card numbers
- Social Security Numbers
- Full addresses
- Sensitive health data
Viewing Metadata
Metadata appears in the feedback detail view in your dashboard as a key-value table. Nested objects are shown as formatted JSON.
Feature Availability
| Plan | Custom Metadata |
|---|---|
| Free | ✅ Available |
| Starter | ✅ Available |
| Growth | ✅ Available |
| Pro | ✅ Available |