qr-code-scanner-tracking

TippyEntertainment 提供

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

このスキルは、Tasking.tech エージェントプラットフォーム（https://tasking.tech）での使用を想定しており、.claude、.openai、.mistral などのスキル形式のハンドラーを受け入れるアシスタントランタイムとも互換性があります。このスキルは、Claude code と Tasking.tech エージェントソースの両方に使用してください。

qr-code-scanner-tracking

概要

QR コードベースのトラッキングシステムを設計、構築、改善します。このスキルは、QR コードの生成、スキャン時の動作の定義、マーケティング、運用、プロダクトのフロー、内部ツール向けのスキャンイベント（誰が、どこで、いつ、どのようにスキャンしたか）の追跡を支援します。

---

使用するタイミング

ユーザーが次のことを希望する場合に、このスキルを使用してください。

• 動的なトラッキング URL を指す QR コードを作成する。
• チラシ、パッケージ、イベント、画面、内部アセットからのスキャン数とコンバージョンを追跡する。
• QR コードを使って、キャンペーン単位またはユーザー／アセット単位でトラッキングする。
• スキャン → ルーティング → ログ記録のフローを実装する（スキャンするとページが開き、アナリティクスが起動し、メタデータが記録される）。
• ウェブアプリやモバイルアプリ（社内アプリ、キオスク、現場ツールなど）に QR スキャンを統合する。

このスキルでは、QR コード生成とスキャン追跡に関するアーキテクチャ、データモデリング、コードのひな形作成に重点を置きます。

---

収集する入力情報

アシスタントは次の内容を尋ねてください。

ビジネスコンテキスト

• 主なユースケース
  • 例：マーケティングキャンペーンのトラッキング、イベントのチェックイン、製品パッケージ、アセット追跡、ログイン／デバイスのペアリング、店舗内のサイン。
• スキャン時に行うこと
  • ランディングページへリダイレクトする、アプリのディープリンクを開く、動的な画面を表示する、フロー（登録など）を開始する。
• トラッキングの目標
  • 測定する項目：スキャン総数、ユニークスキャナー数、場所、登録／購入へのコンバージョン、チャネルごとのパフォーマンスなど。

技術コンテキスト

• 既存の技術スタック
  • フロントエンド：React、Next.js、Vue、Svelte、SPA、ネイティブアプリ。
  • バックエンド：Node、Deno、Python、Cloudflare Workers、AWS Lambda など。
• ホスティング／プラットフォーム
  • Cloudflare（Workers／Pages／D1）、AWS、GCP、オンプレミスなど。
• 想定規模
  • QR コードのおおよその数と、1 日あたりに予想されるスキャン数。

データとプライバシー

• スキャンごとに取得するデータ
  • 最低限：タイムスタンプ、QR コード ID、キャンペーン／チャネル。
  • 任意：IP／位置情報（匿名化済み）、デバイスの種類、ユーザー ID／セッション ID、リファラー。
• プライバシー／コンプライアンス
  • 同意、匿名化、データ保持に関する要件。

重要な情報が不足している場合は、解決策を提案する前に確認質問を 2～4 件してください。

---

期待される動作

1. 要件を明確にする

• ユースケースを箇条書きで簡潔にまとめます（例：「カンファレンスのバッジからのスキャンを追跡し、登録を特定のブース／QR に紐付ける」）。
• 次の点を確認します。
  • トラッキングの粒度（キャンペーン単位、媒体単位、アセット単位、個人単位）。
  • オフライン利用や印刷に関する制約。

2. アーキテクチャを提案する

システムを明確なコンポーネントに分けます。

QR コード生成サービス

• 役割：
  • 一意のトークン／IDを持つ QR コードを作成する。
  • 各トークンに次の情報を関連付ける。
    • 遷移先 URL またはアプリのディープリンク。
    • キャンペーン／チャネルのメタデータ（例：utm_source、utm_medium）。
    • 任意のアセット単位またはユーザー単位のラベル。
• 設計：
  • QR コードの定義を生成・保存するバックエンド API または CLI。
  • 技術者以外のユーザーがコードを作成・管理できる任意の管理 UI。
• オプション：
  • 固定の遷移先 URL または動的なルール（A/B テスト、位置情報に応じた遷移先など）に対応する。

スキャンハンドラー／リダイレクトエンドポイント

• ルートパターン：
  • 例：https://app.example.com/q/{token} またはカスタムドメインの /r/{token}。
• 役割：
  • URL からトークンを解析する。
  • データベースで QR コードの定義を検索する。
  • メタデータとともにスキャンイベントを記録する。
  • 遷移先 URL にリダイレクトする（または動的なページを表示する）。
• エラー時の動作：
  • 無効または不明なトークン → 分かりやすいエラーページを表示する。
  • 無効化または期限切れのコード → フォールバックメッセージまたは期限切れメッセージを表示する。

トラッキングとストレージ

• データモデル（例）：

  • qr_codes

    • id
    • token（一意）
    • campaign_id（任意）
    • destination_url
    • label（人が読み取れる名前）
    • metadata_json（任意）
    • is_active（ブール値）
    • created_at
    • expires_at（任意）

  • qr_scan_events

    • id
    • qr_code_id
    • scanned_at
    • ip_hash または ip_truncated（任意、プライバシーに配慮）
    • user_agent
    • referrer
    • geo_region（任意、プラットフォームが大まかな地域を提供する場合）
    • user_id または session_id（任意）
    • meta_json（追加コンテキスト：チャネル、デバイス、アプリ情報）

• ストレージの選択肢：

  • 軽量なデータベース（Cloudflare D1、DynamoDB、Postgres など）。
  • 必要に応じて、アナリティクス用データウェアハウス（BigQuery／Redshift／ClickHouse）へのエクスポートも可能です。

アナリティクスとレポート

• クエリと指標：
  • キャンペーン別、日別、チャネル別のスキャン数。
  • パフォーマンス上位のコード。
  • 下流イベント（例：サインアップ）に関連付けた場合のコンバージョン指標。
• ダッシュボードのアイデア：
  • 時系列グラフ。
  • キャンペーンとスキャン数の一覧表。
  • デバイス／ブラウザー別の内訳。
  • おおよその地域を示すマップ（地域情報を追跡している場合）。

スキャナーの統合（任意）

• ブラウザーベースのスキャナー：
  • 内部ツールやキオスクには、getUserMedia と JavaScript の QR デコーダーを使用します。
• ネイティブアプリとの統合：
  • プラットフォームのスキャナーを使用し、結果を同じ /q/{token} エンドポイントまたはカスタムのディープリンクに直接渡します。
• 次の点を決定します：
  • スキャナーを内部専用にするか、アプリを通じてエンドユーザーにも公開するか。

---

3. 実装用のひな形を生成する

このスキルは、ユーザーの技術スタックに適した、実装にすぐ使えるひな形を生成する必要があります。例：

スキャンハンドラーの例（TypeScript／Cloudflare Worker スタイル）

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);
  },
};