Sledování skenů a analytika

Přehled

Každé naskenování dynamického QR kódu vytvoří záznam o skenu (Scan-Record) ve vašem workspace. Sběr dat probíhá kompletně na Cloudflare Edge – bez externích sledovacích služeb, bez souborů cookies a bez toho, aby původní IP adresa kdykoli dosáhla vaší databáze.

Tři způsoby, jak využívat data o skenech:

Agregační API

GET /v1/codes/:id/scans — časové řady + nejčastější země/zařízení/OS pro jeden objekt kódu.

Webhooks (v reálném čase)

Událost qr.scanned na každý sken, podepsaná pomocí HMAC-SHA256. Viz Webhooks.

Dashboard

Vizualizace na nástěnce qr3.app – není nutné žádné volání API.

Jaká data jsou shromažďována

Pro každý sken se vytvoří záznam v tabulce scans:

Pole	Zdroj	Příklad
`id`	UUID generované serverem	`scn_d1f8…`
`code_id`	ID naskenovaného QR kódu	`qr_a1b2c3d4`
`workspace_id`	Workspace kódu	`ws_xxx`
`country`	Cloudflare `cf.country`	`AT`
`region`	Cloudflare `cf.region`	`Vienna`
`city`	Cloudflare `cf.city`	`Wien`
`device_type`	Parsování User-Agenta	`mobile`, `tablet`, `desktop`
`os`	Parsování User-Agenta	`iOS`, `Android`, `macOS`, `Windows`
`browser`	Parsování User-Agenta	`Safari`, `Chrome`, `Firefox`
`referer`	HTTP hlavička `Referer`	`https://example.com/landing`
`language`	Hlavička `Accept-Language` (první jazyk)	`de`
`redirected_to`	Skutečný cíl přesměrování	`https://example.com`
`ip_hash`	Denní pseudonym HMAC-SHA-256 (dlouhodobé tajemství + účel + den UTC + IP)	`8f3a…`
`scanned_at`	Časové razítko ISO-8601	`2026-05-12T14:32:11.000Z`

Geolokace na Edge

Všechna geografická data (country, region, city) pocházejí z objektu cf od Cloudflare a jsou založena na databázi Cloudflare Geo-IP. Nedotazují se žádné externí Geo-IP služby – vyhodnocení probíhá ve stejném Workeru, který provádí i přesměrování.

To má tři důsledky:

Nízká latence – žádný další skok (hop), žádný DNS dotaz na externího poskytovatele.
Ochrana osobních údajů – IP adresa neopustí Cloudflare a nikdy není předána třetím stranám.
Omezená granularita – hodnota city není vždy k dispozici (např. u VPN, mobilních operátorů nebo malých regionů). Počítejte s hodnotami null a zohledněte je ve svých nástěnkách.

Dotazování na analytiku skenů

`GET /v1/codes/:id/scans`

Vrací agregovanou analytiku pro jeden QR kód za zvolené časové období.

curl "https://qr3.app/v1/codes/qr_a1b2c3d4/scans?days=30" \
  -H "Authorization: Bearer qr3_sk_..."

const analytics = await qr3.scans.get('qr_a1b2c3d4', { days: 30 });
console.log(analytics.period_scans, analytics.top_countries);

qr3 scans qr_a1b2c3d4 --days 30

Parametry dotazu (Query Parameters):

Parametr	Typ	Výchozí	Popis
`days`	integer	`30`	Časové období ve dnech (1–365)

Odpověď (HTTP 200):

{
  "data": {
    "code_id": "qr_a1b2c3d4",
    "short_code": "r7f3Kx",
    "total_scans": 1842,
    "period_days": 30,
    "period_scans": 367,
    "scans_by_day": [
      { "date": "2026-04-13", "count": 12 },
      { "date": "2026-04-14", "count": 18 }
    ],
    "top_countries": [
      { "value": "AT", "count": 142 },
      { "value": "DE", "count": 98 },
      { "value": "CH", "count": 41 }
    ],
    "top_devices": [
      { "value": "mobile", "count": 281 },
      { "value": "desktop", "count": 72 },
      { "value": "tablet", "count": 14 }
    ],
    "top_os": [
      { "value": "iOS", "count": 158 },
      { "value": "Android", "count": 123 },
      { "value": "macOS", "count": 48 }
    ]
  },
  "meta": { "request_id": "req_xyz123" }
}

