Skenēšanas izsekošana un analītika

Pārskats

Katrs dinamiskā QR koda skenējums izveido skenēšanas ierakstu (Scan-Record) tavā darba vidē (Workspace). Datu apkopošana pilnībā notiek Cloudflare-Edge — bez ārējiem izsekošanas pakalpojumiem, bez sīkfailiem (cookies) un bez oriģinālās IP adreses nonākšanas tavā datubāzē.

Trīs veidi, kā piekļūt skenēšanas datiem:

Agregācijas API

GET /v1/codes/:id/scans — laika rindas + populārākās valstis/ierīces/OS vienam koda objektam.

Webhooks (reāllaikā)

qr.scanned notikums katram skenējumam, parakstīts ar HMAC-SHA256. Skatiet Webhooks.

Vadības panelis

Vizualizācija qr3.app vadības panelī — nav nepieciešams API izsaukums.

---

Kādi dati tiek apkopoti

Katram skenējumam tiek izveidots ieraksts tabulā scans:

Lauks	Avots	Piemērs
id	Servera ģenerēts UUID	scn_d1f8…
code_id	Skenētā QR koda ID	qr_a1b2c3d4
workspace_id	Koda darba vide (Workspace)	ws_xxx
country	Cloudflare cf.country	AT
region	Cloudflare cf.region	Vienna
city	Cloudflare cf.city	Wien
device_type	User-Agent parsēšana	mobile, tablet, desktop
os	User-Agent parsēšana	iOS, Android, macOS, Windows
browser	User-Agent parsēšana	Safari, Chrome, Firefox
referer	HTTP Referer galvene	https://example.com/landing
language	Accept-Language galvene (pirmā valoda)	de
redirected_to	Faktiskais novirzīšanas mērķis	https://example.com
ip_hash	SHA-256(IP + ikdienas sāls) — neatgriezenisks	8f3a…
scanned_at	ISO-8601 laika zīmogs	2026-05-12T14:32:11.000Z

Tip

Datu minimizēšana pēc noklusējuma (by Design): netiek iestatīti sīkfaili, netiek veikta pirkstu nospiedumu noņemšana (fingerprinting), netiek ielādēti ārējie izsekošanas pikseļi. Oriģinālā IP adrese Edge-Worker vidē nekavējoties tiek pārveidota par katru dienu rotējošu SHA-256 jaucējkodu (hash) un nekad nepamet Edge.

Ģeolokalizācija Edge līmenī

Visi ģeogrāfiskie dati (country, region, city) nāk no Cloudflare cf objekta un ir balstīti uz Cloudflare Geo-IP datubāzi. Ārējie Geo-IP pakalpojumi netiek pieprasīti — noteikšana notiek tajā pašā Worker, kas veic novirzīšanu.

Tam ir trīs sekas:

1. Zems latentums — nav papildu pārejas (hop), nav DNS vaicājuma ārējam pakalpojumu sniedzējam.
2. Datu aizsardzība — IP adrese nepamet Cloudflare un nekad netiek nodota trešajām pusēm.
3. Ierobežota granularitāte — city ne vienmēr ir pieejama (piemēram, izmantojot VPN, mobilo sakaru operatorus vai mazos reģionos). Rēķinieties ar null vērtībām un iekļaujiet tās savos vadības paneļos.

---

Skenēšanas analītikas pieprasīšana

GET /v1/codes/:id/scans

Nodrošina apkopotu analītiku vienam QR kodam izvēlētajā laika periodā.

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

Vaicājuma parametri (Query Parameters):

Parametrs	Tips	Noklusējums	Apraksts
days	vesels skaitlis	30	Laika periods dienās (1–365)

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

Atbildes lauki:

Lauks	Apraksts
total_scans	Kopējais skenējumu skaits koda darbības laikā (neatkarīgi no days loga)
period_scans	Skenējumu skaits izvēlētajā laika logā
scans_by_day	Dienu grupas, augošā secībā pēc datuma, tukšās dienas tiek izlaistas
top_countries	Top 8 valstis laika logā, dilstošā secībā
top_devices	Top 5 ierīču tipi (mobile, tablet, desktop)
top_os	Top 5 operētājsistēmas

Note

Agregācijas API nenodrošina atsevišķus skenēšanas ierakstus — pat ne ar kursoru pagināciju (Cursor-Pagination). Neapstrādātām notikumu plūsmām izmantojiet Webhooks (skatīt zemāk). Ja jums ir nepieciešami vēsturiskie neapstrādātie dati, eksportējiet tos, izmantojot GET /v1/account/export.

Agregācija vairākiem kodiem

Darba vides mēroga kopsummas (piemēram, skenējumi mēnesī visiem kodiem) ir pieejamas, izmantojot GET /v1/workspaces/:id laukā scans_this_month. Starpkodu analīzei mēs iesakām izmantot vadības paneli vai periodisku eksportēšanu.

---

Reāllaika patēriņš, izmantojot Webhooks

Ja vēlaties apstrādāt skenēšanas notikumus tiklīdz tie notiek — piemēram, tiešsaistes vadības paneļiem, kontaktu izsekošanai (Lead-Tracking) vai CRM integrācijām —, abonējiet qr.scanned notikumu:

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

Datu kopa (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"
  }
}

Pilna dokumentācija par paraksta verifikāciju, atkārtošanas loģiku (Retry-Logik) un piegādes žurnāliem (Delivery-Logs) ir pieejama sadaļā API → Webhooks.

---

VDAR un datu aizsardzība

Skenēšanas ieraksti nesatur personas datus saturošas IP adreses. Sākotnējā IP adrese Edge-Worker vidē tiek aizstāta ar kriptogrāfisku jaucējfunkciju (SHA-256) ar katru dienu rotējošu sāli (salt). Tas nozīmē:

• Nav iespējama atkārtota identifikācija, pat zinot algoritmu
• Nav iespējama viena un tā paša apmeklētāja korelācija starp dažādām dienām
• Oriģinālā IP adrese nekad nenonāk D1 datubāzē

Datu glabāšanas ilgums (Retention) ir atkarīgs no plāna:

Plāns	Uzglabāšana
Free	7 dienas
Pro	90 dienas
Business / Agency	1 gads
Enterprise	Pielāgots (SLA)

Katru dienu palaists Cron uzdevums (purgeOldScans) automātiski dzēš vecākus ierakstus — tas neietekmē total_scans vērtību koda objektā.

VDAR informācija un informācijas pieprasīšanas API IP jaukšana, apakšapstrādātāju DPA, datu eksports un tiesības tikt aizmirstam.

---

Labākā prakse

• Aptaujas biežums (Polling-Frequenz): Agregācijas API ir efektīva, taču tā nav paredzēta vaicājumiem katru sekundi. Tiešsaistes atjauninājumiem vienmēr dodiet priekšroku Webhooks un izmantojiet API tikai datu papildināšanai (Backfills) vai vadības paneļiem.
• Kešatmiņa (Caching): Atbilde satur laika rindas — lielu laika logu gadījumā (days=365) datu kopa (payload) var sasniegt vairākus KB. Veiciet kešatmiņu klienta pusē ar īsu TTL (piemēram, 60 s).
• Top-N ierobežojumi: top_countries, top_devices, top_os servera pusē ir ierobežoti attiecīgi līdz 8 vai 5 ierakstiem. Padziļinātai analīzei eksportējiet neapstrādātos datus.
• Pieļaujiet null vērtības: country, region, city, referer, language var būt null. Savā analīzē apstrādājiet tās kā “Nezināms”.