Web Widget

The Web Widget adds BiomAPI’s upload and review interface to your browser application. Users can process or retrieve a report in a popup, compare it with the original, and edit values. Your application receives the reviewed result when they press Send.

Open the widget through the Browser SDK; the complete example below includes its setup. Try the live demo. Choose the REST API when you want to build the review interface yourself or process reports on a server.

Quick start

Save this as an HTML page and serve it from your application’s HTTPS origin. Open the widget directly from a click so the browser can allow the popup. For a trial, upload the synthetic JSON report inside the widget.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Import biometry</title>
</head>
<body>
  <button id="import-biometry" type="button">Import with BiomAPI</button>
  <p id="status" role="status"></p>
  <pre id="result"></pre>
  <script src="https://biomapi.com/static/js/biomapi-sdk.js"></script>
  <script>
    const importButton = document.getElementById('import-biometry');
    const status = document.getElementById('status');
    const result = document.getElementById('result');

    importButton.addEventListener('click', async () => {
      try {
        const response = await BiomAPI.widget.open({
          integrator: { id: 'example-ehr', name: 'Example EHR' }
        });
        if (response === null) {
          status.textContent = 'Import cancelled. No data received.';
          return;
        }
        result.textContent = JSON.stringify(response.data, null, 2);
        status.textContent = 'Reviewed biometry received.';
      } catch (error) {
        status.textContent = `Import failed: ${error.message}`;
      }
    });
  </script>
</body>
</html>

This example displays the received measurements; replace that display with your form-filling code. For a working demonstration with sharing and retrieval, see the official demo. Treat the response as patient data and avoid logging it in production.

The example loads the hosted Browser SDK, which follows the current BiomAPI deployment. Its interface is in active development; review the reference when updating your integration.

Identify your application

Use a stable integrator.id of up to 64 characters. Start it with a lowercase letter or digit. The remaining characters may also include ., _, or -.

Set integrator.name to the name users should see in the widget’s green handoff bar. Use up to 80 characters.

BiomAPI uses these values to display your application’s name and identify requests from it. They do not authenticate your application. The biomapi.* namespace is reserved by convention for official clients.

Handle the result

BiomAPI.widget.open() returns a promise:

Outcome	Result
User presses Send	Reviewed StandardAPIResponse
User presses Cancel or closes the popup	null
Popup or connection fails	Rejected promise with a widget error

The result card’s Close action clears the current result; it does not cancel the whole widget. Only one widget session can be active per page. Calling open() again focuses the existing popup and returns the same promise.

Invalid integrator options throw an error immediately. Popup and connection failures reject the promise. A surrounding try/catch, as above, handles both.

BiomAPI.widget.BiomAPIWidgetError exposes one of these code values: INVALID_INTEGRATOR, POPUP_BLOCKED, CONNECTION_TIMEOUT, or CONNECTION_FAILED.

Patient identifiers

Names are converted to uppercase initials by BiomAPI. When initials or an ID are available, the result’s identity selector lets the user include them or choose Anonymous before sending.

Anonymous sets only data.patient.name and data.patient.id to null. Other fields remain. The report is therefore not fully anonymous. BiomPIN storage removes these two identifiers regardless of the widget selection. See sharing and identity context.

To build a BiomAPI link with available initials/ID after receiving the widget response:

const link = BiomAPI.biompin.buildUrl({
  pin: response.biompin.pin,
  context: BiomAPI.context.fromResponse(response)
});

The Browser SDK sharing examples and demo include identity for both BiomAPI and integrator links. Omit context to share without initials/ID.

Delivery and security

The SDK and widget validate the popup window, origin, and protocol, then exchange data through a dedicated MessageChannel. The opening page acknowledges receipt before the popup closes. A connection must be accepted within 15 seconds; reloading the popup requires a fresh connection.

Use HTTPS in production. Read the returned response through the SDK instead of reading the popup’s DOM. Your application receives no clinical data until the user presses Send. Processing within the popup follows the Privacy policy.

The widget adds X-BiomAPI-Integrator-ID and X-BiomAPI-Integrator-Origin to its process and retrieve requests. When analytics is enabled, BiomAPI retains the declared ID and validated origin hostname for operational attribution. No separate Send event is emitted.

For branded buttons, see Branding. For blocked popups or failed handoffs, see Troubleshooting.