Scan-követés és analitika

Übersicht

Egy dinamikus QR-kód minden egyes beolvasása létrehoz egy Scan-recordot a munkaterületeden (Workspace). A rögzítés teljes egészében a Cloudflare-Edge-en történik — külső követőszolgáltatások és cookie-k nélkül, anélkül, hogy az eredeti IP-cím valaha is elérné az adatbázisodat.

A beolvasási adatok felhasználásának három módja:

Aggregációs API

GET /v1/codes/:id/scans — Idősorok + leggyakoribb országok/eszközök/operációs rendszerek egyetlen kódobjektumhoz.

Webhookok (valós idejű)

qr.scanned esemény beolvasásonként, HMAC-SHA256 aláírással. Lásd: Webhookok.

Irányítópult (Dashboard)

Vizualizáció a qr3.app irányítópultján — nincs szükség API-hívásra.

---

Welche Daten werden erfasst

Beolvasásonként egy rekord jön létre a scans táblában:

Mező	Forrás	Példa
id	Szerver által generált UUID	scn_d1f8…
code_id	A beolvasott QR-kód kód-azonosítója	qr_a1b2c3d4
workspace_id	A kód munkaterülete (Workspace)	ws_xxx
country	Cloudflare cf.country	AT
region	Cloudflare cf.region	Vienna
city	Cloudflare cf.city	Wien
device_type	User-Agent elemzés	mobile, tablet, desktop
os	User-Agent elemzés	iOS, Android, macOS, Windows
browser	User-Agent elemzés	Safari, Chrome, Firefox
referer	HTTP Referer fejléc	https://example.com/landing
language	Accept-Language fejléc (első nyelv)	de
redirected_to	Tényleges átirányítási cél	https://example.com
ip_hash	SHA-256(IP + napi salt) — visszafejthetetlen	8f3a…
scanned_at	ISO-8601 időbélyeg	2026-05-12T14:32:11.000Z

Tip

Beépített adatminimalizálás (by Design): Nem használunk cookie-kat, nincs ujjlenyomat-vétel (fingerprinting), és nem töltünk be külső követőpixeleket. Az eredeti IP-címet az Edge-Worker azonnal egy naponta változó SHA-256 hash-sé alakítja, és az soha nem hagyja el az Edge-et.

Geo-Lokalisierung am Edge

Minden geo-adat (country, region, city) a Cloudflare cf objektumából származik, és a Cloudflare Geo-IP adatbázisán alapul. Nem kérdezünk le külső Geo-IP szolgáltatásokat — a feloldás ugyanabban a Workerben történik, amely az átirányítást (redirect) is végzi.

Ennek három következménye van:

1. Alacsony késleltetés — nincs plusz ugrás (hop), nincs DNS-lekérdezés külső szolgáltató felé.
2. Adatvédelem — az IP-cím nem hagyja el a Cloudflare-t, és soha nem kerül átadásra harmadik félnek.
3. Korlátozott részletesség — a city (település) nem mindig érhető el (pl. VPN-ek, mobilhálózatok vagy kis régiók esetén). Számíts null értékekre, és kalkuláld be őket az irányítópultjaidon.

---

Scan-Analytics abfragen

GET /v1/codes/:id/scans

Aggregált analitikai adatokat ad vissza egyetlen QR-kódhoz egy választható időszakra vonatkozóan.

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

Lekérdezési (Query) paraméterek:

Paraméter	Típus	Alapértelmezett	Leírás
days	integer	30	Időtartam napokban (1–365)

Válasz (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" }
}

Válaszmezők:

Mező	Leírás
total_scans	A kód összes élettartam-beolvasása (függetlenül a days időablaktól)
period_scans	Beolvasások összege a választott időablakban
scans_by_day	Napi bontás, dátum szerint növekvő sorrendben, az üres napok kimaradnak
top_countries	A leggyakoribb 8 ország az időablakban, csökkenő sorrendben
top_devices	A leggyakoribb 5 eszköztípus (mobile, tablet, desktop)
top_os	A leggyakoribb 5 operációs rendszer

Note

A lekérdező API nem ad vissza egyedi beolvasási rekordokat — kurzor-alapú lapozással (Cursor-Pagination) sem. Nyers eseményfolyamokhoz (Event-Streams) használj inkább webhookokat (lásd alább). Ha korábbi nyers adatokra van szükséged, exportáld őket a GET /v1/account/export végponton keresztül.

Aggregation über mehrere Codes

A munkaterület-szintű összegek (pl. havi beolvasások az összes kódra vonatkozóan) a GET /v1/workspaces/:id végponton keresztül érhetők el a scans_this_month mezőben. Kódok közötti (Cross-Code) elemzésekhez az irányítópultot vagy az időszakos exportálást javasoljuk.

---

Echtzeit-Konsum via Webhooks

Ha a beolvasási eseményeket azonnal, amint megtörténnek fel szeretnéd dolgozni — például élő irányítópultokhoz, lead-követéshez vagy CRM-integrációkhoz —, iratkozz fel a qr.scanned eseményre:

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

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

A szignó-ellenőrzésről, az újrapróbálkozási (retry) logikáról és a kézbesítési naplókról (delivery logs) szóló teljes dokumentációt az API → Webhooks oldalon találod.

---

DSGVO & Datenschutz

A beolvasási rekordok nem tartalmaznak személyes adatnak minősülő IP-címeket. Az eredeti IP-címet az Edge-Worker egy kriptográfiai hash-függvénnyel (SHA-256) és egy naponta változó salt-tal helyettesíti. Ez azt jelenti, hogy:

• Nincs lehetőség az újra-azonosításra az algoritmus ismeretében sem
• Nincs lehetőség ugyanazon látogató napokon átívelő korrelációjára
• Az eredeti IP-cím soha nem éri el a D1 adatbázist

Az adatmegőrzés (Retention) a csomagtól függ:

Csomag	Megőrzés
Free	7 nap
Pro	90 nap
Business / Agency	1 év
Enterprise	Egyedi (SLA)

Egy naponta futó cron-feladat (purgeOldScans) automatikusan eltávolítja a régebbi rekordokat — ez a kódobjektum total_scans értékét nem érinti.

GDPR-részletek és lekérdező API IP-hashing, adatfeldolgozói megállapodás (DPA), adatexport és az elfeledtetéshez való jog.

---

Best Practices

• Lekérdezési gyakoriság (Polling): Az aggregációs API hatékony, de nem másodpercenkénti lekérdezésre tervezték. Élő frissítésekhez mindig a webhookokat részesítsd előnyben, az API-t pedig csak utólagos feltöltésre (backfill) vagy irányítópultokhoz használd.
• Gyorsítótárazás (Caching): A válasz idősorokat tartalmaz — nagy időablakok (days=365) esetén a payload mérete több KB is lehet. Használj kliensoldali gyorsítótárazást rövid TTL-lel (pl. 60 s).
• Top-N korlátok: A top_countries, top_devices és top_os értékek szerveroldalon 8, illetve 5 bejegyzésre vannak korlátozva. Mélyebb elemzésekhez exportáld a nyers adatokat.
• null értékek kezelése: A country, region, city, referer és language mezők értéke lehet null. Kezeld ezeket az elemzésedben „Ismeretlenként”.