Skenavimo sekimas ir analitika

Apžvalga

Kiekvienas dinaminio QR kodo nuskaitymas sukuria skenavimo įrašą (Scan-Record) jūsų 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ų jūsų 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`

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:

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

Skenavimo analitikos užklausa

`GET /v1/codes/:id/scans`

Pateikia agreguotą vieno QR kodo analitiką pasirinktam laikotarpiui.

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

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

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

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

Planas	Saugojimo laikotarpis
Visi planai	90 dienų

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“.