Rianú Scananna & Anailísíocht

Foramharc

Cruthaíonn gach scanadh ar chód QR dinimiciúil taifead scanta i do spás oibre. Tarlaíonn an bhailiúchán go hiomlán ag imeall Cloudflare — gan seirbhísí rianaithe seachtracha, gan fianáin, agus gan an seoladh IP bunaidh a shroicheadh do bhunachar sonraí riamh.

Trí bhealach chun sonraí scanta a úsáid:

API Comhiomlánaithe

GET /v1/codes/:id/scans — Sraith ama + Príomhthíortha/-gléasanna/-OS do chód-réad aonair.

Webhooks (Fíor-am)

Teagmhas qr.scanned in aghaidh an scanta, sínithe le HMAC-SHA256. Féach Webhooks.

Deais

Léiriú amhairc i ndeais qr3.app — níl aon ghlaoch API de dhíth.

Cad iad na sonraí a bhailítear

Cruthaítear taifead sa tábla scans in aghaidh gach scanta:

Réimse	Foinse	Sampla
`id`	UUID ginte ag an bhfreastalaí	`scn_d1f8…`
`code_id`	ID an chóid QR a scanadh	`qr_a1b2c3d4`
`workspace_id`	Spás oibre an chóid	`ws_xxx`
`country`	Cloudflare `cf.country`	`AT`
`region`	Cloudflare `cf.region`	`Vienna`
`city`	Cloudflare `cf.city`	`Wien`
`device_type`	Parsáil User-Agent	`mobile`, `tablet`, `desktop`
`os`	Parsáil User-Agent	`iOS`, `Android`, `macOS`, `Windows`
`browser`	Parsáil User-Agent	`Safari`, `Chrome`, `Firefox`
`referer`	Ceanntásc HTTP `Referer`	`https://example.com/landing`
`language`	Ceanntásc `Accept-Language` (an chéad teanga)	`de`
`redirected_to`	Sprioc athsheolta iarbhír	`https://example.com`
`ip_hash`	SHA-256(IP + salann laethúil) — neamh-inchúlaithe	`8f3a…`
`scanned_at`	Stampa ama ISO-8601	`2026-05-12T14:32:11.000Z`

Geolonnú ag an Edge

Tagann na sonraí geografacha go léir (country, region, city) as réad cf Cloudflare agus tá siad bunaithe ar bhunachar sonraí Geo-IP Cloudflare. Ní dhéantar aon iarratas ar sheirbhísí seachtracha Geo-IP — tarlaíonn an réiteach sa Worker céanna a dhéanann an t-athsheoladh.

Tá trí iarmhairt ag baint leis seo:

Moill íseal — gan aon léim bhreise, gan aon chuardach DNS ar sholáthraí seachtrach.
Cosaint sonraí — ní fhágann an seoladh IP Cloudflare agus ní roinntear le tríú páirtithe é riamh.
Miondealú teoranta — ní bhíonn city ar fáil i gcónaí (e.g. le VPNanna, iompróirí soghluaiste, nó réigiúin bheaga). Bí ag súil le luachanna null agus cuir san áireamh iad i do dheais.

Anailísíocht Scananna a Fhiosrú

`GET /v1/codes/:id/scans`

Soláthraíonn sé anailísíocht chomhiomlánaithe do chód QR aonair thar thréimhse roghnaithe.

curl "https://qr3.app/v1/codes/qr_a1b2c3d4/scans?days=30" \
  -H "Authorization: Bearer qr3_sk_..."

const analytics = await qr3.scans.get('qr_a1b2c3d4', { days: 30 });
console.log(analytics.period_scans, analytics.top_countries);

qr3 scans qr_a1b2c3d4 --days 30

Paraiméadair Iarratais:

Paraiméadar	Cineál	Réamhshocrú	Cur síos
`days`	integer	`30`	Tréimhse i laethanta (1–365)

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

Réimsí Freagra:

Réimse	Cur síos
`total_scans`	Iomlán na scananna feadh an tsaoil don chód (neamhspleách ar an bhfuinneog `days`)
`period_scans`	Iomlán na scananna sa bhfuinneog ama roghnaithe
`scans_by_day`	Bicéid laethúla, in ord ardaitheach de réir dáta, fágtar laethanta folmha ar lár
`top_countries`	Na 8 dtír is fearr sa bhfuinneog ama, in ord íslitheach
`top_devices`	Na 5 chineál gléis is fearr (`mobile`, `tablet`, `desktop`)
`top_os`	Na 5 chóras oibriúcháin is fearr

Comhiomlánú thar roinnt Cód

Tá iomláin ar leibhéal an spáis oibre (e.g. scananna in aghaidh na míosa thar gach cód) ar fáil trí GET /v1/workspaces/:id mar an réimse scans_this_month. Le haghaidh anailís tras-chóid, molaimid an deais nó easpórtáil thréimhsiúil.

Fíor-am a Úsáid trí Webhooks

Más mian leat teagmhais scanta a phróiseáil chomh luath agus a tharlaíonn siad — mar shampla le haghaidh deais bheo, rianú treoracha, nó comhtháthú CRM — liostáil don teagmhas 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"
  }'

Pálasta:

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

Doiciméadúchán iomlán ar fhíorú sínithe, loighic atriallta, agus logaí seachadta in API → Webhooks.

Níl aon seoltaí IP pearsanta i dtaifid scanta. Cuirtear feidhm hash chripteagrafach (SHA-256) le salann a rothlaíonn go laethúil in ionad an IP bhunaidh sa Edge Worker. Ciallaíonn sé seo:

Gan aon ath-aithint fiú má tá eolas ar an algartam
Gan aon chomhchoibhneas thar laethanta don cuairteoir céanna
Ní shroicheann an IP bunaidh bunachar sonraí D1 riamh

Braitheann coinneáil sonraí ar an bplean:

Plean	Coinneáil
Free	7 lá
Pro	90 lá
Business / Agency	1 bhliain
Enterprise	Saincheaptha (SLA)

Baineann post Cron laethúil (purgeOldScans) seantaifid go huathoibríoch — ní dhéantar difear do total_scans ar an gcód-réad dá bharr.

Sonraí GDPR & API Faisnéise Hashing IP, DPA Fo-phróiseálaí, easpórtáil sonraí, agus an ceart go ndéanfaí dearmad ort.

Dea-Chleachtais

Minicíocht vótaíochta: Tá an API Comhiomlánaithe éifeachtach ó thaobh costais de, ach níl sé deartha le haghaidh vótaíocht gach soicind. Le haghaidh nuashonruithe beo, tabhair tosaíocht do Webhooks i gcónaí agus ná húsáid an API ach le haghaidh cúltóga / deais.
Taisceadh: Tá sraitheanna ama sa fhreagra — le fuinneoga móra (days=365), is féidir leis an bpálasta a bheith roinnt KB i méid. Cuir i dtaisce é ar thaobh an chliaint le TTL gearr (e.g. 60 s).
Teorainneacha Top-N: Tá top_countries, top_devices, top_os teoranta do 8 nó 5 iontráil ar thaobh an fhreastalaí. Le haghaidh anailís níos doimhne, easpórtáil na sonraí amha.
Glac le luachanna null: Is féidir le country, region, city, referer, language a bheith null. Déan iad seo a láimhseáil mar “Neamhaitheanta” i do chuid anailíse.