Praćenje skeniranja i analitika

Pregled

Svako skeniranje dinamičkog QR koda stvara zapis skeniranja (Scan-Record) u tvom radnom prostoru (Workspace). Prikupljanje se odvija u potpunosti na Cloudflare Edgeu — bez vanjskih usluga praćenja, bez kolačića i bez da izvorna IP adresa ikada stigne do tvoje baze podataka.

Tri načina za korištenje podataka o skeniranju:

Agregacijski API

GET /v1/codes/:id/scans — vremenske serije + top države/uređaji/OS za pojedinačni objekt koda.

Webhooks (stvarno vrijeme)

qr.scanned događaj po skeniranju, potpisan s HMAC-SHA256. Vidi Webhooks.

Nadzorna ploča

Vizualizacija na qr3.app nadzornoj ploči — nije potreban API poziv.

---

Koji se podaci prikupljaju

Za svako skeniranje stvara se zapis u tablici scans:

Polje	Izvor	Primjer
id	UUID generiran na poslužitelju	scn_d1f8…
code_id	ID skeniranog QR koda	qr_a1b2c3d4
workspace_id	Workspace koda	ws_xxx
country	Cloudflare cf.country	AT
region	Cloudflare cf.region	Vienna
city	Cloudflare cf.city	Wien
device_type	User-Agent parsiranje	mobile, tablet, desktop
os	User-Agent parsiranje	iOS, Android, macOS, Windows
browser	User-Agent parsiranje	Safari, Chrome, Firefox
referer	HTTP Referer zaglavlje	https://example.com/landing
language	Accept-Language zaglavlje (prvi jezik)	de
redirected_to	Stvarno odredište preusmjeravanja	https://example.com
ip_hash	SHA-256(IP + dnevni salt) — nepovratno	8f3a…
scanned_at	ISO-8601 vremenska oznaka	2026-05-12T14:32:11.000Z

Tip

Minimizacija podataka po dizajnu: Ne postavljaju se kolačići, nema otisaka prstiju (fingerprinting), niti se učitavaju vanjski pikseli za praćenje. Izvorna IP adresa se u Edge Workeru odmah pretvara u SHA-256 hash koji se svakodnevno mijenja (rotirajući salt) i nikada ne napušta Edge.

Geolociranje na Edgeu

Svi geografski podaci (country, region, city) dolaze iz cf objekta Cloudflarea i temelju se na Cloudflare Geo-IP bazi podataka. Ne upućuju se zahtjevi vanjskim Geo-IP uslugama — razlučivanje se odvija u istom Workeru koji izvršava i preusmjeravanje.

To ima tri posljedice:

1. Niska latencija — nema dodatnog skoka (hop), nema DNS pretraživanja prema vanjskom pružatelju usluga.
2. Zaštita podataka — IP adresa ne napušta Cloudflare i nikada se ne prosljeđuje trećim stranama.
3. Ograničena granularnost — city nije uvijek dostupan (npr. kod VPN-ova, mobilnih operatera ili malih regija). Očekuj null vrijednosti i predvidi ih u svojim nadzornim pločama.

---

Dohvaćanje analitike skeniranja

GET /v1/codes/:id/scans

Pruža agregiranu analitiku za pojedinačni QR kod tijekom odabranog vremenskog razdoblja.

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 upita:

Parametar	Tip	Zadano	Opis
days	integer	30	Razdoblje u danima (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 odgovora:

Polje	Opis
total_scans	Ukupan broj skeniranja koda od početka (neovisno o vremenskom prozoru days)
period_scans	Zbroj skeniranja u odabranom vremenskom prozoru
scans_by_day	Dnevne grupe, uzlazno po datumu, prazni dani se izostavljaju
top_countries	Top 8 država u vremenskom prozoru, silazno
top_devices	Top 5 vrsta uređaja (mobile, tablet, desktop)
top_os	Top 5 operacijskih sustava

Note

Agregacijski API ne pruža pojedinačne zapise skeniranja — čak ni putem paginacije kursorom. Za sirove tokove događaja (event streams) radije koristi webhooke (vidi u nastavku). Ako trebaš povijesne sirove podatke, izvezi ih putem GET /v1/account/export.

Agregacija kroz više kodova

Ukupni iznosi na razini radnog prostora (npr. skeniranja mjesečno za sve kodove) dostupni su putem GET /v1/workspaces/:id u polju scans_this_month. Za analize kroz više kodova preporučujemo nadzornu ploču ili periodički izvoz.

---

Praćenje u stvarnom vremenu putem webhooka

Ako želiš obrađivati događaje skeniranja čim se dogode — primjerice za nadzorne ploče uživo, praćenje potencijalnih klijenata (lead tracking) ili CRM integracije — pretplati se na događaj 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"
  }
}

Potpuna dokumentacija o verifikaciji potpisa, logici ponovnog pokušaja (retry) i zapisima isporuke (delivery logs) nalazi se u API → Webhooks.

---

GDPR i zaštita podataka

Zapisi skeniranja ne sadrže osobne IP adrese. Izvorna IP adresa se u Edge Workeru zamjenjuje kriptografskom hash funkcijom (SHA-256) s dnevno rotirajućim saltom. To znači:

• Nema ponovne identifikacije čak ni uz poznavanje algoritma
• Nema korelacije istog posjetitelja kroz više dana
• Izvorna IP adresa nikada ne stiže do D1 baze podataka

Zadržavanje podataka (Retention) ovisi o paketu:

Paket	Zadržavanje
Free	7 dana
Pro	90 dana
Business / Agency	1 godina
Enterprise	Prilagođeno (SLA)

Dnevni cron posao (purgeOldScans) automatski uklanja starije zapise — to ne utječe na vrijednost total_scans na objektu koda.

GDPR detalji i API za informacije IP hashing, DPA s podizvršiteljima obrade, izvoz podataka i pravo na zaborav.

---

Najbolje prakse

• Učestalost prozivanja (Polling): Agregacijski API je učinkovit, ali nije namijenjen za sekvencijalno pozivanje svake sekunde. Za ažuriranja uživo uvijek daj prednost webhookovima, a API koristi samo za naknadno popunjavanje (backfill) ili nadzorne ploče.
• Predmemoriranje (Caching): Odgovor sadrži vremenske serije — kod velikih prozora (days=365) payload može biti velik nekoliko KB. Predmemoriraj na strani klijenta s kratkim vremenom života (TTL, npr. 60 s).
• Ograničenja za Top-N: top_countries, top_devices i top_os ograničeni su na strani poslužitelja na 8 odnosno 5 unosa. Za dublju analizu izvezi sirove podatke.
• Toleriranje null vrijednosti: country, region, city, referer i language mogu biti null. U svojoj evaluaciji tretiraj to kao „Nepoznato“.