Quickstart Guide

Last updated

July 3, 2025

This section helps you run your first live measurement integration on a web page in less than 5 minutes. All you need is a web browser and your Saphere API Key.

Step-by-Step Example

This example loads the Saphere Scan widget from a public CDN, defines how the widget should behave (language, event logging, measurement strategy), and uses your API key to authenticate the measurement request. When the file is opened in a browser, the widget initializes and prompts the user to start a live scan.

Open your browser and copy the HTML below into a file named index.html.
Get your API Key from the Saphere Ops Portal and replace the example token in the Authorization header.
Double-click the file to open it in your browser.
Allow camera access and start your first scan!

👉 You can also download the complete HTML example file and run it directly.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, height=device-height, initial-scale=1, minimum-scale=1, maximum-scale=1, user-scalable=0" />
    <title>Saphere Scan Example</title>
    <style>
      html, body { padding: 0; margin: 0; overflow: hidden; }
      #container { height: 100vh; }
      #container:not(.mobile) { aspect-ratio: 9/16; margin: auto; }
    </style>
  </head>
  <body>
    <div id="container"></div>
    <script type="module">
      import { Handler } from "https://cdn.test.saphere.ai/saphere-scan/mjs/main.min.js"

      const container = document.getElementById("container")
      const options = {
        createMeasure: {
          strategy: "delegate",
          url: "https://api.test.saphere.ai/measures",
          // ⚠ Replace this with your real token from the Ops Portal ⚠
          headers: { Authorization: `Bearer YOUR_API_KEY_HERE` }
        },
        onEvent: console.log,
        allowLeave: true,
        lang: "en"
      }

      if (Handler.isMobile)
        container.classList.add("mobile")
      Handler.load(container, options)
    </script>
  </body>
</html>

⚠️ Security Note: This is for testing purposes only. Never expose your API Key in production code or frontend apps.

‍

How It Works

The HTML page creates a full-screen container (#container) to host the scan widget.
The script loads the Saphere Scan module from the CDN as an ES module.
An options object is defined to configure the widget:
- createMeasure.strategy = 'delegate' tells the widget to use a secure server call to create a measurement.
- The Authorization header carries the Bearer token (your API key).
- The default UI language is set to English (lang: 'en').
- All widget lifecycle events are printed in the browser console via onEvent: console.log.
The code checks if the device is mobile to apply responsive styling.
Finally, Handler.load() mounts the widget.

This simple example launches the widget, starts a scan, and logs events to your browser console.

‍