@gigaqr/embed

Drop a GigaQR code creation widget onto any website. One script, zero backend. Visitors create QRs against your workspace; you get a server-side qr.created webhook for every success.

Install

npm install @gigaqr/embed

Or use the ESM CDN build with a plain <script type="module">.

Usage

Modern bundler (Vite, Next.js, Webpack, Rollup...)

import { GigaQR } from '@gigaqr/embed'

const widget = GigaQR.mount('#qr-slot', {
  publishableKey: 'pk_live_...',
  theme: { primary: '#0ea5e9' },
  onCreated: (qr) => {
    // qr.scanUrl is the short URL visitors will scan
    console.log('created', qr)
  },
})

// later, to clean up:
widget.unmount()

Plain HTML

<div id="qr-slot"></div>
<script type="module">
  import { GigaQR } from 'https://esm.sh/@gigaqr/embed'

  GigaQR.mount('#qr-slot', {
    publishableKey: 'pk_live_...',
    onCreated: (qr) => console.log(qr.scanUrl),
  })
</script>

Configuration

| Option | Type | Default | Notes | | ----------------- | --------------------------------- | ------------------------- | ----- | | publishableKey | string | required | Create under Dashboard → Developer. Starts with pk_live_. | | host | string | https://gigaqr.com | Override only for self-hosted or local dev. | | theme.primary | CSS color | #0f172a | Button + accent color. | | theme.background| CSS color | #ffffff | Widget background. | | defaultQrType | 'url' | 'url' | Only url supported in v0.1. | | height | number \| string | '420px' | Numbers treated as pixels. | | width | number \| string | '100%' | | | onReady | () => void | — | Fires after the widget acknowledges init. | | onCreated | (qr: CreatedQr) => void | — | Fires on every successful create. | | onError | (err: GigaQRError) => void | — | Fires when the widget shows an error to the user. |

CreatedQr

interface CreatedQr {
  id: string        // internal UUID
  hash: string      // short hash used in the scan URL
  qrType: string
  scanUrl: string   // e.g. https://gigaqr.com/scan/abc123
}

Security model

The widget is a sandboxed iframe loaded from your host (default https://gigaqr.com). The SDK and the widget both verify MessageEvent.origin on every postMessage, so an attacker page can't spoof create events to your listener.

Your publishable key is origin-restricted. When you create a key, add every site it will run on (e.g. https://acme.com) to the key's allowed origins. Requests from other origins are rejected at /api/v1/widget/qr.

Always trust the qr.created webhook on your workspace as the authoritative event — the onCreated client callback is advisory only.

Local development

Point the widget at your dev server:

GigaQR.mount('#qr-slot', {
  publishableKey: 'pk_live_...',
  host: 'http://localhost:3000',
})

You'll also need to add http://localhost:3000 (or wherever your demo page is served from) to the publishable key's allowed origins.

Examples

See the examples/ folder for:

• examples/vanilla/ — static HTML page, no build step.
• examples/react/ — Vite + React app.
• examples/node-rest/ — Node script hitting the REST API with a secret key (the non-embed path, for server-side automation).

Versioning

@gigaqr/embed follows semver. The postMessage protocol is considered public API and will only break on major version bumps.