OctoFeedback
Integration guide

Use OctoFeedback in your applications

Embed the same feedback widget in ContentKit, InterviewKit, Django, React, static sites or any other application. Captures go to the central D1 inbox; optional screenshots stay private in R2.

1. Register a project and an instance

Sign in to the admin inbox, create a project such as contentkit, then an instance such as production. Use the exact website origin, including https://, without path or trailing slash.

Project:  contentkit
Instance: production
Origin:   https://contentkit.example.org

A separate instance is recommended for each production/staging/development deployment. Instead of manual registration, your Ansible jobs can call the idempotent provisioning API.

2. Paste the widget into your site

Place this before </body>, adapting the project, instance and language:

<script
  src="https://feedback.example.org/widget/v1.js"
  data-project="contentkit"
  data-instance="production"
  data-locale="auto"
  data-label="Feedback"
  data-primary-color="#155e75"
  data-position="bottom-right"
  data-app-version="1.0.0"></script>

Embed the stable /widget/v1.js path: it only receives backward-compatible changes, and a breaking change ships as v2 so existing installs keep working. /widget.js remains an alias for older installs. Use the matching Worker URL for this environment. By default the widget follows the host page language (<html lang="de">, es or en), then the browser language. Explicit data-locale overrides its initial language. The visitor can also choose English, Deutsch or Español from the widget header without losing the draft.

3. Programmatic mounting (SPA, React, Vue)

<script src="https://feedback.example.org/widget/v1.js" defer></script>
<script>
  document.addEventListener("DOMContentLoaded", () => {
    const widget = window.OctoFeedback.mount({
      apiBase: "https://feedback.example.org",
      project: "interviewkit",
      instance: "staging",
      locale: "de",
      primaryColor: "#0e7490",
      position: "bottom-left",
      appVersion: "1.2.0"
    });
    // Call widget.destroy() when the SPA view unmounts.
  });
</script>

If your site has a strict Content Security Policy, allow the OctoFeedback Worker origin in script-src, connect-src and img-src (the widget icon is served from the Worker). Widget styles use constructable stylesheets, so 'unsafe-inline' is not required for the widget. If an instance uses a customer logo URL, also allow that image host in img-src. Screenshot capture renders a copy of the page and may omit content your CSP blocks. Never add wildcard exceptions. Load the script once per application view.

Screenshot editor

Capturing is voluntary. Users may draw, redact, undo, enlarge and zoom the image. The recipient never gets a direct public R2 URL. Review screenshots before sending: automatic privacy masking is best effort.

Security

Do not put ADMIN_TOKEN, MCP_TOKEN, provisioning tokens or signing keys in HTML or JavaScript. Public browser ingestion checks the registered origin, but it is not cryptographic authentication.

4. Verify the integration

  1. Open your registered website and click Feedback.
  2. Enter a non-sensitive test message and optionally annotate a screenshot.
  3. Submit and confirm the reference ID.
  4. Open the inbox and filter by project/instance.
  5. If you receive Instance not configured for origin, ensure the instance has exactly the host page's origin and is enabled.

Need signed ingestion or per-user verification? See the advanced widget guide and source security details.