Skenēšanas izsekošana un analītika

Pārskats

Katrs dinamiskā QR koda skenējums izveido skenēšanas ierakstu (Scan-Record) jūsu darba vidē (Workspace). Datu apkopošana pilnībā notiek Cloudflare-Edge — bez ārējiem izsekošanas pakalpojumiem, bez sīkfailiem (cookies) un bez oriģinālās IP adreses nonākšanas jūsu datubāzē.

Trīs veidi, kā piekļūt skenēšanas datiem:

Agregācijas API

GET /v1/codes/:id/scans — laika rindas + populārākās valstis/ierīces/OS vienam koda objektam.

Webhooks (reāllaikā)

qr.scanned notikums katram skenējumam, parakstīts ar HMAC-SHA256. Skatiet Webhooks.

Vadības panelis

Vizualizācija qr3.app vadības panelī — nav nepieciešams API izsaukums.

Kādi dati tiek apkopoti

Katram skenējumam tiek izveidots ieraksts tabulā scans:

Lauks	Avots	Piemērs
`id`	Servera ģenerēts UUID	`scn_d1f8…`
`code_id`	Skenētā QR koda ID	`qr_a1b2c3d4`
`workspace_id`	Koda darba vide (Workspace)	`ws_xxx`
`country`	Cloudflare `cf.country`	`AT`
`region`	Cloudflare `cf.region`	`Vienna`
`city`	Cloudflare `cf.city`	`Wien`
`device_type`	User-Agent parsēšana	`mobile`, `tablet`, `desktop`
`os`	User-Agent parsēšana	`iOS`, `Android`, `macOS`, `Windows`
`browser`	User-Agent parsēšana	`Safari`, `Chrome`, `Firefox`
`referer`	HTTP `Referer` galvene	`https://example.com/landing`
`language`	`Accept-Language` galvene (pirmā valoda)	`de`
`redirected_to`	Faktiskais novirzīšanas mērķis	`https://example.com`
`ip_hash`	Ikdienas HMAC-SHA-256 pseidonīms (ilglaicīgs noslēpums + nolūks + UTC diena + IP)	`8f3a…`
`scanned_at`	ISO-8601 laika zīmogs	`2026-05-12T14:32:11.000Z`

Ģeolokalizācija Edge līmenī

Visi ģeogrāfiskie dati (country, region, city) nāk no Cloudflare cf objekta un ir balstīti uz Cloudflare Geo-IP datubāzi. Ārējie Geo-IP pakalpojumi netiek pieprasīti — noteikšana notiek tajā pašā Worker, kas veic novirzīšanu.

Tam ir trīs sekas:

Zems latentums — nav papildu pārejas (hop), nav DNS vaicājuma ārējam pakalpojumu sniedzējam.
Datu aizsardzība — IP adrese nepamet Cloudflare un nekad netiek nodota trešajām pusēm.
Ierobežota granularitāte — city ne vienmēr ir pieejama (piemēram, izmantojot VPN, mobilo sakaru operatorus vai mazos reģionos). Rēķinieties ar null vērtībām un iekļaujiet tās savos vadības paneļos.

Skenēšanas analītikas pieprasīšana

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

Nodrošina apkopotu analītiku vienam QR kodam izvēlētajā laika periodā.

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

Vaicājuma parametri (Query Parameters):

Parametrs	Tips	Noklusējums	Apraksts
`days`	vesels skaitlis	`30`	Laika periods dienās (1–365)

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

Atbildes lauki:

Lauks	Apraksts
`total_scans`	Kopējais skenējumu skaits koda darbības laikā (neatkarīgi no `days` loga)
`period_scans`	Skenējumu skaits izvēlētajā laika logā
`scans_by_day`	Dienu grupas, augošā secībā pēc datuma, tukšās dienas tiek izlaistas
`top_countries`	Top 8 valstis laika logā, dilstošā secībā
`top_devices`	Top 5 ierīču tipi (`mobile`, `tablet`, `desktop`)
`top_os`	Top 5 operētājsistēmas

Agregācija vairākiem kodiem

Darba vides mēroga kopsummas (piemēram, skenējumi mēnesī visiem kodiem) ir pieejamas, izmantojot GET /v1/workspaces/:id laukā scans_this_month. Starpkodu analīzei mēs iesakām izmantot vadības paneli vai periodisku eksportēšanu.

Reāllaika patēriņš, izmantojot Webhooks

Ja vēlaties apstrādāt skenēšanas notikumus tiklīdz tie notiek — piemēram, tiešsaistes vadības paneļiem, kontaktu izsekošanai (Lead-Tracking) vai CRM integrācijām —, abonējiet qr.scanned notikumu:

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

Datu kopa (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"
  }
}

Pilna dokumentācija par paraksta verifikāciju, atkārtošanas loģiku (Retry-Logik) un piegādes žurnāliem (Delivery-Logs) ir pieejama sadaļā API → Webhooks.

VDAR un datu aizsardzība

Skenēšanas ieraksti neglabā sākotnējo IP. Edge Worker atvasina HMAC-SHA-256 pseidonīmu no ilglaicīga noslēpuma, nolūka un UTC dienas; pseidonīms joprojām ir personas dati.

Bez noslēpuma vērtība nav tieši apgriežama, bet noslēpuma turētājs var UTC dienai pārrēķināt zināmus IP kandidātus.
Nolūks un UTC diena ir atvasināšanas daļa, tādēļ viena skenera hash dažādās dienās nav tieši salīdzināmi.
Sākotnējais IP nenonāk D1, KV vai R2.

Vairāku dienu logos unique_scanners ir Skenēšanas dienas metrika, nevis personu metrika: viens skeneris katrai UTC dienai saņem atsevišķu pseidonīmu.

Datu glabāšanas ilgums (Retention):

Plāns	Uzglabāšana
Visi plāni	90 dienas

Katru dienu palaists Cron uzdevums (purgeOldScans) automātiski dzēš vecākus ierakstus — tas neietekmē total_scans vērtību koda objektā.

VDAR informācija un informācijas pieprasīšanas API IP jaukšana, apakšapstrādātāju DPA, datu eksports un tiesības tikt aizmirstam.

Labākā prakse

Aptaujas biežums (Polling-Frequenz): Agregācijas API ir efektīva, taču tā nav paredzēta vaicājumiem katru sekundi. Tiešsaistes atjauninājumiem vienmēr dodiet priekšroku Webhooks un izmantojiet API tikai datu papildināšanai (Backfills) vai vadības paneļiem.
Kešatmiņa (Caching): Atbilde satur laika rindas — lielu laika logu gadījumā (days=365) datu kopa (payload) var sasniegt vairākus KB. Veiciet kešatmiņu klienta pusē ar īsu TTL (piemēram, 60 s).
Top-N ierobežojumi: top_countries, top_devices, top_os servera pusē ir ierobežoti attiecīgi līdz 8 vai 5 ierakstiem. Padziļinātai analīzei eksportējiet neapstrādātos datus.
Pieļaujiet null vērtības: country, region, city, referer, language var būt null. Savā analīzē apstrādājiet tās kā “Nezināms”.