Scan-követés és analitika

Áttekintés

Egy dinamikus QR-kód minden egyes beolvasása létrehoz egy beolvasási rekordot (Scan-Record) a munkaterületeden (Workspace). Az adatgyűjtés teljes egészében a Cloudflare-Edge-en történik — külső követőszolgáltatások és sütik 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 időben)

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.

---

Milyen adatok kerülnek rögzítésre

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 (Code-ID)	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	Napi HMAC-SHA-256-álnevesítő (hosszú távú titok + cél + UTC-nap + IP)	8f3a…
scanned_at	ISO-8601 időbélyeg	2026-05-12T14:32:11.000Z

Tip

Beépített adatminimalizálás (Data minimization by design): Nem helyezünk el sütiket, nincs ujjlenyomat-vétel (fingerprinting), és nem töltünk be külső követőpixeleket. Az Edge-Worker az eredeti IP-címet azonnal HMAC-SHA-256-tal, hosszú távú titokkal, céllal és UTC-nappal álnevesíti; az IP nem hagyja el az Edge-et.

Geolokáció az Edge-en

Minden földrajzi 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 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ónál.
2. Adatvédelem — az IP-cím nem hagyja el a Cloudflare-t, és soha nem kerül továbbításra harmadik félnek.
3. Korlátozott részletesség — a city (város) 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.

---

Beolvasási analitika lekérdezése

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 paraméterek (Query parameters):

Paraméter	Típus	Alapértelmezett	Leírás
days	integer	30	Időszak 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 teljes élettartamára vonatkozó beolvasások száma (függetlenül a days időablaktól)
period_scans	A beolvasások száma 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 a választott 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

An aggregációs 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.

Több kód aggregációja

A munkaterület-szintű összegek (pl. havi beolvasások száma 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.

---

Valós idejű adatfogadás webhookokon keresztül

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 teljes dokumentáció az aláírás-ellenőrzésről, az újrapróbálkozási logikáról (Retry-Logik) és a kézbesítési naplókról (Delivery-Logs) az API → Webhooks oldalon található.

---

GDPR és adatvédelem

A beolvasási rekordok nem tárolják az eredeti IP-címet. Az Edge-Worker HMAC-SHA-256-álnevesítőt vezet le hosszú távú titokból, célból és UTC-napból; az álnevesítő továbbra is személyes adat.

• A titok nélkül az érték nem fordítható vissza közvetlenül, de a titok birtokosa ismert IP-jelölteket újraszámolhat egy UTC-napra.
• A cél és az UTC-nap a levezetés része, így ugyanazon szkenner hash-ei különböző napokon nem hasonlíthatók össze közvetlenül.
• Az eredeti IP-cím nem jut el a D1-be, KV-be vagy R2-be.

Többnapos időablakokban a unique_scanners Szkennelési napok mutató, nem személymutató: ugyanaz a szkenner minden UTC-napra külön álnevesítőt kap.

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

Csomag	Megőrzési idő
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ési API IP-hashing, adatfeldolgozói megállapodás (DPA), adatexport és az elfeledtetéshez való jog.

---

Bevált gyakorlatok (Best Practices)

• Lekérdezési gyakoriság (Polling): Az aggregációs API erőforrás-igénye alacsony, 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 adatok utólagos feltöltésére (Backfill) vagy irányítópultokhoz használd.
• Gyorsítótárazás (Caching): A válasz idősorokat tartalmaz — nagy időablakok esetén (days=365) az adatcsomag mérete elérheti a több KB-ot is. Használj kliensoldali gyorsítótárazást rövid élettartammal (pl. 60 mp TTL).
• Top-N korlátok: A top_countries, top_devices és top_os mezők 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. Az értékelés során kezeld ezeket „Ismeretlenként”.