Παρακολούθηση Σαρώσεων & Analytics

Επισκόπηση

Κάθε σάρωση ενός δυναμικού QR-Code δημιουργεί ένα Scan-Record στο Workspace σας. Η καταγραφή πραγματοποιείται εξ ολοκλήρου στο Cloudflare Edge — χωρίς εξωτερικές υπηρεσίες παρακολούθησης, χωρίς cookies, και χωρίς η αρχική IP να φτάνει ποτέ στη βάση δεδομένων σας.

Τρεις τρόποι για την κατανάλωση των δεδομένων σάρωσης:

API Συγκέντρωσης

GET /v1/codes/:id/scans — Χρονοσειρές + Κορυφαίες χώρες/συσκευές/λειτουργικά συστήματα για ένα μεμονωμένο αντικείμενο κώδικα.

Webhooks (Πραγματικός χρόνος)

Συμβάν qr.scanned ανά σάρωση, υπογεγραμμένο με HMAC-SHA256. Δείτε τα Webhooks.

Dashboard

Οπτικοποίηση στο Dashboard του qr3.app — δεν απαιτείται κλήση API.

---

Ποια δεδομένα συλλέγονται

Για κάθε σάρωση δημιουργείται μια εγγραφή στον πίνακα scans:

Πεδίο	Πηγή	Παράδειγμα
id	UUID που δημιουργείται από τον διακομιστή	scn_d1f8…
code_id	ID του σαρωμένου QR-Code	qr_a1b2c3d4
workspace_id	Workspace του κώδικα	ws_xxx
country	Cloudflare cf.country	AT
region	Cloudflare cf.region	Vienna
city	Cloudflare cf.city	Wien
device_type	User-Agent Parsing	mobile, tablet, desktop
os	User-Agent Parsing	iOS, Android, macOS, Windows
browser	User-Agent Parsing	Safari, Chrome, Firefox
referer	HTTP Referer Header	https://example.com/landing
language	Accept-Language Header (πρώτη γλώσσα)	de
redirected_to	Πραγματικός προορισμός ανακατεύθυνσης	https://example.com
ip_hash	SHA-256(IP + καθημερινό salt) — μη αναστρέψιμο	8f3a…
scanned_at	ISO-8601 Timestamp	2026-05-12T14:32:11.000Z

Tip

Ελαχιστοποίηση δεδομένων εκ σχεδιασμού (by Design): Δεν ορίζονται cookies, δεν γίνεται fingerprinting, και δεν φορτώνονται εξωτερικά pixel παρακολούθησης. Η αρχική διεύθυνση IP μετατρέπεται αμέσως στον Edge Worker σε έναν καθημερινά εναλλασσόμενο κατακερματισμό (hash) SHA-256 και δεν φεύγει ποτέ από το Edge.

Γεωεντοπισμός στο Edge

Όλα τα γεωγραφικά δεδομένα (country, region, city) προέρχονται από το αντικείμενο cf της Cloudflare και βασίζονται στη βάση δεδομένων Geo-IP της Cloudflare. Δεν γίνονται ερωτήματα σε εξωτερικές υπηρεσίες Geo-IP — η ανάλυση πραγματοποιείται στον ίδιο Worker που εκτελεί και την ανακατεύθυνση.

Αυτό έχει τρεις συνέπειες:

1. Χαμηλή καθυστέρηση (Latency) — κανένα επιπλέον βήμα (hop), κανένα DNS Lookup σε εξωτερικό πάροχο.
2. Προστασία δεδομένων — η διεύθυνση IP δεν φεύγει από την Cloudflare και δεν κοινοποιείται ποτέ σε τρίτους.
3. Περιορισμένη ανάλυση — η πόλη (city) δεν είναι πάντα διαθέσιμη (π.χ. σε VPNs, παρόχους κινητής τηλεφωνίας ή μικρές περιοχές). Να αναμένετε τιμές null και να τις συνυπολογίζετε στα Dashboards σας.

---

Ερώτημα Analytics Σαρώσεων

GET /v1/codes/:id/scans

Παρέχει συγκεντρωτικά Analytics για έναν μεμονωμένο QR-Code για μια επιλεγμένη χρονική περίοδο.

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

Παράμετροι ερωτήματος:

Παράμετρος	Τύπος	Προεπιλογή	Περιγραφή
days	integer	30	Χρονική περίοδος σε ημέρες (1–365)

Απόκριση (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" }
}

Πεδία απόκρισης:

