Ana içerik geç

Embed snippet — the universal tracker

You spin up a state machine and you get a small JavaScript snippet you can drop on any page. The runtime is ≤ 12 KB, CSP-safe, frozen-API. Every event the snippet records becomes a row on your state machine's audit entangled state at a known Zeqond — verifiable against your hash-chain forever.

You can think of it like Google Analytics or Plausible. Same install posture: paste a tag. Different end-state: instead of feeding a third-party warehouse, your events land in your state machine. You read them via your API key. You cryptographically prove they arrived. You can't be cut off, throttled, or have your data sold.

The portal at /portal/embed lets you copy the snippet pre-filled with your machine and zsm_pub_… key. The canonical install file is at outputs/zeq-embed.snippet.html in the repo.

Three install forms​

The snippet is one line in three flavors — pick the form that matches your host CSP.

For any first-party site you control (including Squarespace, WordPress, Webflow custom-code, Shopify, etc.). Loader + runtime ≤ 12 KB combined. Single round-trip.

<script async
        src="https://zeqapi.com/embed.js"
        data-slug="MY-SLUG"
        data-key="zsm_pub_xxxxxxxxxxxxxxxx"></script>

The script self-installs on DOMContentLoaded. Once active, the host page's JS sees a frozen window.zsm with these methods:

window.zsm.event(name, data);    // arbitrary named event
window.zsm.state(stateHash);     // state-hash snapshot
window.zsm.file(fileHash, meta); // file-hash event
window.zsm.connection(meta);     // connection event
window.zsm.identify(zid);        // bind a Zeq ID to the session (optional)
window.zsm.ping();               // immediate heartbeat

The exposed object is Object.freezed and Object.defineProperty(..., {writable:false, configurable:false}) — host pages cannot tamper with it.

CSP requirement on the host page: script-src 'self' https://zeqapi.com.

B. Sandboxed iframe​

For untrusted host contexts — third-party blogs, forum signatures, Notion / Confluence embeds, browser extensions injected into pages you don't control. The iframe is sandboxed; cannot touch host DOM, cannot read host cookies. Host page talks to it via postMessage.

<iframe src="https://zeqapi.com/embed/iframe.html?slug=MY-SLUG&key=zsm_pub_xxxxxxxxxxxxxxxx"
        title="Zeq state-machine beacon"
        style="display:none" width="0" height="0"
        sandbox="allow-scripts"
        referrerpolicy="no-referrer"></iframe>

In host JS:

document.querySelector('iframe[title="Zeq state-machine beacon"]')
  .contentWindow.postMessage(
    { zsm: 'event', name: 'cta_click', data: { sku: 'pro' } },
    '*'
  );

The iframe whitelists event, state, file, identify, ping, connection. Anything else is dropped. The iframe never echoes a value back, so the host can't use it as a confused-deputy oracle.

CSP requirement: frame-src https://zeqapi.com.

C. NoScript pixel​

For AMP pages, email opens, IoT firmware, no-JS contexts. One beacon at view-time. No event surface beyond the heartbeat.

<noscript>
  <img src="https://zeqapi.com/api/embed/MY-SLUG/pixel?k=zsm_pub_xxxxxxxxxxxxxxxx&v=1.287.5"
       alt="" width="1" height="1" referrerpolicy="no-referrer" loading="eager">
</noscript>

CSP requirement: img-src https://zeqapi.com.

Browser extension form​

For Chrome / Firefox extensions: fetch from a content script. Same CSP-safe constraints (no eval).

(function () {
  var s = document.createElement('script');
  s.async = true; s.defer = true;
  s.src = 'https://zeqapi.com/embed.js';
  s.dataset.slug = 'MY-SLUG';
  s.dataset.key  = 'zsm_pub_xxxxxxxxxxxxxxxx';
  (document.head || document.documentElement).appendChild(s);
})();

IoT / firmware form​

For devices that can't run JS — send raw HTTP POST every 1–60 Zeqonds. One heartbeat per call. Endpoint accepts JSON or form-encoded.

POST https://zeqapi.com/api/embed/MY-SLUG/ingest
X-Zsm-Key: zsm_pub_xxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "v": "1.287.5",
  "slug": "MY-SLUG",
  "sid": "device-mac-or-uuid",
  "kind": "heartbeat",
  "payload": { "uptime_ms": 12345, "temp_c": 21.4 },
  "pulse": { "f": 1.287, "tau": 0.777, "alpha": 0.00129, "ns": "777000777" },
  "ts": 1777336155374
}

Public key vs. write-back key​

Your state machine has two kinds of API key:

  • zsm_pub_… — public, ships in the snippet. Read-only-public on /api/embed/:slug/ingest. Anyone scraping the snippet has it; that's expected.
  • zsm_… — write-back, NEVER ships in the snippet. Used from your backend for authoritative events.

The framework gates abuse on the public key with rate limits and per-slug quotas (see security). A leaked public key is recoverable: rotate it from /portal/embed and re-deploy the snippet.

What gets recorded on the entangled state​

Every beacon becomes a row in your audit log:

FieldSource
transition_typesnippet's kind (heartbeat / event / state / file / connection / identify)
state_hashsha256(payload) (server-side; bytes never stored on free tier)
zeqond_numberserver's HulyaPulse at receive
prev_hashchained against the previous row

You read it back via the entangled state endpoints:

curl -sS "https://zeqapi.com/api/chain/MY-SLUG/explore?from=$(date -u +%s --date '1 hour ago')000000&limit=100" \
  -H "Authorization: Bearer ${ZSM_KEY}"

Or in real-time via SSE:

const es = new EventSource(`https://zeqapi.com/api/chain/MY-SLUG/explore/sse?token=${jwt}`);
es.onmessage = (e) => console.log(JSON.parse(e.data));

CSP guarantees​

The runtime serves with:

Content-Security-Policy: default-src 'none'; connect-src 'self'

The runtime can call fetch and sendBeacon to zeq.dev, nothing else — no script loading, no font loading, no image loading, no eval, no Function. There is no path from the runtime back into the host page beyond the frozen window.zsm API.

Subresource Integrity is opt-in: /portal/embed includes a copy-paste variant with integrity="sha384-…" for hosts that pin scripts.

The build pipeline pins embed.js SHA-256 in apps/zeq-dev/public/embed.lock.json and CI fails if served bytes don't match.

Portal copy-paste flow​

  1. Sign in at https://zeqapi.com/portal.
  2. Open /portal/embed.
  3. Pick a state machine slug (or spin up a new one).
  4. Click "Mint public key" — a zsm_pub_… key is created and SHOWN ONCE in the panel.
  5. Optionally configure the origin allow-list (one or more hostnames).
  6. Copy the pre-filled <script> snippet. Paste into your host page's <head>.
  7. View /portal/embed/recent to see beacons land in real-time.

Portal is the canonical install path. The hand-rolled snippet at outputs/zeq-embed.snippet.html is the documented contract for SDKs and operators.

Where this fits​

  • The embed runtime is the public-facing tip of the framework. Host pages talk to it.
  • The /api/embed/:slug/ingest route is the only CORS-wildcard route on zeq.dev. Every other route stays origin-locked.
  • Beacons land in the same audit log as your contract transitions, your direct entangled-state writes, your tally mints. One entangled state per state machine, regardless of how rows arrive.

Next​