Traċċar ta' Scans u Analitika

Ħarsa Ġenerali

Kull scan ta’ QR code dinamiku joħloq scan-record fil-workspace tiegħek. Il-ġbir isir kompletament fuq il-Cloudflare-Edge — mingħajr servizzi ta’ traċċar esterni, mingħajr cookies, u mingħajr ma l-IP oriġinali qatt jilħaq id-database tiegħek.

Tliet modi kif tikkonsma d-data tal-iscans:

API tal-Aggregazzjoni

GET /v1/codes/:id/scans — Serje ta’ ħin + L-aqwa pajjiżi/apparat/OS għal oġġett ta’ kodiċi wieħed.

Webhooks (Ħin Real)

Avveniment qr.scanned għal kull scan, iffirmat b’HMAC-SHA256. Ara Webhooks.

Dashboard

Viżwalizzazzjoni fid-dashboard ta’ qr3.app — m’hemmx bżonn ta’ sejħa API.

---

Liema data tinġabar

Għal kull scan, jinħoloq record fit-tabella scans:

Qasam	Sors	Eżempju
id	UUID ġġenerata mis-server	scn_d1f8…
code_id	ID tal-kodiċi tal-QR code skennjat	qr_a1b2c3d4
workspace_id	Workspace tal-kodiċi	ws_xxx
country	Cloudflare cf.country	AT
region	Cloudflare cf.region	Vienna
city	Cloudflare cf.city	Wien
device_type	Parsing tal-User-Agent	mobile, tablet, desktop
os	Parsing tal-User-Agent	iOS, Android, macOS, Windows
browser	Parsing tal-User-Agent	Safari, Chrome, Firefox
referer	Header HTTP Referer	https://example.com/landing
language	Header Accept-Language (l-ewwel lingwa)	de
redirected_to	Destinazzjoni attwali tar-redirect	https://example.com
ip_hash	SHA-256(IP + salt ta’ kuljum) — mhux riversibbli	8f3a…
scanned_at	Timestamp ISO-8601	2026-05-12T14:32:11.000Z

Tip

Minimizzazzjoni tad-Data by Design: Ma jiġu ssettjati l-ebda cookies, l-ebda fingerprinting, u l-ebda pixel ta’ traċċar estern ma jiġi mgħobbi. L-indirizz IP oriġinali jiġi kkonvertit immedjatament fl-Edge-Worker f’hash SHA-256 u qatt ma jħalli l-Edge.

Ġeolokalizzazzjoni fuq l-Edge

Id-data ġeografika kollha (country, region, city) tiġi mill-oġġett cf ta’ Cloudflare u hija bbażata fuq id-database Geo-IP ta’ Cloudflare. Ma jiġu mitluba l-ebda servizzi esterni ta’ Geo-IP — ir-riżoluzzjoni sseħħ fl-istess Worker li jwettaq ukoll ir-redirect.

Dan għandu tliet konsegwenzi:

1. Latenza baxxa — l-ebda hop addizzjonali, l-ebda DNS lookup għal fornitur estern.
2. Protezzjoni tad-data — l-indirizz IP ma jħallix lil Cloudflare u qatt ma jiġi mgħoddi lil partijiet terzi.
3. Granularità limitata — city mhux dejjem tkun disponibbli (eż. f’każ ta’ VPNs, operaturi tal-mowbajl jew reġjuni żgħar). Stenna valuri null u kkalkulahom fid-dashboards tiegħek.

---

Kif Tistaqsi għall-Analitika tal-Iscans

GET /v1/codes/:id/scans

Tipprovdi analitika aggregata għal QR code wieħed fuq perjodu ta’ żmien magħżul.

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 tal-Query:

Parametru	Tip	Default	Deskrizzjoni
days	integer	30	Perjodu f’jiem (1–365)

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

Oqsma tar-Rispons:

