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',
name: 'Jane Smith',
plan: 'pro',
company: 'Acme Inc',
});This data is included with all subsequent feedback submissions until you clear it or set new data.
User Identification
How User Info Promotion Works
When you include recognized keys in setMetadata(), UserHero automatically promotes those values to the feedback item's user info. Promoted values appear in the Context card in your dashboard, making it easy to see who submitted the feedback at a glance.
| Field | Recognized Keys |
|---|---|
| Name | name, userName, user_name, fullName, full_name, displayName, customer, customerName, customer_name |
email, userEmail, user_email | |
| Phone | phone, userPhone, user_phone, phoneNumber, phone_number |
// These keys are automatically promoted to user info
UserHero.setMetadata({
name: 'Jane Smith', // → appears as user name in Context card
email: 'jane@acme.com', // → appears as user email in Context card
phone: '+1-555-0100', // → appears as user phone in Context card
plan: 'pro', // → stays in Custom Data only
company: 'Acme Inc', // → stays in Custom Data only
});Any keys that are not in the recognized list are stored as-is and appear in the Custom Data card.
userId
The userId key is not promoted to the user info fields. Instead, it serves as the primary identifier for linking feedback to a customer profile. Pass it so your team can correlate feedback with your internal user records:
UserHero.setMetadata({
userId: 'usr_8f2k9d', // links feedback to customer profile
name: 'Jane Smith',
email: 'jane@acme.com',
});userId appears in the Custom Data card and is used internally for grouping feedback by customer. It is not displayed as the user's name or email.
Custom Metadata vs Custom Fields
UserHero has two ways to collect structured data with feedback. They serve different purposes:
| Custom Metadata | Custom Fields | |
|---|---|---|
| Set by | Developer, via setMetadata() | End user, via the widget form |
| When | Before the widget opens (e.g. on login) | When the user fills out the feedback form |
| Visible to user | No | Yes (form inputs) |
| Use case | App context, user identity, internal IDs | Collecting name, email, phone, or custom input from the user |
| Dashboard location | Custom Data card | Custom Fields card |
Priority rule: If both custom metadata and a custom field provide the same user info (e.g. both set an email), the custom field value wins. This means if a user types their email into a form field, it overrides whatever was set via setMetadata().
// Developer sets metadata before widget opens
UserHero.setMetadata({ email: 'dev-known@acme.com' });
// If the widget has a df_email field and the user types "actual@acme.com",
// the feedback's userEmail will be "actual@acme.com" (custom field wins)See Widget Fields for details on configuring custom fields in your widget.
Common Use Cases
After User Login
async function onUserLogin(user) {
UserHero.setMetadata({
userId: user.id,
email: user.email,
name: user.displayName,
plan: user.subscription?.plan || 'free',
role: user.role,
});
}With Application Context
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
Where Metadata Appears
In the feedback detail view:
- Context card — Promoted user info (name, email, phone) alongside automatic context like browser, OS, and location
- Custom Data card — All metadata key-value pairs, including
userId,plan, and any other custom keys. Nested objects are shown as formatted JSON.
Feature Availability
| Plan | Custom Metadata |
|---|---|
| Free | ✅ Available |
| Starter | ✅ Available |
| Growth | ✅ Available |
| Pro | ✅ Available |