Getting Started
Installation
Detailed installation guide for the UserHero widget
Installation
The UserHero widget is loaded via a simple script tag. This guide covers all installation options and best practices.
Basic Installation
Add the following script to your website:
<script
async
src="https://userhero.co/widget.js"
data-key="pk_live_your_public_key">
</script>Attributes
| Attribute | Required | Description |
|---|---|---|
src | Yes | The widget script URL |
data-key | Yes | Your project's public key (starts with pk_live_ or pk_test_) |
async | Recommended | Load script asynchronously without blocking page render |
Finding Your Public Key
- Log in to your UserHero dashboard
- Select your project
- Go to Settings → Widget Code
- Copy your public key or the full embed code
Placement
Place the script tag just before the closing </body> tag for optimal performance:
<!DOCTYPE html>
<html>
<head>
<title>My Website</title>
</head>
<body>
<!-- Your website content -->
<!-- UserHero Widget - Load last for best performance -->
<script
async
src="https://userhero.co/widget.js"
data-key="pk_live_your_public_key">
</script>
</body>
</html>Advanced Configuration
You can configure the widget using a global config object before loading the script:
<script>
window.UserHeroConfig = {
// Custom API base (for self-hosted or proxy setups)
apiBase: 'https://userhero.co',
// Alternative to data-key attribute
publicKey: 'pk_live_your_public_key',
};
</script>
<script async src="https://userhero.co/widget.js"></script>Single Page Applications (SPA)
For SPAs like React, Vue, or Angular, the widget automatically handles route changes. However, you may want to control when the script loads.
React Example
import { useEffect } from 'react';
export function UserHeroWidget() {
useEffect(() => {
// Prevent double-loading
if (window.UserHeroLoaded) return;
const script = document.createElement('script');
script.src = 'https://userhero.co/widget.js';
script.async = true;
script.dataset.key = 'pk_live_your_public_key';
document.body.appendChild(script);
return () => {
// Cleanup if needed
};
}, []);
return null;
}Next.js App Router
// app/layout.tsx
import Script from 'next/script';
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html>
<body>
{children}
<Script
src="https://userhero.co/widget.js"
data-key="pk_live_your_public_key"
strategy="lazyOnload"
/>
</body>
</html>
);
}Next.js Pages Router
// pages/_app.tsx
import Script from 'next/script';
export default function App({ Component, pageProps }) {
return (
<>
<Component {...pageProps} />
<Script
src="https://userhero.co/widget.js"
data-key="pk_live_your_public_key"
strategy="lazyOnload"
/>
</>
);
}Content Security Policy (CSP)
If your site uses CSP, add these directives:
script-src 'self' https://userhero.co;
connect-src 'self' https://userhero.co;
style-src 'self' 'unsafe-inline';
img-src 'self' blob: data: https://userhero.co;Verifying Installation
After installing the widget:
- Open your browser's Developer Tools (F12)
- Go to the Network tab
- Filter by "userhero"
- Refresh your page
- You should see the widget.js script loading successfully
You can also check the console for any UserHero messages:
[UserHero] Widget initialized successfullyTroubleshooting
Widget not appearing? Check these common issues:
- Missing
data-key: Ensure the public key is set correctly - Targeting rules: Check that your current page matches the widget's targeting settings
- Plan limits: Verify your workspace hasn't exceeded its feedback limit
- Console errors: Look for any JavaScript errors in your browser console
- Ad blockers: Some ad blockers may block feedback widgets—test in incognito mode