Skip to main content

Beacon Control

Overview​

The Beacon Control is a lightweight web control designed to collect non-sensitive, contextual signals from a user's browser session and deliver them to an agent or analytics backend. It is optimized for minimal performance impact and intended for use-cases that require session context (e.g., last interaction, page visibility, referrer) rather than personal or sensitive data.

What It Collects​

The Beacon Control collects the following signals by default:

  • Page URL: Current URL (path and query) where the control runs.
  • Referrer: Document referrer when available.
  • Page Title: The document.title value.
  • User Agent Short: A short browser identifier (no full UA string unless explicitly enabled).
  • Device and Locale: Browser, operating system, language, and device category.
  • Geo Location: Approximate geographic location such as country and region.

Note: The control does not collect names, emails, credentials, or long-form user content by default. It does collect device/browser characteristics and approximate location fields shown in the example payload below.

Example JSON Stored in DB​

{
  "entrySource": {
    "engine": "XXXX",
    "engineType": "YYYYY",
    "referrerDomain": "ZZZZZZ",
    "landingPage": {
      "url": "https://ai12z.com/ai-experience-platform/?utm_source=VVVVVV",
      "path": "/ai-experience-platform/",
      "title": "AI Experience Platform | ai12z"
    },
    "utm": {
      "source": "VVVVVV",
      "medium": null,
      "campaign": null,
      "content": null,
      "term": null
    },
    "device": {
      "category": "desktop",
      "browser": "Chrome",
      "operatingSystem": "macOS",
      "language": "en-US",
      "countryCode": "US",
      "region": "MA"
    }
  }
}

Integration Example​

HTML

<script
  type="module"
  src="https://cdn.ai12z.net/pkg/ai12z@latest/dist/esm/library.js"
></script>
<link
  rel="stylesheet"
  href="https://cdn.ai12z.net/pkg/ai12z@latest/dist/library/library.css"
/>
<ai12z-beacon data-key="XXXXXX" data-mode="dev"></ai12z-beacon>

Setup​

Add the following to the <head> of pages that use the Beacon Control:

<script
  type="module"
  src="https://cdn.ai12z.net/pkg/ai12z@latest/dist/esm/library.js"
></script>
<link
  rel="stylesheet"
  href="https://cdn.ai12z.net/pkg/ai12z@latest/dist/library/library.css"
/>

Attributes​

<ai12z-beacon data-key="YOUR_API_KEY"></ai12z-beacon>
AttributeRequiredDescriptionExampleDefault
data-keyYesYour agent API key (from Agent Settings). Can also be provided via JS.data-key="YOUR_API_KEY"
disableNoBoolean flag to disable beacon collection when set to true.disable="true"false
data-modeNoRuntime mode: dev or prod.data-mode="dev"prod

Configure via JavaScript​

You can instantiate or configure the control programmatically after page load:

<script>
  document.addEventListener("DOMContentLoaded", () => {
    const beaconEl = document.querySelector("ai12z-beacon")
    beaconEl.setAttribute("data-key", "YOUR_API_KEY")
    beaconEl.setAttribute("data-mode", "dev")
  })
</script>

The disable property is a boolean and defaults to false. Set it to true to disable beacon collection.

Complete Example​

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>ai12z Beacon Control</title>

    <!-- ai12z web components -->
    <script
      type="module"
      src="https://cdn.ai12z.net/pkg/ai12z@latest/dist/esm/library.js"
    ></script>
    <link
      rel="stylesheet"
      href="https://cdn.ai12z.net/pkg/ai12z@latest/dist/library/library.css"
    />
  </head>

  <body>
    <ai12z-beacon data-mode="dev"></ai12z-beacon>

    <script>
      document.addEventListener("DOMContentLoaded", function () {
        const beacon = document.querySelector("ai12z-beacon")
        beacon.setAttribute("data-key", "YOUR_API_KEY")
      })
    </script>
  </body>
</html>

Use Cases​

ScenarioWhy use Beacon
Assist contextProvide page context to the assistant for better answers
AnalyticsLightweight session signals for page analytics
DebuggingCapture visibility and referrer to reproduce issues

Disable Beacon​

Set disable to true to stop collecting metadata without removing the control. The default value is false.

Troubleshooting​

  • If the control doesn't send beacons, confirm data-key.
  • Check browser console for CORS or network errors.
  • Ensure your backend accepts the beacon payload and that HTTPS is used.
Last updated on