Πεδίο	Περιγραφή
total_scans	Συνολικός αριθμός σαρώσεων του κώδικα καθ’ όλη τη διάρκεια ζωής του (ανεξάρτητα από το παράθυρο days)
period_scans	Σύνολο σαρώσεων στο επιλεγμένο χρονικό παράθυρο
scans_by_day	Ημερήσιες ομάδες (buckets), σε αύξουσα σειρά ημερομηνίας, οι κενές ημέρες παραλείπονται
top_countries	Κορυφαίες 8 χώρες στο χρονικό παράθυρο, σε φθίνουσα σειρά
top_devices	Κορυφαίοι 5 τύποι συσκευών (mobile, tablet, desktop)
top_os	Κορυφαία 5 λειτουργικά συστήματα

Note

Το API συγκέντρωσης δεν παρέχει μεμονωμένες καταγραφές σαρώσεων — ούτε μέσω Cursor-Pagination. Για ακατέργαστες ροές συμβάντων (raw event streams), χρησιμοποιήστε αντ’ αυτού Webhooks (δείτε παρακάτω). Εάν χρειάζεστε ιστορικά ακατέργαστα δεδομένα, εξάγετέ τα μέσω του GET /v1/account/export.

Συγκεντρωτικά στοιχεία για πολλούς κώδικες

Τα συγκεντρωτικά σύνολα σε επίπεδο Workspace (π.χ. σαρώσεις ανά μήνα για όλους τους κώδικες) είναι διαθέσιμα μέσω του GET /v1/workspaces/:id στο πεδίο scans_this_month. Για αναλύσεις μεταξύ διαφορετικών κωδίκων (cross-code), συνιστούμε το Dashboard ή μια περιοδική εξαγωγή.

---

Κατανάλωση σε πραγματικό χρόνο μέσω Webhooks

Εάν θέλετε να επεξεργάζεστε τα συμβάντα σάρωσης τη στιγμή που συμβαίνουν — για παράδειγμα για ζωντανά Dashboards, παρακολούθηση υποψήφιων πελατών (lead tracking) ή ενσωματώσεις CRM — εγγραφείτε στο συμβάν 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"
  }
}

Πλήρης τεκμηρίωση σχετικά με την επαλήθευση υπογραφής, τη λογική επαναπροσπάθειας (retry logic) και τα αρχεία καταγραφής παράδοσης (delivery logs) στο API → Webhooks.

---

GDPR & Προστασία Δεδομένων

Οι καταγραφές σαρώσεων δεν περιέχουν προσωπικές διευθύνσεις IP. Η αρχική IP αντικαθίσταται στον Edge Worker από μια κρυπτογραφική συνάρτηση κατακερματισμού (SHA-256) με ένα καθημερινά εναλλασσόμενο salt. Αυτό σημαίνει:

• Καμία δυνατότητα επαναταυτοποίησης, ακόμη και αν είναι γνωστός ο αλγόριθμος
• Καμία συσχέτιση του ίδιου επισκέπτη μεταξύ διαφορετικών ημερών
• Η αρχική IP δεν φεύγει ποτέ από τη βάση δεδομένων D1

Η Διατήρηση δεδομένων (Retention) εξαρτάται από το πακέτο:

Πακέτο	Διατήρηση
Free	7 ημέρες
Pro	90 ημέρες
Business / Agency	1 έτος
Enterprise	Προσαρμοσμένη (SLA)

Μια καθημερινή εργασία Cron (purgeOldScans) αφαιρεί αυτόματα τις παλαιότερες καταγραφές — το πεδίο total_scans στο αντικείμενο κώδικα παραμένει ανεπηρέαστο.

Λεπτομέρειες GDPR & API Πληροφοριών IP Hashing, DPA υποεπεξεργαστών, εξαγωγή δεδομένων και δικαίωμα στη λήθη.

---

Βέλτιστες Πρακτικές

• Συχνότητα Polling: Το API συγκέντρωσης είναι αποδοτικό, αλλά δεν προορίζεται για ερωτήματα ανά δευτερόλεπτο. Για ζωντανές ενημερώσεις, να προτιμάτε πάντα τα Webhooks και να χρησιμοποιείτε το API μόνο για backfills / Dashboards.
• Προσωρινή αποθήκευση (Caching): Η απόκριση περιέχει χρονοσειρές — για μεγάλα παράθυρα (days=365), το payload μπορεί να φτάσει αρκετά KB. Αποθηκεύστε το προσωρινά στην πλευρά του πελάτη (client-side) με σύντομο TTL (π.χ. 60 δευτερόλεπτα).
• Όρια Top-N: Τα top_countries, top_devices, top_os περιορίζονται από την πλευρά του διακομιστή σε 8 ή 5 εγγραφές αντίστοιχα. Για βαθύτερη ανάλυση, εξάγετε τα ακατέργαστα δεδομένα.
• Ανοχή σε τιμές null: Τα πεδία country, region, city, referer, language ενδέχεται να είναι null. Αντιμετωπίστε τα στην ανάλυσή σας ως “Άγνωστο”.