Installing the widget

The widget is the script an Institution pastes into its website. It does two jobs at once: it is the tracker that feeds the live visitor list, and it is the chat surface the visitor talks through.

One file, no runtime dependencies, no framework, roughly 9 KB gzipped.

Install

<script src="https://support.acme.go.ke/widget.js" data-site="ts_abc123"></script>

That is the whole installation. Put it before </body> on every page.

The exact snippet for a site, with its own key already filled in, is on the Sites screen and is returned by GET /v1/sites/{site_id}/snippet.

Attributes

Loading it asynchronously

If a tag manager loads widget.js with async, queue calls so nothing is lost before the bundle arrives:

<script>
  window.TaifaSupport = window.TaifaSupport || { q: [] };
  window.TaifaSupport.q.push(["identify", { id: "183", name: "James Mwangi" }]);
</script>
<script async src="https://support.acme.go.ke/widget.js" data-site="ts_abc123"></script>

The queue is drained in order as soon as the bundle boots.

It cannot break the host page

This is a design constraint rather than a claim, because the widget runs on someone else's page, often a government portal that nobody wants to be responsible for taking down.

• Every network call resolves to null rather than rejecting. There is no unhandled rejection to surface in the portal's own error tracking.
• Every storage call is wrapped. Safari private mode throws on localStorage access, not only on write.
• Every listener runs inside a guard. A listener that throws is caught and logged, never rethrown into the page.
• The whole boot is inside one try/catch.
• A circuit breaker opens after three consecutive failures and the widget stops touching the network for up to five minutes, so an outage cannot become a retry storm from every visitor at once.
• With data-debug absent, nothing is ever written to the console.

Shadow DOM isolation

The whole UI lives in a shadow root with all: initial on the host, so the portal's CSS cannot reach in and the widget's cannot leak out. If a browser has no attachShadow, the UI does not mount and the tracker keeps working: a visitor on an ancient browser still appears in the live list, they just cannot chat.

Single-page applications produce pageviews

history.pushState and replaceState are patched, preserving their return value and receiver, and popstate and hashchange are handled.

A burst of router calls collapses into one pageview for the final URL, so a transition that writes history three times does not report three pages. That matters because page_view_count is a column an agent reads on the live row, and inflating it makes the row lie.

Accessibility

• The launcher is a real button with aria-haspopup, aria-expanded and an accessible name that includes the unread count.
• The panel is role="dialog" with aria-modal="false" and no focus trap. The visitor is still on your page, and trapping them in a support widget would be hostile.
• Escape closes the panel and returns focus to the launcher.
• The transcript is role="log" with aria-live="polite". The typing indicator announces through a visually hidden status region.
• prefers-reduced-motion is respected.

On a narrow viewport, opening the panel focuses the panel rather than the composer, so the on-screen keyboard does not cover the transcript before anything has been read.

Endpoints it calls

Full request and response shapes are in the track reference.

Next

• The window.TaifaSupport API
• The identify() contract
• Consent and privacy