Sledenje skeniranjem & analitika

Pregled

Vsak sken dinamične QR-kode ustvari zapis o skeniranju (Scan-Record) v vašem delovnem prostoru (Workspace). Zbiranje podatkov poteka v celoti na Cloudflare Edge — brez zunanjih storitev sledenja, brez piškotkov in brez tega, da bi izvirni IP-naslov kadar koli dosegel vašo bazo podatkov.

Trije načini za uporabo podatkov o skeniranju:

API za agregacijo

GET /v1/codes/:id/scans — časovne vrste + top države/naprave/OS za posamezen objekt kode.

Webhooks (v realnem času)

Dogodek qr.scanned na sken, podpisan s HMAC-SHA256. Glejte Webhooks.

Nadzorna plošča

Vizualizacija na nadzorni plošči qr3.app — klic API ni potreben.

---

Katere podatke zbiramo

Za vsak sken se ustvari zapis v tabeli scans:

Polje	Vir	Primer
id	UUID, ustvarjen na strežniku	scn_d1f8…
code_id	ID skenirane QR-kode	qr_a1b2c3d4
workspace_id	Delovni prostor (Workspace) kode	ws_xxx
country	Cloudflare cf.country	AT
region	Cloudflare cf.region	Vienna
city	Cloudflare cf.city	Wien
device_type	Razčlenjevanje uporabniškega agenta (User-Agent)	mobile, tablet, desktop
os	Razčlenjevanje uporabniškega agenta (User-Agent)	iOS, Android, macOS, Windows
browser	Razčlenjevanje uporabniškega agenta (User-Agent)	Safari, Chrome, Firefox
referer	HTTP-glava Referer	https://example.com/landing
language	Glava Accept-Language (prvi jezik)	de
redirected_to	Dejanski cilj preusmeritve	https://example.com
ip_hash	Dnevni psevdonim HMAC-SHA-256 (dolgotrajna skrivnost + namen + dan UTC + IP)	8f3a…
scanned_at	Časovni žig ISO-8601	2026-05-12T14:32:11.000Z

Tip

Zmanjševanje količine podatkov s snovanjem (Data minimization by design): Piškotki se ne nastavljajo, prstni odtisi se ne zbirajo, zunanje slikovne pike za sledenje se ne nalagajo. Edge Worker izvorni IP takoj psevdonimizira s HMAC-SHA-256, dolgotrajno skrivnostjo, namenom in dnevom UTC; IP ne zapusti Edge-a.

Geolociranje na Edge-u

Vsi geografski podatki (country, region, city) izvirajo iz objekta cf ponudnika Cloudflare in temeljijo na zbirki podatkov Cloudflare Geo-IP. Zunanje storitve Geo-IP se ne kličejo — razreševanje poteka v istem Workerju, ki izvede preusmeritev.

To ima tri posledice:

1. Nizka zakasnitev (latency) — brez dodatnega skoka (hop), brez poizvedbe DNS pri zunanjem ponudniku.
2. Varstvo podatkov — IP-naslov ne zapusti omrežja Cloudflare in se nikoli ne posreduje tretjim osebam.
3. Omejena natančnost — podatek city ni vedno na voljo (npr. pri uporabi VPN-jev, mobilnih operaterjev ali v manjših regijah). Pričakujte vrednosti null in jih upoštevajte pri oblikovanju svojih nadzornih plošč.

---

Pridobivanje analitike skeniranj

GET /v1/codes/:id/scans

Vrne agregirano analitiko za posamezno QR-kodo za izbrano časovno obdobje.

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

Parametri poizvedbe (Query Parameters):

Parameter	Vrsta	Privzeto	Opis
days	celo število (integer)	30	Časovno obdobje v dneh (1–365)

Odgovor (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" }
}

Polja v odgovoru:

Polje	Opis
total_scans	Skupno število skeniranj kode v celotnem obdobju (neodvisno od časovnega okna days)
period_scans	Vsota skeniranj v izbranem časovnem oknu
scans_by_day	Dnevne skupine (buckets), naraščajoče po datumu, prazni dnevi so izpuščeni
top_countries	Top 8 držav v časovnem oknu, padajoče
top_devices	Top 5 vrst naprav (mobile, tablet, desktop)
top_os	Top 5 operacijskih sistemov

Note

API za agregacijo ne vrača posameznih zapisov o skeniranju — niti prek straničenja s kazalcem (cursor pagination). Za surove tokove dogodkov (event streams) raje uporabite spletne kavlje (webhooks) (glejte spodaj). Če potrebujete zgodovinske surove podatke, jih izvozite prek GET /v1/account/export.

Agregacija za več kod

Skupne vrednosti na ravni delovnega prostora (npr. skeniranja na mesec za vse kode) so na voljo prek GET /v1/workspaces/:id v polju scans_this_month. Za analizo več kod hkrati priporočamo uporabo nadzorne plošče ali redni izvoz.

---

Spremljanje v realnem času prek spletnih kavljev (Webhooks)

Če želite obdelati dogodke skeniranja takoj, ko se zgodijo — na primer za nadzorne plošče v živo, sledenje sledem (lead tracking) ali integracije CRM — se naročite na dogodek 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"
  }
}

Celotna dokumentacija o preverjanju podpisov, logiki ponovnih poskusov (retry logic) in dnevnikih dostave (delivery logs) je na voljo v API → Webhooks.

---

GDPR & varstvo podatkov

Zapisi ne shranjujejo izvornega IP-ja. Edge Worker izpelje psevdonim HMAC-SHA-256 iz dolgotrajne skrivnosti, namena in dneva UTC; psevdonim ostaja osebni podatek.

• Brez skrivnosti vrednost ni neposredno obrnljiva, imetnik skrivnosti pa lahko znane IP-kandidate za dan UTC ponovno izračuna.
• Namen in dan UTC sta del izpeljave, zato hashi istega skenerja v različnih dneh niso neposredno primerljivi.
• Izvorni IP ne doseže D1, KV ali R2.

V večdnevnih oknih je unique_scanners metrika Dnevi skeniranja in ne oseb: isti skener prejme ločen psevdonim za vsak dan UTC.

Hramba podatkov (Retention) je odvisna od paketa:

Paket	Hramba
Free	7 dni
Pro	90 dni
Business / Agency	1 leto
Enterprise	Po meri (SLA)

Dnevno opravilo Cron (purgeOldScans) samodejno odstrani starejše zapise — to ne vpliva na vrednost total_scans na objektu kode.

Podrobnosti o GDPR & API za informacije Zgoščevanje IP-naslovov, DPA s podizvajalci, izvoz podatkov in pravica do pozabe.

---

Najboljše prakse

• Frekvenca poizvedovanja (Polling): API za agregacijo je učinkovit, vendar ni namenjen poizvedovanju vsako sekundo. Za posodobitve v živo vedno raje uporabite spletne kavlje (webhooks), API pa uporabljajte le za naknadno polnjenje (backfills) ali nadzorne plošče.
• Predpomnjenje (Caching): Odgovor vsebuje časovne vrste — pri velikih časovnih oknih (days=365) lahko velikost tovora (payload) doseže več KB. Predpomnite podatke na strani odjemalca s kratkim časom veljavnosti (TTL, npr. 60 s).
• Omejitve Top-N: Polja top_countries, top_devices in top_os so na strežniški strani omejena na 8 oziroma 5 vnosov. Za globlje analize izvozite surove podatke.
• Dopuščanje vrednosti null: Polja country, region, city, referer in language so lahko null. V svojih analizah jih obravnavajte kot »Neznano«.