Widget configuration

The script tag, every data-* attribute of the declarative widget, render options, callbacks, languages and accessibility.

The script

HTML
<script src="https://agentgate.example/sdk/v1/agentgate.js" async></script>
  • /sdk/v1/agentgate.js is the latest 1.x SDK. A breaking change would get /sdk/v2/. The loaded version is AgentGate.version and is also sent in the X-AgentGate-SDK-Version response header.
  • The SDK talks to the origin that served the script unless you pass an endpoint.
  • The proof of work runs in a Web Worker loaded from /sdk/v1/worker.js on the same endpoint.
  • async and defer are both fine. Widgets render when the document is parsed.

Declarative widget

Any element with the class agentgate and a data-sitekey attribute becomes a widget when the document is ready:

HTML
<form method="post" action="/signup">
  <input name="email" type="email" required>
  <div class="agentgate" data-sitekey="site_…" data-action="signup"
       data-mode="managed" data-lang="fr"></div>
  <button>Sign up</button>
</form>
AttributeRequiredDefaultMeaning
class="agentgate"yesmarks the element as a widget
data-sitekeyyesthe site's public key, site_…
data-actionyesthe action to verify, [a-z0-9_]{1,64}; must be configured for the site
data-modenoinvisibleinvisible, managed or interactive (modes)
data-langnothe page's lang, then the browser's languagesUI language: en, es, fr, de, pt, hi, ja, zh
data-endpointnothe script's originyour AgentGate endpoint, when the script comes from elsewhere

Declarative widgets have no callback attributes. To be told about tokens or errors, render the widget from code with AgentGate.render() (below).

What the widget does in a form

  • It finds its enclosing <form> and adds a hidden input named agentgate_token, unless the form already has one (then it uses yours).
  • When the form is submitted without a fresh token, the widget stops the submission, verifies, fills agentgate_token, and submits the form again with the same submit button (requestSubmit).
  • After a submission the token is cleared, so the next submission verifies again. A token is also cleared five seconds before it expires.
  • In interactive mode a submission before verification is blocked and the chip says "Please complete the verification first."

Your server reads agentgate_token from the form body and redeems it with POST /v1/siteverify.

Rendering from code

AgentGate.render(element, options) creates the same widget and returns its id. element is an element or a CSS selector.

JavaScript
const id = AgentGate.render("#signup-widget", {
  siteKey: "site_…",
  action: "signup",
  mode: "managed",
  callback: (token, result) => console.log("verified", result.decisionId),
  errorCallback: (err) => console.warn("AgentGate:", err.code),
  expiredCallback: () => console.log("token expired"),
});
OptionMeaning
siteKeythe site key (else data-sitekey, else the init() site key)
actionthe action (else data-action)
modeinvisible, managed or interactive (else data-mode)
langUI language (else data-lang, the page's lang, the browser's)
endpointthe AgentGate endpoint (else data-endpoint, the init() endpoint, the script's origin)
callback(token, result)a token was issued; result is {token, expiresAt, decisionId, clearance?, clearanceExpiresAt?}
errorCallback(error)verification failed; error.code is one of AgentGate.errors
expiredCallback()the token was cleared because it was about to expire

The hyphenated names error-callback and expired-callback are accepted too. Manage rendered widgets with getResponse(id), reset(id) and remove(id); see the JavaScript API.

Languages

The widget has strings for English (en), Spanish (es), French (fr), German (de), Portuguese (pt), Hindi (hi), Japanese (ja) and Chinese (zh); AgentGate.locales lists them. The language is chosen from, in order: the lang option or data-lang, the page's <html lang>, then the browser's preferred languages, matched on the primary subtag (fr-CA uses fr). Anything else falls back to English.

Accessibility

  • The status chip is a polite live region (role="status").
  • The check is a labelled group inline, or a modal dialog (aria-modal) when there is no widget element to hold it; focus moves into it and back afterwards, and Tab stays inside the dialog.
  • Press and hold works with a mouse, touch, or Space / Enter held on the focused button. "Verify another way" needs no pointer, timing or puzzle (WCAG 2.2 success criterion 3.3.8).
  • Progress is a progressbar with aria-valuenow, announced every five seconds during the wait alternative.
  • Nothing animates when the person prefers reduced motion.
  • The widget uses CSS system colours (Canvas, CanvasText, ButtonFace, Highlight), which follow the page's color-scheme and forced-colours (high contrast) mode.

Styling hooks

The widget styles its own elements through the CSSOM, so there is no stylesheet to load and CSP style-src needs no change. Stable class names you can target: agentgate-chip (with data-state), agentgate-start (the Verify button), agentgate-check, agentgate-hold, agentgate-alt and agentgate-overlay (the dialog backdrop).

View as Markdown