SDK Reference
Complete reference for the UserHero JavaScript SDK
SDK Reference
The UserHero SDK exposes a global UserHero object with methods to control the widget programmatically.
Global Object
After the SDK loads, window.UserHero provides these methods:
interface UserHero {
open(widgetId?: string): void;
close(): void;
setMetadata(data: object | null): boolean;
clearMetadata(): void;
getMetadata(): object | null;
captureScreenshot(widgetId?: string): Promise<void>;
}Methods
open(widgetId?)
Opens the feedback widget modal.
// Open the default widget
UserHero.open();
// Open a specific widget by ID
UserHero.open('widget_abc123');Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
widgetId | string | No | ID of the widget to open. If omitted, opens the first available widget. |
Use cases:
- Trigger feedback from a custom button
- Open feedback after a specific user action
- Integrate with help menus
close()
Closes the currently open widget modal.
UserHero.close();setMetadata(data)
Attach custom metadata to feedback submissions. This data is included with every feedback submitted from this session.
UserHero.setMetadata({
userId: 'user_123',
plan: 'pro',
company: 'Acme Inc',
role: 'admin',
});Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
data | object | null | Yes | Key-value pairs of metadata. Pass null to clear. |
Returns: boolean - true if set successfully, false if validation failed.
Constraints:
- Maximum payload size: 5KB when serialized to JSON
- Must be a plain object (not an array)
- Values can be strings, numbers, booleans, or nested objects
Example with user context:
// After user logs in
UserHero.setMetadata({
userId: currentUser.id,
email: currentUser.email,
plan: currentUser.subscription.plan,
signupDate: currentUser.createdAt,
features: {
beta: true,
darkMode: true,
},
});clearMetadata()
Remove all custom metadata.
// When user logs out
UserHero.clearMetadata();getMetadata()
Retrieve the currently set metadata.
const metadata = UserHero.getMetadata();
console.log(metadata);
// { userId: 'user_123', plan: 'pro', ... }Returns: object | null - The current metadata or null if not set.
captureScreenshot(widgetId?)
Programmatically trigger a screenshot capture.
await UserHero.captureScreenshot();Screenshot capture requires the widget to be open. Call open() first if needed.
Events
The SDK dispatches custom events you can listen for:
userhero:ready
Fired when the SDK is fully initialized.
window.addEventListener('userhero:ready', () => {
console.log('UserHero is ready');
// Safe to call UserHero methods now
});userhero:open
Fired when a widget opens.
window.addEventListener('userhero:open', (event) => {
console.log('Widget opened:', event.detail.widgetId);
});userhero:close
Fired when a widget closes.
window.addEventListener('userhero:close', () => {
console.log('Widget closed');
});userhero:submit
Fired when feedback is successfully submitted.
window.addEventListener('userhero:submit', (event) => {
console.log('Feedback submitted:', event.detail);
// Track in analytics
analytics.track('Feedback Submitted', {
category: event.detail.category,
});
});Complete Example
// Wait for SDK to load
window.addEventListener('userhero:ready', () => {
// Set user context
UserHero.setMetadata({
userId: currentUser.id,
plan: currentUser.plan,
});
});
// Custom feedback button
document.getElementById('feedback-btn').addEventListener('click', () => {
UserHero.open();
});
// Track submissions
window.addEventListener('userhero:submit', (event) => {
analytics.track('User Feedback', event.detail);
});
// Clear on logout
function onLogout() {
UserHero.clearMetadata();
}TypeScript
For TypeScript projects, you can add type declarations:
declare global {
interface Window {
UserHero?: {
open(widgetId?: string): void;
close(): void;
setMetadata(data: Record<string, unknown> | null): boolean;
clearMetadata(): void;
getMetadata(): Record<string, unknown> | null;
captureScreenshot(widgetId?: string): Promise<void>;
};
UserHeroLoaded?: boolean;
UserHeroConfig?: {
publicKey?: string;
apiBase?: string;
};
}
}