Pole odpovědi:

Pole	Popis
`total_scans`	Celkový počet skenů kódu za celou dobu (nezávisle na časovém okně `days`)
`period_scans`	Součet skenů ve zvoleném časovém okně
`scans_by_day`	Denní skupiny (buckets), vzestupně podle data, prázdné dny jsou vynechány
`top_countries`	Nejčastějších 8 zemí v časovém okně, sestupně
`top_devices`	Nejčastějších 5 typů zařízení (`mobile`, `tablet`, `desktop`)
`top_os`	Nejčastějších 5 operačních systémů

Agregace přes více kódů

Celkové součty za celý workspace (např. skeny za měsíc přes všechny kódy) jsou k dispozici přes GET /v1/workspaces/:id v poli scans_this_month. Pro analýzy napříč kódy doporučujeme použít nástěnku (dashboard) nebo pravidelný export.

Zpracování v reálném čase přes webhooks

Pokud chcete zpracovávat události skenování okamžitě, jakmile nastanou – například pro živé nástěnky, sledování leadů nebo integraci s CRM – přihlaste se k odběru události qr.scanned:

curl -X POST https://qr3.app/v1/webhooks \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/qr3",
    "events": ["qr.scanned"],
    "secret": "my-secret-key-min-16-chars"
  }'

Payload (tělo zprávy):

{
  "id": "evt_abc123xyz",
  "type": "qr.scanned",
  "created": "2026-05-12T14:32:11.000Z",
  "data": {
    "code_id": "qr_a1b2c3d4",
    "short_code": "r7f3Kx",
    "scan_id": "scn_d1f8...",
    "country": "AT",
    "device_type": "mobile",
    "os": "iOS"
  }
}

Kompletní dokumentace k ověřování podpisů, logice opakování (retry) a protokolům doručení (delivery logs) v API → Webhooks.

Záznamy neukládají původní IP. Edge Worker odvodí pseudonym HMAC-SHA-256 z dlouhodobého tajemství, účelu a dne UTC; pseudonym zůstává osobním údajem.

Bez tajemství není hodnota přímo vratná, držitel tajemství však může pro den UTC znovu vypočítat známé kandidáty IP.
Účel a den UTC jsou součástí odvození, proto hashe stejného skeneru v různých dnech nejsou přímo porovnatelné.
Původní IP nedosáhne D1, KV ani R2.

V období přes více dnů je unique_scanners metrika Dny skenování, nikoli lidí: stejný skener dostane pro každý den UTC samostatný pseudonym.

Doba uchování (retence) závisí na tarifu:

Tarif	Doba uchování
Free	7 dní
Pro	90 dní
Business / Agency	1 rok
Enterprise	Vlastní (SLA)

Denně spouštěná plánovaná úloha (cron job purgeOldScans) automaticky odstraňuje starší záznamy – hodnota total_scans u objektu kódu tím zůstává nedotčena.

Podrobnosti o GDPR a API pro poskytování informací Hashování IP adres, Sub-Processor-DPA, export dat a právo na být zapomenut.

Doporučené postupy

Frekvence dotazování (polling): Agregační API je rychlé a efektivní, ale není určeno pro dotazování každou sekundu. Pro živé aktualizace vždy upřednostňujte webhooks a API používejte pouze pro zpětné načítání dat (backfills) nebo nástěnky.
Caching (ukládání do mezipaměti): Odpověď obsahuje časové řady – při velkých časových oknech (days=365) může mít payload velikost několik KB. Ukládejte data do mezipaměti na straně klienta s krátkou dobou platnosti (TTL, např. 60 s).
Limity Top-N: Pole top_countries, top_devices a top_os jsou na straně serveru omezeny na 8, respektive 5 záznamů. Pro hlubší analýzy exportujte surová data.
Tolerance hodnot null: Pole country, region, city, referer a language mohou mít hodnotu null. Ve svém vyhodnocení s nimi pracujte jako s „Neznámými“ (Unknown).