window.ExpressConsent

The script attaches a single global. Everything the SDK offers hangs off it.

Loading the script

<script
  src="https://sdk.expressconsent.com/sdk/v1/sdk.js"
  data-ec-cid="YOUR_CID"
  async
></script>

async is correct here: nothing is needed until a person submits a form, so the script should not block your page from rendering. defer works too.

The script has to run in the same document as the form it captures. It reads the page it is loaded into and nothing else, so a form inside an iframe needs the script inside that iframe.

Loading with a backup URL

The script is served through a CDN. If that CDN cannot be reached from a visitor's browser, due to a rare outage for instance, the script does not load and nothing is captured on that page. To guard against that, load it with this snippet instead of the tag above. It tries the primary URL and switches to an independent backup host if the primary fails or has not loaded within 10 seconds.

<script>
  (function (cid, urls) {
    function load(i) {
      var script = document.createElement("script");
      var switched = false;
      function next() {
        if (switched || window.ExpressConsent || i + 1 >= urls.length) return;
        switched = true;
        load(i + 1);
      }
      script.src = urls[i];
      script.async = true;
      script.setAttribute("data-ec-cid", cid);
      script.onerror = next;
      setTimeout(next, 10000);
      document.head.appendChild(script);
    }
    load(0);
  })("YOUR_CID", [
    "https://sdk.expressconsent.com/sdk/v1/sdk.js",
    "https://expressconsent-prod-sdk.web.app/sdk/v1/sdk.js",
  ]);
</script>

Both URLs serve the same file, and the SDK behaves identically whichever one loads. If your Content Security Policy blocks inline scripts, add your nonce to this script tag, and allow both hosts in script-src.

Your submit handler stays the same. Until a copy has loaded, window.ExpressConsent is undefined, so calling it throws inside your try and the submission continues, exactly as when the plain tag has not loaded.

Error events

Every error the SDK throws is also dispatched on window as an expressconsent:error event, so you can route SDK failures into your own monitoring without wrapping every call site.

window.addEventListener("expressconsent:error", (event) => {
  reportToMonitoring(event.detail.code, event.detail.message);
});

The detail carries name (always "ExpressConsentError"), code, message, and timestampMs; the page url when it can be read; details with backendCode and backendMessage when the server rejected the upload; and a cause summary when there was an underlying error.

Route details.backendCode into monitoring; it is the reason behind an UPLOAD_FAILED. Codes are listed on SDK errors.