Skenavimo sekimas ir analitika

Apžvalga

Kiekvienas dinaminio QR kodo nuskaitymas sukuria skenavimo įrašą (Scan-Record) tavo Workspace. Duomenys renkami visiškai Cloudflare-Edge aplinkoje — be išorinių sekimo paslaugų, be slapukų ir be to, kad originalus IP adresas kada nors pasiektų tavo duomenų bazę.

Trys būdai gauti skenavimo duomenis:

Agregavimo API

GET /v1/codes/:id/scans — laiko eilutės + populiariausios šalys / įrenginiai / OS vienam kodo objektui.

Webhooks (realiuoju laiku)

qr.scanned įvykis kiekvienam skenavimui, pasirašytas HMAC-SHA256. Žr. Webhooks.

Valdymo skydelis

Vizualizacija qr3.app valdymo skydelyje — nereikia jokių API iškvietimų.

---

Kokie duomenys renkami

Kiekvienam skenavimui sukuriama eilutė lentelėje scans:

Laukas	Šaltinis	Pavyzdys
id	Serverio sugeneruotas UUID	scn_d1f8…
code_id	Nuskaityto QR kodo ID	qr_a1b2c3d4
workspace_id	Kodo Workspace	ws_xxx
country	Cloudflare cf.country	AT
region	Cloudflare cf.region	Vienna
city	Cloudflare cf.city	Wien
device_type	User-Agent analizė	mobile, tablet, desktop
os	User-Agent analizė	iOS, Android, macOS, Windows
browser	User-Agent analizė	Safari, Chrome, Firefox
referer	HTTP Referer antraštė	https://example.com/landing
language	Accept-Language antraštė (pirmoji kalba)	de
redirected_to	Faktinis nukreipimo tikslas	https://example.com
ip_hash	Dienos HMAC-SHA-256 pseudonimas (ilgalaikė paslaptis + paskirtis + UTC diena + IP)	8f3a…
scanned_at	ISO-8601 laiko žyma	2026-05-12T14:32:11.000Z

Tip

Duomenų minimizavimas pagal projektą: nenaudojami slapukai, netaikomas fingerprinting ir neįkeliami išoriniai sekimo pikseliai. Edge Worker iškart pseudonimizuoja originalų IP HMAC-SHA-256, ilgalaike paslaptimi, paskirtimi ir UTC diena; IP niekada nepalieka Edge aplinkos.

Geo-lokalizacija Edge aplinkoje

Visi geo-duomenys (country, region, city) gaunami iš Cloudflare cf objekto ir yra pagrįsti Cloudflare Geo-IP duomenų baze. Išorinės Geo-IP paslaugos neužklausia — vietos nustatymas vyksta tame pačiame Worker, kuris atlieka ir nukreipimą (redirect).

Tai turi tris pasekmes:

1. Maža delsa (latency) — jokių papildomų tinklo žingsnių (hop), jokios DNS užklausos išoriniam teikėjui.
2. Duomenų apsauga — IP adresas nepalieka Cloudflare aplinkos ir niekada neperduodamas trečiosioms šalims.
3. Ribotas tikslumas — city (miestas) ne visada prieinamas (pvz., naudojant VPN, mobiliojo ryšio operatorius ar mažesniuose regionuose). Tikėkis null reikšmių ir numatyk jas savo valdymo skydeliuose.

---

Skenavimo analitikos užklausa

GET /v1/codes/:id/scans

Pateikia agreguotą vieno QR kodo analitiką pasirinktam laikotarpiui.

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

Užklausos parametrai (Query parameters):

Parametras	Tipas	Numatytasis	Aprašymas
days	integer	30	Laikotarpis dienomis (1–365)

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

Atsakymo laukai:

Laukas	Aprašymas
total_scans	Bendras kodo nuskaitymų skaičius per visą laiką (nepriklausomai nuo days filtro)
period_scans	Skenavimų suma pasirinktu laikotarpiu
scans_by_day	Dienos grupės, didėjančia tvarka pagal datą, tuščios dienos praleidžiamos
top_countries	Populiariausios 8 šalys pasirinktu laikotarpiu, mažėjančia tvarka
top_devices	Populiariausi 5 įrenginių tipai (mobile, tablet, desktop)
top_os	Populiariausios 5 operacinės sistemos

