Skaneeringute jälgimine ja analüütika

Ülevaade

Iga dünaamilise QR-koodi skaneerimine loob sinu töölaual (Workspace) skaneerimiskirje (Scan-Record). Andmete kogumine toimub täielikult Cloudflare-Edge’is — ilma väliste jälgimisteenusteta, ilma küpsisteta ja ilma, et algne IP-aadress kunagi sinu andmebaasi jõuaks.

Kolm viisi skaneerimisandmete kasutamiseks:

Agregeerimise API

GET /v1/codes/:id/scans — aegread + parimad riigid/seadmed/operatsioonisüsteemid ühe koodiobjekti kohta.

Veebikonksud (reaalaeg)

qr.scanned-sündmus iga skaneeringu kohta, HMAC-SHA256 allkirjastatud. Vaata Webhooks.

Töölaud

Visualiseerimine qr3.app töölaual — API-päringut pole vaja.

---

Milliseid andmeid kogutakse

Iga skaneeringu kohta luuakse kirje tabelisse scans:

Väli	Allikas	Näide
id	Serveri loodud UUID	scn_d1f8…
code_id	Skaneeritud QR-koodi ID	qr_a1b2c3d4
workspace_id	Koodi Workspace	ws_xxx
country	Cloudflare cf.country	AT
region	Cloudflare cf.region	Vienna
city	Cloudflare cf.city	Wien
device_type	User-Agent’i parsimine	mobile, tablet, desktop
os	User-Agent’i parsimine	iOS, Android, macOS, Windows
browser	User-Agent’i parsimine	Safari, Chrome, Firefox
referer	HTTP Referer-päis	https://example.com/landing
language	Accept-Language-päis (esimene keel)	de
redirected_to	Tegelik ümbersuunamise sihtkoht	https://example.com
ip_hash	SHA-256(IP + igapäevane sool) — pöördumatu	8f3a…
scanned_at	ISO-8601 ajatempel	2026-05-12T14:32:11.000Z

Tip

Andmete minimeerimine disaini kaudu: Küpsiseid ei paigaldata, sõrmejälgi (fingerprinting) ei tuvastata, väliseid jälgimispiksleid ei laadita. Algne IP-aadress teisendatakse Edge-Workeris koheselt igapäevaselt vahetuvaks SHA-256 räsiks ja see ei lahku kunagi Edge’ist.

Geo-lokaliseerimine Edge’is

Kõik geoandmed (country, region, city) pärinevad Cloudflare’i cf-objektist ja põhinevad Cloudflare’i Geo-IP andmebaasil. Väliseid Geo-IP teenuseid ei pärita — tuvastamine toimub samas Workeris, mis teostab ka ümbersuunamise.

Sellel on kolm tagajärge:

1. Madal viivitus — puudub täiendav vahesamm (hop), puudub DNS-päring välisele teenusepakkujale.
2. Andmekaitse — IP-aadress ei lahku Cloudflare’ist ja seda ei edastata kunagi kolmandatele osapooltele.
3. Piiratud täpsus — city (linn) ei ole alati saadaval (nt VPN-ide, mobiilsideoperaatorite või väikeste piirkondade puhul). Arvesta null-väärtustega ja võta neid oma töölaudadel arvesse.

---

Skaneerimisanalüütika päringud

GET /v1/codes/:id/scans

Tagastab agregeeritud analüütika ühe QR-koodi kohta valitud ajavahemikus.

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

Päringu parameetrid:

Parameeter	Tüüp	Vaikimisi	Kirjeldus
days	integer	30	Ajavahemik päevades (1–365)

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

Vastuse väljad:

Väli	Kirjeldus
total_scans	Koodi eluaegne skaneeringute koguarv (sõltumata days-aknast)
period_scans	Skaneeringute koguarv valitud ajavahemikus
scans_by_day	Päevapõhised andmed, kuupäeva järgi kasvavas järjekorras, tühjad päevad jäetakse vahele
top_countries	Top 8 riiki valitud ajavahemikus, kahanevas järjekorras
top_devices	Top 5 seadmetüüpi (mobile, tablet, desktop)
top_os	Top 5 operatsioonisüsteemi

Note

Agregeerimise API ei tarni üksikuid skaneerimiskirjeid — isegi mitte kursori-põhise lehekülgede jaotuse (cursor pagination) kaudu. Toorandmete voogude jaoks kasuta selle asemel veebikonkse (vt allpool). Kui vajad ajaloolisi toorandmeid, ekspordi need päringuga GET /v1/account/export.

Agregeerimine mitme koodi vahel

Workspace’i-ülesed kogusummad (nt skaneeringud kuus kõigi koodide lõikes) on saadaval päringu GET /v1/workspaces/:id kaudu väljal scans_this_month. Koodidevaheliseks analüüsiks soovitame kasutada töölauda või perioodilist eksporti.

---

Reaalajas tarbimine veebikonksude kaudu

Kui soovid skaneerimissündmusi töödelda kohe, kui need toimuvad — näiteks reaalajas töölaudade, vihjete jälgimise (lead tracking) või CRM-integratsioonide jaoks — telli sündmus 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"
  }
}

Täielik dokumentatsioon allkirja verifitseerimise, korduskatsete loogika ja tarne logide kohta on saadaval jaotises API → Webhooks.

---

Isikuandmete kaitse üldmäärus (GDPR) & andmekaitse

Skaneerimiskirjed ei sisalda isikuandmeteks liigituvaid IP-aadresse. Algne IP-aadress asendatakse Edge-Workeris krüptograafilise räsifunktsiooniga (SHA-256), kasutades igapäevaselt vahetuvat soola (salt). See tähendab:

• Isiku tuvastamine ei ole võimalik isegi algoritmi teadmise korral
• Sama külastaja tegevust ei saa eri päevade vahel seostada
• Algne IP-aadress ei jõua kunagi D1 andmebaasi

Säilitusaeg (Retention) sõltub paketist:

Pakett	Säilitusaeg
Free	7 päeva
Pro	90 päeva
Business / Agency	1 aasta
Enterprise	Kohandatud (SLA)

Igapäevaselt käivitatav cron-töö (purgeOldScans) eemaldab vanemad kirjed automaatselt — koodiobjekti väli total_scans jääb sellest puutumata.

GDPR üksikasjad ja teabe API IP-räsimine, alamtöötleja DPA, andmete eksport ja õigus olla unustatud.

---

Parimad tavad

• Päringute sagedus (Polling): Agregeerimise API on ressursisäästlik, kuid pole mõeldud sekundipõhiseks päringute tegemiseks. Reaalajas uuenduste jaoks kasuta alati veebikonkse ja kasuta API-t ainult andmete tagantjärele täitmiseks või töölaudade jaoks.
• Puhverdamine (Caching): Vastus sisaldab aegridu — suurte ajavahemike puhul (days=365) võib andmemaht (payload) olla mitu kilobaiti. Puhverda andmeid kliendi poolel lühikese elueaga (TTL, nt 60 s).
• Top-N piirangud: top_countries, top_devices, top_os on serveri poolel piiratud vastavalt 8 või 5 kirjele. Põhjalikumaks analüüsiks ekspordi toorandmed.
• null-väärtuste lubamine: country, region, city, referer, language võivad olla null. Käsitle neid oma analüüsis kui “Tundmatu”.