Developer Documentation

Integrate BugBear's Hosted Feedback Form into any app with a single link – no SDK, no setup.

Contents

  1. Overview
  2. Quickstart
  3. URL Parameters
  4. Passing Categories
  5. Examples
  6. Page Behavior
  7. Direct API (Advanced)

1. Overview

BugBear provides a hosted feedback form that you can link to directly from your app. No SDK installation, no UI to build — just point your users to a URL with your API key and they can submit feedback in seconds.

This is ideal if you want to:

  • Add a "Send Feedback" button to your app without building custom UI
  • Collect structured feedback per category and app version
  • Redirect users back to your app after submission
💡 The hosted form is public — no login required for your users. All feedback is associated with your product via the apiKey parameter.

2. Quickstart

Add a button to your app that opens the BugBear feedback form:

HTML Button

<!-- Simple feedback button --> <a href="https://bug-bear.com/FeedbackForm?apiKey=YOUR_API_KEY&categories=GUID:Bug Report" target="_blank" rel="noopener"> Send Feedback </a>

Flutter / Dart

final url = Uri.parse( 'https://bug-bear.com/FeedbackForm' '?apiKey=YOUR_API_KEY' '&categories=GUID1:Bug Report,GUID2:Feature Request' '&version=1.2.0' '&returnUrl=https://yourapp.com/thank-you', ); await launchUrl(url, mode: LaunchMode.externalApplication);

.NET / C#

var url = $"https://bug-bear.com/FeedbackForm" + $"?apiKey={apiKey}" + $"&categories={categoryId}:Bug Report" + $"&version={appVersion}" + $"&returnUrl={Uri.EscapeDataString(returnUrl)}"; Process.Start(new ProcessStartInfo(url) { UseShellExecute = true });
↗ Preview the Form

3. URL Parameters

The feedback form URL is https://bug-bear.com/FeedbackForm and accepts the following query parameters:

Parameter Required Description
apiKey Required Your product's API key from the BugBear dashboard (e.g. bb_xxxx).
categories Optional Comma-separated list of categoryId:Name pairs. If omitted, the form shows a free-text field only. See Passing Categories below.
version Optional Display version string, e.g. 1.2.3. Shown as a badge on the form and included in the feedback metadata. Defaults to 1.0 if omitted.
productVersionId Optional GUID of a specific product version from the BugBear dashboard. Associates the feedback with that version. If omitted, the product's default version is used.
returnUrl Optional URL to redirect the user to after successful submission. Should be URL-encoded. If omitted, a confirmation message is shown instead.

4. Passing Categories

The categories parameter controls which category options the user sees. The format is a comma-separated list of categoryId:Display Name pairs. You find your category GUIDs in the BugBear dashboard under your product settings.

Single category (preselected, no dropdown)

https://bug-bear.com/FeedbackForm?apiKey=bb_xxx&categories=8ed26c57-9124-4942-938b-41aa90474fa1:Bug Report

When only one category is provided, it is shown as a fixed badge — the user cannot change it. This is useful for a dedicated "Report a Bug" button.

Multiple categories (dropdown)

https://bug-bear.com/FeedbackForm?apiKey=bb_xxx&categories=8ed26c57-9124-4942-938b-41aa90474fa1:Bug Report,2e30b5a6-fe4c-49e4-aab4-b4c9630886db:Feature Request,31082f50-8b60-49f5-904a-e90bbf1df656:Other

When multiple categories are provided, the user can choose from a dropdown.

✅ Tip: URL-encode the : and , characters when building the URL programmatically (they become %3A and %2C). Most HTTP libraries handle this automatically via query string builders.

5. Examples

Minimal – just an API key

https://bug-bear.com/FeedbackForm?apiKey=bb_91198227025241209148269dadaf78d5

Bug Report button with version

https://bug-bear.com/FeedbackForm?apiKey=bb_xxx&categories=8ed26c57-9124-4942-938b-41aa90474fa1:Bug%20Report&version=2.1.0

Full example with productVersionId and returnUrl

https://bug-bear.com/FeedbackForm ?apiKey=bb_xxx &categories=8ed26c57-9124-4942-938b-41aa90474fa1:Bug Report,2e30b5a6-fe4c-49e4-aab4-b4c9630886db:Feature Request &version=2.1.0 &productVersionId=c15e3f2b-0786-4908-b453-f1ecd94db8d4 &returnUrl=https%3A%2F%2Fyourapp.com%2Fthank-you

Kotlin / Android

val uri = Uri.parse("https://bug-bear.com/FeedbackForm").buildUpon() .appendQueryParameter("apiKey", apiKey) .appendQueryParameter("categories", "$categoryId:Bug Report") .appendQueryParameter("version", BuildConfig.VERSION_NAME) .build() startActivity(Intent(Intent.ACTION_VIEW, uri))

Swift / iOS

var components = URLComponents(string: "https://bug-bear.com/FeedbackForm")! components.queryItems = [ URLQueryItem(name: "apiKey", value: apiKey), URLQueryItem(name: "categories", value: "\(categoryId):Bug Report"), URLQueryItem(name: "version", value: Bundle.main.shortVersion), ] UIApplication.shared.open(components.url!)

6. Page Behavior

  • No login required — the page is fully public.
  • Single category → displayed as a badge, not editable by the user.
  • Multiple categories → shown as a dropdown for the user to choose.
  • Version → shown as a small badge on the form; included in feedback metadata.
  • After submission with returnUrl → user is redirected after 2 seconds.
  • After submission without returnUrl → a success message is shown.
  • Invalid apiKey → the API returns an error which is shown on the form.
  • Theme → respects the user's system dark/light mode preference automatically.

7. Direct API (Advanced)

If you want to build your own feedback UI, you can submit feedback directly to the BugBear REST API without using the hosted form.

Endpoint

POST https://api.bug-bear.com/api/feedback Content-Type: application/json

Request Body

{ "productApiKey": "bb_xxx", // required "categoryId": "8ed26c57-...", // required – GUID "description": "The login button crashes.",// required, 10–5000 chars "submitterEmail": "user@example.com", // optional "productVersionId": "c15e3f2b-...", // optional – GUID "metadata": "{\"version\":\"1.0\"}" // optional – free JSON string }

Response

// HTTP 201 Created { "feedbackId": "a1b2c3d4-...", "message": "Feedback submitted successfully" }
📘 No authentication header is required. The productApiKey in the request body identifies your product.