Skannausten seuranta & analytiikka

Yleiskatsaus

Jokainen dynaamisen QR-koodin skannaus luo skannaustietueen (Scan-Record) työtilaasi. Tiedonkeruu tapahtuu kokonaan Cloudflare-edgessä — ilman ulkoisia seurantapalveluita, ilman evästeitä ja ilman, että alkuperäinen IP-osoite koskaan päätyy tietokantaasi.

Kolme tapaa hyödyntää skannaustietoja:

Aggregaatio-API

GET /v1/codes/:id/scans — Aikasarjat + suosituimmat maat/laitteet/käyttöjärjestelmät yksittäiselle koodiobjektille.

Webhookit (reaaliaikainen)

qr.scanned-tapahtuma per skannaus, HMAC-SHA256-allekirjoitettu. Katso Webhookit.

Hallintapaneeli

Visualisointi qr3.app-hallintapaneelissa — API-kutsua ei tarvita.

Mitä tietoja kerätään

Jokaisesta skannauksesta luodaan tietue scans-tauluun:

Kenttä	Lähde	Esimerkki
`id`	Palvelimen generoima UUID	`scn_d1f8…`
`code_id`	Skannatun QR-koodin koodi-ID	`qr_a1b2c3d4`
`workspace_id`	Koodin työtila (Workspace)	`ws_xxx`
`country`	Cloudflare `cf.country`	`AT`
`region`	Cloudflare `cf.region`	`Vienna`
`city`	Cloudflare `cf.city`	`Wien`
`device_type`	User-Agent-analyysi	`mobile`, `tablet`, `desktop`
`os`	User-Agent-analyysi	`iOS`, `Android`, `macOS`, `Windows`
`browser`	User-Agent-analyysi	`Safari`, `Chrome`, `Firefox`
`referer`	HTTP `Referer`-otsake	`https://example.com/landing`
`language`	`Accept-Language`-otsake (ensimmäinen kieli)	`de`
`redirected_to`	Todellinen uudelleenohjauskohde	`https://example.com`
`ip_hash`	SHA-256(IP + päivittäinen suola) — ei kumottavissa	`8f3a…`
`scanned_at`	ISO-8601-aikaleima	`2026-05-12T14:32:11.000Z`

Geolokaatio edgessä

Kaikki maantieteelliset tiedot (country, region, city) ovat peräisin Cloudflaren cf-objektista ja perustuvat Cloudflaren Geo-IP-tietokantaan. Ulkoisia Geo-IP-palveluita ei kutsuta — sijainnin selvitys tapahtuu samassa Workerissa, joka suorittaa myös uudelleenohjauksen.

Tällä on kolme seurausta:

Matala viive — ei ylimääräistä hyppyä (hop), ei DNS-kyselyä ulkoiselle palveluntarjoajalle.
Tietosuoja — IP-osoite ei poistu Cloudflaresta eikä sitä koskaan luovuteta kolmansille osapuolille.
Rajoitettu tarkkuus — city ei ole aina saatavilla (esim. VPN-yhteyksien, mobiilioperaattoreiden tai pienten alueiden kohdalla). Varaudu null-arvoihin ja ota ne huomioon hallintapaneeleissasi.

Skannausanalytiikan kyselyt

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

Palauttaa aggregoidun analytiikan yksittäiselle QR-koodille valitulta ajanjaksolta.

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

Kyselyparametrit:

Parametri	Tyyppi	Oletus	Kuvaus
`days`	integer	`30`	Ajanjakso päivinä (1–365)

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

Vastauksen kentät:

Kenttä	Kuvaus
`total_scans`	Koodin elinkaaren aikainen skannausten kokonaismäärä (riippumaton `days`-ajanjaksosta)
`period_scans`	Skannausten määrä valitulla ajanjaksolla
`scans_by_day`	Päivittäiset ryhmittelyt, nousevassa järjestyksessä päivämäärän mukaan, tyhjät päivät jätetään pois
`top_countries`	Suosituimmat 8 maata ajanjaksolla, laskeva järjestys
`top_devices`	Suosituimmat 5 laitetyyppiä (`mobile`, `tablet`, `desktop`)
`top_os`	Suosituimmat 5 käyttöjärjestelmää

Aggregointi useamman koodin yli

Työtilan laajuiset kokonaismäärät (esim. skannaukset kuukaudessa kaikille koodeille) ovat saatavilla polusta GET /v1/workspaces/:id kentässä scans_this_month. Koodien väliseen ristiinanalyysiin suosittelemme hallintapaneelia tai säännöllistä vientiä (export).

Reaaliaikainen seuranta webhookeilla

Jos haluat käsitellä skannaustapahtumia heti kun ne tapahtuvat — esimerkiksi reaaliaikaisia hallintapaneeleja, liidien seurantaa tai CRM-integraatioita varten — tilaa qr.scanned-tapahtuma:

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

Täydellinen dokumentaatio allekirjoituksen varmentamisesta, uudelleenyrityslogiikasta ja toimituslogeista löytyy sivulta API → Webhookit.

Skannaustietueet eivät sisällä henkilötietoja sisältäviä IP-osoitteita. Alkuperäinen IP korvataan Edge-Workerissa kryptografisella tiivisteellä (SHA-256) käyttäen päivittäin vaihtuvaa suolaa (salt). Tämä tarkoittaa:

Ei uudelleentunnistusta, vaikka algoritmi tunnettaisiin
Ei saman vierailijan yhdistämistä eri päivien välillä
Alkuperäinen IP ei koskaan päädy D1-tietokantaan

Säilytysaika (retention) riippuu tilauksesta:

Tilaus	Säilytysaika
Free	7 päivää
Pro	90 päivää
Business / Agency	1 vuosi
Enterprise	Mukautettu (SLA)

Päivittäin suoritettava cron-työ (purgeOldScans) poistaa vanhemmat tietueet automaattisesti — tämä ei vaikuta koodiobjektin total_scans-arvoon.

GDPR-tiedot & tietopyyntö-API IP-hashing, alihankkijoiden DPA, tietojen vienti ja oikeus tulla unohdetuksi.

Parhaat käytännöt

Kyselytiheys (polling): Aggregaatio-API on tehokas, mutta sitä ei ole tarkoitettu sekuntitason kyselyihin. Suosi reaaliaikaisiin päivityksiin aina webhookeja ja käytä API-rajapintaa vain puuttuvien tietojen täydentämiseen tai hallintapaneeleihin.
Välimuisti (caching): Vastaus sisältää aikasarjoja — suurilla ajanjaksoilla (days=365) payload voi olla useita kilotavuja. Käytä asiakaspuolen välimuistia lyhyellä eliniällä (TTL, esim. 60 s).
Top-N-rajoitukset: top_countries, top_devices ja top_os on rajoitettu palvelimen puolella 8 tai 5 tietueeseen. Syvällisempää analyysiä varten vie raakatiedot.
Salli null-arvot: Kentät country, region, city, referer ja language voivat olla null. Käsittele nämä analyysissäsi arvona ”Tuntematon”.