Install the widget

One async script. Shadow DOM isolation. Config fetched from the Worker. UI loads only when the visitor opens the launcher.

Script tag (recommended)

production · html

<script
  async
  src="https://cdn.openroadmap.app/widget.js"
  data-project="pk_YOUR_PUBLIC_KEY"
  data-api="https://api.openroadmap.app"
></script>

Attribute	Required	Description
`data-project`	Yes	Project public key (`pk_…`)
`data-api`	No*	API origin. Defaults to the script host when omitted.

Warning

*If you serve widget.js from a different origin than the API, always set data-api (or window.__OPENROADMAP_API_BASE__).

Globals (optional)

before widget.js · html

<script>
  window.__OPENROADMAP_API_BASE__ = "https://api.openroadmap.app";
  window.__OPENROADMAP_UI_URL__ = "https://cdn.openroadmap.app/widget-ui.js";
  window.FeedbackWidgetKey = "pk_YOUR_PUBLIC_KEY";
</script>
<script async src="https://cdn.openroadmap.app/widget.js"></script>

SPA / React / Next

Load the script once at the app root (layout or _document). Do not mount multiple copies. After navigation, call Feedback.identify again if the user session changed.

app/layout.tsx (pattern) · tsx

import Script from "next/script";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://cdn.openroadmap.app/widget.js"
          data-project={process.env.NEXT_PUBLIC_OPENROADMAP_KEY}
          data-api={process.env.NEXT_PUBLIC_OPENROADMAP_API}
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

CSP

Allow your CDN + API origins:

script-src — CDN host for widget.js / widget-ui.js
connect-src — API host for /v1/*

Domain allowlist

Ingest rejects requests whose Origin/Referer host is not allowed for the project. Local demo allows common localhost ports. Add production hosts in project settings before go-live.