Your customers don't report bugs. They report feelings.

Three options, and the third is a call into the endpoint you built. Launcher shape, which tabs exist, theme, which URLs it appears on — none of that is here, because none of it is yours to redeploy for.

<!-- the entire client-side integration -->
<script type="module">
  import { boot } from "https://cdn.beacon.example/widget/v1/loader.js";

  boot({
    baseUrl:   "https://support.example.com/api/v1/widget",
    projectId: "prj_4f9c2a…",
    // your backend vouches; this page never sees the signing secret
    getAssertion: async () => {
      const r = await fetch("/portal/support-identity", { method: "POST" });
      return (await r.json()).assertion;
    },
  });
</script>

The URL is versioned and ours. You do not vendor a copy into your web root — a copy is a thing that gets left behind.

The one most integrations actually want. beacon:unread fires whenever the count changes — including while the panel has never been opened, because the widget polls from the moment it boots. Your customer sees the reply in your own navigation, where they already look.

<span id="nav-support-badge" hidden></span>

<script type="module">
  import { boot } from "https://cdn.beacon.example/widget/v1/loader.js";
  const supportOptions = { /* baseUrl, projectId, getAssertion — see Minimal */ };

  const badge = document.querySelector("#nav-support-badge");

  // Our events bubble and are composed, so `document` is a fine place to
  // listen — and listening before boot() means you cannot miss a count.
  document.addEventListener("beacon:unread", (event) => {
    const n = event.detail.unread;
    badge.textContent = n ? String(n) : "";
    badge.hidden = !n;
  });

  boot(supportOptions);
</script>

Only { unread } is in the detail. The count, and nothing about the tickets behind it.

Switch our launcher off in the project settings — launcher_mode: hidden, a server-side setting, not an option on this page — and open the widget from a control that looks like the rest of your product.

boot() resolves to the control surface, or to null when the project is inactive or a URL rule excludes this page. So you can decide whether your button should exist at all.

<button id="contact-support" type="button" hidden>Contact support</button>

<script type="module">
  import { boot } from "https://cdn.beacon.example/widget/v1/loader.js";
  const supportOptions = { /* baseUrl, projectId, getAssertion — see Minimal */ };

  const button = document.querySelector("#contact-support");
  const beacon = await boot(supportOptions);

  if (beacon) {
    button.hidden = false;
    button.setAttribute("aria-expanded", "false");
    button.addEventListener("click", () => beacon.openNewRequest());

    // Reflect our state in your own chrome. beacon.isOpen() answers the
    // same question on demand, if you would rather ask than listen.
    beacon.on("open",  () => button.setAttribute("aria-expanded", "true"));
    beacon.on("close", () => button.setAttribute("aria-expanded", "false"));
  }
</script>

The same object is published as window.Beacon, for a button rendered somewhere your bootstrap cannot reach. Pass expose: false and nothing is published; pass a name and it is yours. We never overwrite one you are already using.

Boot once, from the shell that outlives your routes — an effect with an empty dependency list, onMounted, whatever your framework calls it. Booting from a route component gives you one widget per navigation and a global that gets clobbered.

// support.js — imported by your app shell, never by a route component.
import { boot } from "https://cdn.beacon.example/widget/v1/loader.js";

const supportOptions = { /* baseUrl, projectId, getAssertion — see Minimal */ };
let widget = null;

export async function mountSupport() {
  if (widget) return widget;        // once, not once per route
  widget = await boot(supportOptions);
  return widget;
}

export function unmountSupport() {
  // Removes our element, detaches every handler registered through
  // on() or hooks:, and releases the window.Beacon name.
  widget?.destroy();
  widget = null;
}

Every beacon:* event through one handler. The payloads are allowlisted projections, not the internal record — there is no priority, no assignee and no SLA field in any of them, so what you forward is bounded by what your customer could already see.

<script type="module">
  import { boot } from "https://cdn.beacon.example/widget/v1/loader.js";
  const supportOptions = { /* baseUrl, projectId, getAssertion — see Minimal */ };

  const beacon = await boot(supportOptions);
  if (beacon) {
    const E = beacon.events;   // the published vocabulary; don't hard-code

    const detach = [
      beacon.on(E.OPEN,  () => analytics.track("support_opened")),
      beacon.on(E.CLOSE, () => analytics.track("support_closed")),
      beacon.on(E.VIEW,  ({ view }) => analytics.track("support_view", { view })),

      // A title is your customer's own prose. Forward the identifiers.
      beacon.on(E.TICKET_CREATED, ({ id, issue_type }) =>
        analytics.track("support_ticket_created", { id, issue_type })),

      beacon.on(E.MESSAGE_SENT, ({ ticket_id }) =>
        analytics.track("support_reply_sent", { ticket_id })),

      beacon.on(E.TICKET_TRANSITIONED, ({ ticket_id, action }) =>
        analytics.track(`support_${action}`, { ticket_id })),

      // { code, message } — the customer-safe pair, nothing internal.
      beacon.on(E.ERROR, ({ code }) => analytics.track("support_error", { code })),
    ];

    // Each on() hands back its own detach function.
    addEventListener("pagehide", () => detach.forEach((off) => off()));
  }
</script>

metadata travels with every submission and is shown to your support staff beside the ticket. It is internal-visibility only: your customer never sees it, and it never appears in an event payload.

<script type="module">
  import { boot } from "https://cdn.beacon.example/widget/v1/loader.js";

  boot({
    baseUrl:   "https://support.example.com/api/v1/widget",
    projectId: "prj_4f9c2a…",
    getAssertion: mintAssertion,          // as in Minimal

    // What triage wants to know before anyone opens the ticket.
    metadata: {
      plan:             "enterprise",
      seats:            240,
      account_age_days: 612,
      flags:            ["new-billing", "sso"],
      portal_release:   "portal@2026.8.3",
    },
  });
</script>

It is the object you passed, read when a request is submitted rather than copied at boot. Updating a field on it later is picked up; swapping your variable for a different object is not.