Note

Agregavimo API neteikia atskirų skenavimo įrašų — net ir naudojant puslapiavimą (Cursor-Pagination). Norėdami gauti neapdorotų įvykių srautus (raw event streams), naudokite Webhooks (žr. žemiau). Jei jums reikia istorinių neapdorotų duomenų, eksportuokite juos per GET /v1/account/export.

Agregavimas keliems kodams

Workspace lygio sumos (pvz., skenavimai per mėnesį visiems kodams) yra prieinamos per GET /v1/workspaces/:id lauke scans_this_month. Kelių kodų analizei (cross-code analysis) rekomenduojame naudoti valdymo skydelį arba periodinį eksportą.

---

Gavimo realiuoju laiku būdas per Webhooks

Jei norite apdoroti skenavimo įvykius iškart jiems įvykus — pavyzdžiui, tiesioginėms ataskaitoms, potencialių klientų sekimui (lead tracking) ar CRM integracijoms — užsiprenumeruokite qr.scanned įvykį:

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 (duomenų paketas):

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

Pilna dokumentacija apie parašo patvirtinimą (signature verification), pakartotinio bandymo logiką (retry logic) ir pristatymo žurnalus (delivery logs) pateikiama skyriuje API → Webhooks.

---

BDAR ir duomenų apsauga

Skenavimo įrašai nesaugo originalaus IP. Edge Worker išveda HMAC-SHA-256 pseudonimą iš ilgalaikės paslapties, paskirties ir UTC dienos; pseudonimas išlieka asmens duomenimis.

• Be paslapties reikšmė nėra tiesiogiai atkuriama, tačiau paslapties turėtojas gali UTC dienai perskaičiuoti žinomus IP kandidatus.
• Paskirtis ir UTC diena yra išvedimo dalis, todėl to paties skaitytuvo hashai skirtingomis dienomis nėra tiesiogiai palyginami.
• Originalus IP nepasiekia D1, KV ar R2.

Kelių dienų languose unique_scanners yra Skenavimo dienos metrika, o ne asmenų metrika: tas pats skaitytuvas kiekvienai UTC dienai gauna atskirą pseudonimą.

Duomenų saugojimas (Retention) priklauso nuo plano:

Planas	Saugojimo laikotarpis
Free	7 dienos
Pro	90 dienų
Business / Agency	1 metai
Enterprise	Pasirinktinis (SLA)

Kasdien veikianti periodinė užduotis (cron job) purgeOldScans automatiškai pašalina senesnius įrašus — kodo objekto total_scans reikšmė lieka nepakitusi.

BDAR informacija ir užklausų API IP maiša (hashing), sub-tvarkytojo DPA, duomenų eksportas ir teisė būti pamirštam.

---

Geriausios praktikos

• Užklausų dažnis (Polling frequency): Agregavimo API yra efektyvi, tačiau ji nėra skirta užklausoms kas sekundę. Tiesioginiams atnaujinimams visada teikite pirmenybę Webhooks, o API naudokite tik duomenų užpildymui (backfills) arba valdymo skydeliams.
• Talpinimas talpykloje (Caching): Atsakyme pateikiamos laiko eilutės — esant dideliems laikotarpiams (days=365), duomenų paketas (payload) gali siekti kelis KB. Naudokite talpinimą kliento pusėje su trumpu gyvavimo laiku (TTL, pvz., 60 s).
• Top-N ribojimai: top_countries, top_devices, top_os serverio pusėje yra ribojami atitinkamai iki 8 arba 5 įrašų. Gilesnei analizei eksportuokite neapdorotus duomenis.
• Toleruokite null reikšmes: country, region, city, referer, language gali būti null. Savo analizėje traktuokite tai kaip „Nežinoma“.