Sledenje skeniranjem in analitika

Pregled

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

Trije načini za uporabo podatkov o skeniranju:

Aggregations-API

GET /v1/codes/:id/scans — časovne vrste + najboljše države/naprave/operacijski sistemi za posamezen objekt kode.

Webhooks (Echtzeit)

qr.scanned-dogodek na sken, podpisan s HMAC-SHA256. Glej spletne kavlje.

Dashboard

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	SHA-256(IP + dnevna sol/salt) — nepovratno	8f3a…
scanned_at	ISO-8601 časovni žig	2026-05-12T14:32:11.000Z

Tip

Minimizacija podatkov s snovanjem (by Design): Piškotki se ne nastavljajo, prstni odtisi se ne zbirajo, zunanje slikovne pike za sledenje se ne nalagajo. Izvorni IP-naslov se v Edge-Workerju takoj pretvori v dnevno rotirajočo zgoščeno vrednost SHA-256 in nikoli ne zapusti Edge-a.

Geolokalizacija na Edge

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 poizvedujejo — razreševanje poteka v istem Workerju, ki izvede tudi preusmeritev.

To ima tri posledice:

1. Nizka zakasnitev — brez dodatnega skoka (hop), brez poizvedbe DNS pri zunanjem ponudniku.
2. Varstvo podatkov — IP-naslov ne zapusti Cloudflare-a in se nikoli ne posreduje tretjim osebam.
3. Omejena natančnost — city ni vedno na voljo (npr. pri VPN-jih, mobilnih operaterjih ali manjših regijah). Pričakuj vrednosti null in jih upoštevaj pri oblikovanju svojih nadzornih plošč.

---

Poizvedovanje po analitiki 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 skenov kode v celotnem obdobju delovanja (neodvisno od časovnega okna days)
period_scans	Vsota skenov v izbranem časovnem oknu
scans_by_day	Dnevne skupine (buckets), naraščajoče po datumu, prazni dnevi so izpuščeni
top_countries	Najboljših 8 držav v časovnem oknu, padajoče
top_devices	Najboljših 5 vrst naprav (mobile, tablet, desktop)
top_os	Najboljših 5 operacijskih sistemov

Note

Agregacijski API ne vrača posameznih zapisov o skeniranju — niti prek straničenja s kazalcem (cursor pagination). Za surove tokove dogodkov raje uporabi spletne kavlje (webhooks) (glej spodaj). Če potrebuješ zgodovinske surove podatke, jih izvozi prek GET /v1/account/export.

Agregacija za več kod

Vsote na ravni delovnega prostora (npr. skeni na mesec za vse kode) so na voljo prek GET /v1/workspaces/:id v polju scans_this_month. Za analize med različnimi kodami priporočamo uporabo nadzorne plošče ali občasen izvoz.

---

Spremljanje v realnem času prek spletnih kavljev (Webhooks)

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

Tovor (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 in dnevnikih dostave je na voljo v API → Spletni kavlji (Webhooks).

---

Splošna uredba o varstvu podatkov (GDPR) in zasebnost

Zapisi o skeniranju ne vsebujejo osebnih IP-naslovov. Prvotni IP-naslov se v Edge-Workerju nadomesti s kriptografsko zgoščevalno funkcijo (SHA-256) z dnevno rotirajočo soljo (salt). To pomeni:

• Ponovna identifikacija ni mogoča, tudi če je algoritem znan
• Ni mogoča korelacija istega obiskovalca med različnimi dnevi
• Izvorni IP-naslov nikoli ne doseže podatkovne baze D1

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 v objektu kode.

DSGVO-Details & Auskunfts-API IP-Hashing, Sub-Processor-DPA, Datenexport und Recht auf Vergessenwerden.

---

Najboljše prakse

• Pogostost poizvedovanja (Polling): Agregacijski API je učinkovit, vendar ni namenjen poizvedovanju vsako sekundo. Za posodobitve v živo vedno raje uporabi spletne kavlje (webhooks), API pa uporabljaj le za naknadno polnjenje podatkov (backfills) ali nadzorne plošče.
• Predpomnjenje (Caching): Odgovor vsebuje časovne vrste — pri velikih časovnih oknih (days=365) lahko tovor (payload) obsega več KB. Predpomni podatke na strani odjemalca s kratkim časom veljavnosti (TTL, npr. 60 s).
• Omejitve Top-N: top_countries, top_devices in top_os so na strežniku omejeni na 8 oziroma 5 vnosov. Za globlje analize izvozi surove podatke.
• Dopuščanje vrednosti null: country, region, city, referer in language so lahko null. V svoji analizi jih obravnavaj kot »neznano«.