Qasam	Deskrizzjoni
total_scans	Total tal-iscans tul il-ħajja tal-kodiċi (irrispettivament mit-tieqa ta’ days)
period_scans	Total tal-iscans fit-tieqa ta’ żmien magħżula
scans_by_day	Buckets ta’ kuljum, f’ordni axxendenti skont id-data, jiem vojta jiġu ommessi
top_countries	L-aqwa 8 pajjiżi fit-tieqa ta’ żmien, f’ordni dixxendenti
top_devices	L-aqwa 5 tipi ta’ apparat (mobile, tablet, desktop)
top_os	L-aqwa 5 sistemi operattivi

Note

L-API tal-aggregazzjoni ma tipprovdix records ta’ scans individwali — lanqas permezz ta’ cursor-pagination. Għal streams ta’ avvenimenti mhux ipproċessati (raw event streams), uża webhooks minflok (ara hawn taħt). Jekk għandek bżonn data storika mhux ipproċessata, esportaha permezz ta’ GET /v1/account/export.

Aggregazzjoni fuq Diversi Kodiċijiet

Totali fuq il-livell tal-workspace kollu (eż. scans kull xahar fuq il-kodiċijiet kollha) huma disponibbli permezz ta’ GET /v1/workspaces/:id bħala l-qasam scans_this_month. Għal analiżi bejn kodiċijiet differenti (cross-code), nirrakkomandaw id-dashboard jew esportazzjoni perjodika.

---

Konsum f’Ħin Real permezz ta’ Webhooks

Jekk trid tipproċessa l-avvenimenti tal-iscans malli jseħħu — bħal għal dashboards diretti, traċċar ta’ leads jew integrazzjonijiet tas-CRM — abbona għall-avveniment 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"
  }
}

Dokumentazzjoni sħiħa dwar il-verifika tal-firem, il-loġika ta’ attentat mill-ġdid (retry) u r-reġistri tal-kunsinna (delivery logs) tinsab f’ API → Webhooks.

---

GDPR & Protezzjoni tad-Data

Ir-records tal-iscans ma fihomx indirizzi IP personali. L-IP oriġinali jiġi sostitwit fl-Edge-Worker b’funzjoni hash kriptografika (SHA-256) b’salt li jdur kuljum. Dan ifisser:

• L-ebda re-identifikazzjoni anke jekk l-algoritmu jkun magħruf
• L-ebda korrelazzjoni bejn jiem differenti tal-istess viżitatur
• L-IP oriġinali qatt ma jilħaq id-database D1

Iż-żamma tad-data (retention) tiddependi fuq il-pjan:

Pjan	Żamma
Free	7 ijiem
Pro	90 jum
Business / Agency	sena
Enterprise	Custom (SLA)

Cron-job li jaħdem kuljum (purgeOldScans) ineħħi records eqdem awtomatikament — total_scans fuq l-oġġett tal-kodiċi jibqa’ mhux affettwat minn dan.

Dettalji tal-GDPR u API tal-Informazzjoni Hashing tal-IP, DPA tas-sub-proċessuri, esportazzjoni tad-data u d-dritt li tkun minsi.

---

L-Aħjar Prattiki

• Frekwenza tal-Polling: L-API tal-aggregazzjoni hija rħisa, iżda mhix iddisinjata biex tintuża kull sekonda. Għal aġġornamenti diretti, dejjem ippreferi webhooks u uża l-API biss għal backfills / dashboards.
• Caching: Ir-rispons fih serje ta’ ħin — f’każ ta’ twieqi kbar (days=365), il-payload jista’ jsir ta’ diversi KB. Agħmel cache fuq in-naħa tal-klijent b’TTL qasir (eż. 60 s).
• Limiti Top-N: top_countries, top_devices, top_os huma limitati fuq in-naħa tas-server għal 8 jew 5 daħliet rispettivament. Għal analiżi aktar profonda, esporta d-data mhux ipproċessata.
• Tollera valuri null: country, region, city, referer, language jistgħu jkunu null. Ittratta dan fl-analiżi tiegħek bħala “Mhux magħruf”.