Provided by TippyEntertainment

https://github.com/tippyentertainment/skills.git

qr-code-scanner-tracking

Summary

Design, build, and refine a QR code–based tracking system. This skill helps generate QR codes, define what happens when they are scanned, and track scan events (who, where, when, how) for marketing, operations, product flows, or internal tools.

When to Use

Use this skill when the user wants to:

• Create QR codes that point to dynamic tracking URLs.
• Track scans and conversions from flyers, packaging, events, screens, or internal assets.
• Run campaign‑level or per‑user/per‑asset tracking via QR codes.
• Implement a scan → route → log flow (scan opens a page, triggers analytics, and records metadata).
• Integrate QR scanning into web or mobile apps (e.g., internal apps, kiosks, field tools).

This skill focuses on architecture, data modeling, and code scaffolding around QR generation and scan tracking.

Inputs to Collect

The assistant should ask for:

Business Context

• Primary use case
  • Examples: marketing campaign tracking, event check‑ins, product packaging, asset tracking, login/device pairing, in‑store signage.
• What should happen on scan
  • Redirect to a landing page, open an app deep link, show a dynamic screen, start a flow (e.g., sign‑up).
• Tracking goals
  • Need to measure: total scans, unique scanners, location, conversion to sign‑up/purchase, per‑channel performance, etc.

Technical Context

• Existing stack
  • Frontend: React, Next.js, Vue, Svelte, SPA, native apps.
  • Backend: Node, Deno, Python, Cloudflare Workers, AWS Lambda, etc.
• Hosting / platform
  • Cloudflare (Workers/Pages/D1), AWS, GCP, on‑prem, etc.
• Expected scale
  • Approximate number of QR codes and expected scans per day.

Data & Privacy

• Data to capture per scan
  • At minimum: timestamp, QR code ID, campaign/channel.
  • Optional: IP/geo (anonymized), device type, user ID/session ID, referrer.
• Privacy / compliance
  • Requirements for consent, anonymization, and data retention.

If key details are missing, ask 2–4 clarifying questions before proposing a solution.

Expected Behavior

1. Clarify Requirements

• Summarize the use case in a few bullets (e.g., “Track scans from conference badges and attribute sign‑ups to specific booths/QRs”).
• Identify:
  • Tracking granularity (per campaign, per medium, per asset, per person).
  • Any constraints around offline usage or printing.

2. Propose Architecture

Break the system into clear components:

QR Code Generation Service

• Responsibilities:
  • Create QR codes with unique tokens/IDs.
  • Associate each token with:
    • Destination URL or app deep link.
    • Campaign/channel metadata (e.g., utm_source, utm_medium).
    • Optional per‑asset or per‑user labels.
• Design:
  • A backend API or CLI to generate and store QR definitions.
  • Optional admin UI for non‑technical users to create/manage codes.
• Options:
  • Support static destination URLs or dynamic rules (e.g., A/B tests, geo‑dependent destinations).

Scan Handler / Redirect Endpoint

• Route pattern:
  • e.g. https://app.example.com/q/{token} or custom domain /r/{token}.
• Responsibilities:
  • Parse token from the URL.
  • Look up QR definition in the database.
  • Log a scan event with metadata.
  • Redirect to the destination URL (or render a dynamic page).
• Behavior for errors:
  • Invalid/unknown token → show friendly error page.
  • Inactive/expired codes → show fallback/expired message.

Tracking & Storage

• Data model (example):

  • qr_codes

    • id
    • token (unique)
    • campaign_id (optional)
    • destination_url
    • label (human‑readable name)
    • metadata_json (optional)
    • is_active (boolean)
    • created_at
    • expires_at (optional)

  • qr_scan_events

    • id
    • qr_code_id
    • scanned_at
    • ip_hash or ip_truncated (optional, privacy‑aware)
    • user_agent
    • referrer
    • geo_region (optional, if platform provides coarse region)
    • user_id or session_id (optional)
    • meta_json (extra context: channel, device, app info)

• Storage options:

  • Lightweight DB (Cloudflare D1, DynamoDB, Postgres, etc.).
  • Optional export to analytics warehouse (BigQuery/Redshift/ClickHouse) if needed.

Analytics & Reporting

• Queries and metrics:
  • Scans per campaign, per day, per channel.
  • Top performing codes.
  • Conversion metrics when tied to downstream events (e.g., sign‑ups).
• Dashboard ideas:
  • Time‑series charts.
  • Table of campaigns and scan counts.
  • Device/browser breakdown.
  • Map of approximate regions (if geo tracked).

Scanner Integration (Optional)

• Browser‑based scanner:
  • Use getUserMedia + JavaScript QR decoder for internal tools or kiosks.
• Native app integration:
  • Use platform scanners and direct results to the same /q/{token} endpoints or custom deep links.
• Decide:
  • Whether scanner is only internal, or exposed to end‑users through apps.

3. Generate Implementation Scaffolding

The skill should produce implementation‑ready scaffolding appropriate to the user’s stack. Examples:

Example Scan Handler (TypeScript / Cloudflare Worker Style)

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);
    const segments = url.pathname.split('/').filter(Boolean);
    const token = segments[segments.length - 1]; // /q/{token}

    if (!token) {
      return new Response('Invalid QR code', { status: 400 });
    }

    // Look up QR code
    const qr = await env.DB.prepare(
      'SELECT id, destination_url, campaign_id, is_active FROM qr_codes WHERE token = ?'
    ).bind(token).first();

    if (!qr || !qr.is_active) {
      return new Response('QR code not found or inactive', { status: 404 });
    }

    // Collect metadata
    const ua = request.headers.get('user-agent') ?? '';
    const ip = request.headers.get('cf-connecting-ip') ?? '';
    const now = new Date().toISOString();

    // Persist scan event (with hashed/truncated IP if required)
    await env.DB.prepare(
      'INSERT INTO qr_scan_events (qr_code_id, scanned_at, user_agent, ip_hash) VALUES (?, ?, ?, ?)'
    ).bind(qr.id, now, ua, hashIp(ip)).run();

    // Redirect to destination URL
    return Response.redirect(qr.destination_url, 302);
  },
};