Sledovanie skenov a analytika

Prehľad

Každé naskenovanie dynamického QR kódu vytvorí záznam o skenovaní (Scan-Record) vo vašom workspace. Zhromažďovanie prebieha úplne na Cloudflare-Edge — bez externých sledovacích služieb, bez súborov cookies a bez toho, aby pôvodná IP adresa kedykoľvek dosiahla vašu databázu.

Tri spôsoby, ako konzumovať dáta o skenovaní:

Agregačné API

GET /v1/codes/:id/scans — časové rady + top krajiny/zariadenia/OS pre jeden objekt kódu.

Webhooky (v reálnom čase)

Udalosť qr.scanned na jedno naskenovanie, podpísaná pomocou HMAC-SHA256. Pozrite si Webhooky.

Dashboard

Vizualizácia v dashboarde qr3.app — nie je potrebný žiadny API hovor.

---

Aké údaje sa zhromažďujú

Pre každé naskenovanie sa vytvorí záznam v tabuľke scans:

Pole	Zdroj	Príklad
id	Serverom generované UUID	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	Parsovanie User-Agenta	mobile, tablet, desktop
os	Parsovanie User-Agenta	iOS, Android, macOS, Windows
browser	Parsovanie User-Agenta	Safari, Chrome, Firefox
referer	HTTP hlavička Referer	https://example.com/landing
language	Hlavička Accept-Language (prvý jazyk)	de
redirected_to	Skutočný cieľ presmerovania	https://example.com
ip_hash	SHA-256(IP + denný salt) — nereverzibilný	8f3a…
scanned_at	Časová pečiatka ISO-8601	2026-05-12T14:32:11.000Z

Tip

Minimalizácia údajov by Design: Nenastavujú sa žiadne súbory cookies, nevykonáva sa žiadny fingerprinting a nenačítavajú sa žiadne externé sledovacie pixely. Pôvodná IP adresa sa v Edge-Workeri okamžite prevedie na denne rotujúci SHA-256 hash a nikdy neopustí Edge.

Geolokácia na Edge

Všetky geografické údaje (country, region, city) pochádzajú z objektu cf od Cloudflare a sú založené na databáze Cloudflare Geo-IP. Nenachádzajú sa žiadne dopyty na externé služby Geo-IP — rozlíšenie prebieha v rovnakom Workeri, ktorý vykonáva aj presmerovanie.

To má tri dôsledky:

1. Nízka latencia — žiadny dodatočný hop, žiadne vyhľadávanie DNS u externého poskytovateľa.
2. Ochrana osobných údajov — IP adresa neopúšťa Cloudflare a nikdy sa neposkytuje tretím stranám.
3. Obmedzená granularita — city nie je vždy k dispozícii (napr. pri VPN, mobilných operátoroch alebo malých regiónoch). Počítajte s hodnotami null a zohľadnite ich vo svojich dashboardoch.

---

Dopytovanie analytiky skenovania

GET /v1/codes/:id/scans

Poskytuje agregovanú analytiku pre jeden QR kód za zvolené časové obdobie.

cURL

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

TypeScript SDK

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

CLI

qr3 scans qr_a1b2c3d4 --days 30

Query parametre:

Parameter	Typ	Predvolené	Popis
days	integer	30	Časové obdobie v dňoch (1–365)

Odpoveď (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" }
}

Polia odpovede:

Pole	Popis
total_scans	Celkový počet skenovania kódu za celú dobu (nezávisle od časového okna days)
period_scans	Suma skenov vo zvolenom časovom okne
scans_by_day	Denné buckety, vzostupne podľa dátumu, prázdne dni sú vynechané
top_countries	Top 8 krajín v časovom okne, zostupne
top_devices	Top 5 typov zariadení (mobile, tablet, desktop)
top_os	Top 5 operačných systémov

Poznámka

Agregačné API neposkytuje žiadne jednotlivé záznamy o skenovaní — ani prostredníctvom stránkovania kurzorom (Cursor-Pagination). Pre surové streamy udalostí použite namiesto toho webhooky (pozri nižšie). Ak potrebujete historické surové dáta, exportujte ich cez GET /v1/account/export.

Agregácia cez viacero kódov

Sumy za celý workspace (napr. skeny za mesiac pre všetky kódy) sú k dispozícii cez GET /v1/workspaces/:id v poli scans_this_month. Pre analýzy naprieč kódmi odporúčame dashboard alebo periodický export.

---

Spotreba v reálnom čase cez webhooky

Ak chcete spracovávať udalosti skenovania hneď, ako nastanú — napríklad pre živé dashboardy, sledovanie leadov alebo integrácie CRM — prihláste sa na odber udalosti 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:

{
  "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"
  }
}

Úplná dokumentácia k overovaniu podpisov, logike opakovaných pokusov (retry) a doručovacím logom v API → Webhooks.

---

GDPR & ochrana osobných údajov

Záznamy o skenovaní neobsahujú žiadne osobné IP adresy. Pôvodná IP adresa sa v Edge-Workeri nahradí kryptografickou hashovacou funkciou (SHA-256) s denne rotujúcim saltom. To znamená:

• Žiadna opätovná identifikácia ani pri znalosti algoritmu
• Žiadna korelácia rovnakého návštevníka naprieč dňami
• Pôvodná IP adresa nikdy nedosiahne databázu D1

Uchovávanie údajov (Retention) závisí od programu:

Program	Uchovávanie
Free	7 dní
Pro	90 dní
Business / Agency	1 rok
Enterprise	Vlastné (SLA)

Denne spúšťaná úloha cron (purgeOldScans) automaticky odstraňuje staršie záznamy — hodnota total_scans na objekte kódu zostáva nedotknutá.

GDPR-Details & Auskunfts-API Hashovanie IP adries, DPA subdodávateľov, export dát a právo na zabudnutie.

---

Najlepšie postupy

• Frekvencia dopytovania (Polling): Agregačné API je efektívne, ale nie je určené na dopytovanie každú sekundu. Pre živé aktualizácie vždy uprednostňujte webhooky a API používajte iba na spätné načítanie (backfill) / dashboardy.
• Caching: Odpoveď obsahuje časové rady — pri veľkých oknách (days=365) môže mať payload veľkosť niekoľko KB. Ukladajte do vyrovnávacej pamäte (cache) na strane klienta s krátkou TTL (napr. 60 s).
• Limity Top-N: top_countries, top_devices, top_os sú na strane servera obmedzené na 8, resp. 5 záznamov. Pre hlbšie analýzy exportujte surové dáta.
• Tolerovanie hodnôt null: country, region, city, referer, language môžu byť null. Vo svojom vyhodnotení s nimi zaobchádzajte ako s „Neznámymi“.