Embed Feedback Widgets

Add Feedbackfirst to your website with two buttons: a feedback/testimonial button and a survey button. Setup is simple — just 2 lines of HTML, no build step, no npm install.

Why Embed?

If you already have an audience, embed the feedback widget directly on your site. Your users respond in context — no extra sign-up, zero friction. All responses land in your Feedbackfirst workspace where you can validate them and convert them into feature requests.

Benefits:

Zero friction — Users give feedback without leaving your site
SSO support — Your users are automatically recognized
All responses in one place — Feedback from your site and from the Feedbackfirst community in one workspace
No build step — Just drop the code into your HTML

Step 1: Add the Feedback Button

This button centralizes general feedback and testimonials in one flow.

Basic Setup

<!-- 1) Include widget.js once -->
<script src="https://feedbackfirst.dev/widget.js" defer></script>

<!-- 2) Add this button where you want -->
<ff-feedback-button
  maker-id="your-maker-id"
  sso-token-url="/api/feedbackfirst/sso-token"
  label="Leave feedback"
></ff-feedback-button>

Attributes

Attribute	Required	Description
`maker-id`	Yes	Your product ID on Feedbackfirst. Find it on your product page.
`sso-token-url`	Yes	Endpoint on your server that returns an SSO token. See SSO Integration for details.
`label`	No	Button text. Default: "Leave feedback"

Example: Custom Button Text

<ff-feedback-button
  maker-id="feedbackfirst"
  sso-token-url="/api/feedbackfirst/sso-token"
  label="Share your thoughts"
></ff-feedback-button>

Step 2: Add the Survey Button

Use surveys for NPS, satisfaction, onboarding, or post-project questions.

Basic Setup

<!-- widget.js is shared -->
<script src="https://feedbackfirst.dev/widget.js" defer></script>

<ff-survey-button
  survey-id="123"
  sso-token-url="/api/feedbackfirst/sso-token"
  label="Take survey"
></ff-survey-button>

Attributes

Attribute	Required	Description
`survey-id`	Yes	The ID of your survey. Create surveys in your Feedbackfirst workspace.
`sso-token-url`	Yes	Endpoint on your server that returns an SSO token.
`label`	No	Button text. Default: "Take survey"

Example: NPS Survey

<ff-survey-button
  survey-id="nps-2024"
  sso-token-url="/api/feedbackfirst/sso-token"
  label="How likely are you to recommend us?"
></ff-survey-button>

Creating Surveys

Surveys are created in your Feedbackfirst workspace:

Go to your product page
Click "Create Survey"
Add your questions
Set the credit reward per validated response
Copy the survey ID
Embed the button on your site

When users respond, they earn the credits you specified. You validate responses in your workspace.

SSO Integration

SSO (Single Sign-On) automatically recognizes your logged-in users so they don't have to sign up again on Feedbackfirst.

How It Works

User clicks the feedback button on your site
Your site calls /api/feedbackfirst/sso-token to get a token
The token is passed to the widget
The user is logged into Feedbackfirst automatically
They leave feedback without extra sign-up

Implementing SSO

You need to create an endpoint on your server that returns a JWT token signed with your Feedbackfirst API key.

Endpoint: POST /api/feedbackfirst/sso-token

Request body:

{
  "user_id": "user-123",
  "email": "user@example.com",
  "name": "John Doe"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

See SSO Integration for full implementation details.

Styling

The feedback button inherits styles from your site. You can customize it with CSS:

ff-feedback-button {
  --button-color: #4F46E5;
  --button-text-color: #ffffff;
  --button-border-radius: 8px;
  --button-padding: 12px 24px;
}

Placement Ideas

Help Page

<h1>Help & Feedback</h1>
<p>We'd love to hear from you.</p>
<ff-feedback-button
  maker-id="feedbackfirst"
  sso-token-url="/api/feedbackfirst/sso-token"
  label="Send feedback"
></ff-feedback-button>

Settings Page

<h2>Feedback</h2>
<p>Help us improve by sharing your thoughts.</p>
<ff-feedback-button
  maker-id="feedbackfirst"
  sso-token-url="/api/feedbackfirst/sso-token"
  label="Share feedback"
></ff-feedback-button>

Exit Intent

<div id="exit-popup">
  <h3>Before you go...</h3>
  <p>Quick feedback helps us improve.</p>
  <ff-feedback-button
    maker-id="feedbackfirst"
    sso-token-url="/api/feedbackfirst/sso-token"
    label="Leave feedback"
  ></ff-feedback-button>
</div>

Post-Onboarding

<div class="onboarding-complete">
  <h2>You're all set!</h2>
  <p>How was your onboarding experience?</p>
  <ff-survey-button
    survey-id="onboarding-feedback"
    sso-token-url="/api/feedbackfirst/sso-token"
    label="Rate your experience"
  ></ff-survey-button>
</div>

Troubleshooting

Button doesn't appear

Make sure widget.js is loaded before the button element
Check that maker-id is correct
Check browser console for errors

SSO not working

Verify your sso-token-url endpoint is returning a valid token
Check that the endpoint is accessible from the browser
See SSO Integration for debugging

Responses not appearing in workspace

Make sure you're using the correct maker-id
Check that responses are being submitted (check browser network tab)
Responses may take a few seconds to appear

Best Practices

Placement

Place the button where users naturally think about feedback (help page, settings, etc.)
Don't spam users with feedback requests
Consider exit-intent or post-action timing

Messaging

Use clear, friendly button text
Explain why you want feedback
Make it easy to find

Surveys

Keep surveys short (3-5 questions)
Ask specific questions
Set reasonable credit rewards

Advanced: Custom Styling

You can customize the button appearance with CSS variables:

ff-feedback-button {
  --primary-color: #4F46E5;
  --text-color: #ffffff;
  --border-radius: 8px;
  --padding: 12px 24px;
  --font-size: 14px;
  --font-weight: 600;
}

Advanced: Event Listeners

Listen to widget events:

document.addEventListener('feedbackfirst:submitted', (event) => {
  console.log('Feedback submitted:', event.detail);
  // Track in analytics, show thank you message, etc.
});

document.addEventListener('feedbackfirst:closed', (event) => {
  console.log('Widget closed');
});