GA4のMeasurement Protocolで、LINEや電話で受けた予約と、その後の来館・成約をGA4へ送る実装。client_idの受け渡し、イベントの設計、api_secretの置き場所、72時間の制約、二重送信の防ぎ方、個人情報を送らない点検

// ga-ids.js — 予約フォームの送信前に、GA4 の client_id を隠し項目へ入れる
// タグが止められている・まだ読み込まれていないなどで値が返らなくても、予約の送信は止めない
function readGtagField(measurementId, field, timeoutMs = 1500) {
  return new Promise((resolve) => {
    if (typeof window.gtag !== 'function') return resolve('');
    const timer = setTimeout(() => resolve(''), timeoutMs);
    window.gtag('get', measurementId, field, (value) => {
      clearTimeout(timer);
      resolve(value == null ? '' : String(value));
    });
  });
}

document.querySelector('#booking-form').addEventListener('submit', async (e) => {
  const form = e.currentTarget;
  if (form.dataset.ready === '1') return; // 2回目の submit はそのまま送る
  e.preventDefault();
  form.elements.ga_client_id.value = await readGtagField('G-XXXXXXXXXX', 'client_id');
  form.dataset.ready = '1';
  form.requestSubmit();
});

gtagなし: ""
gtagあり: "1838291045.1759550000"
応答なし: "" 1502ms

"1838291045.1759550000" []
"402918377.1759552222" []
"bk_7f3a9c" []
"090-1234-5678" [ 'phone' ]
"06 6123 4567" [ 'phone' ]
"+81 90 1234 5678" [ 'phone' ]
"[email protected]" [ 'email' ]
"000123" [ 'phone' ]

1. 正しい形 → HTTP 200
   （validationMessages は空）
2. 80時間前・RELAXED（既定） → HTTP 200
   （validationMessages は空）
3. 80時間前・ENFORCE_RECOMMENDATIONS → HTTP 200
   VALUE_INVALID timestamp_micros: Measurement timestamp_micros has timestamp too far in the past. Measurement protocol only supports timestamps [72h] into the past. The current time in UNIX microseconds is [1791109866168959].
4. ミリ秒のまま入れた → HTTP 200
   VALUE_INVALID timestamp_micros: Measurement timestamp_micros has timestamp too far in the past. Measurement protocol only supports timestamps [72h] into the past. The current time in UNIX microseconds is [1791109866328252].
5. 予約済みの名前 → HTTP 200
   NAME_RESERVED events: Event at index: [0] has name [session_start] which is reserved.
6. 値が101文字・ENFORCE → HTTP 200
   VALUE_TOO_LONG events.params: Param [note] has value [あああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああああ] longer than max characters [100].
7. メールと電話をパラメータに入れた → HTTP 200
   （validationMessages は空）

積む: true
同じ来館をもう一度積む: false
[
  {
    "id": "bk_e5a113",
    "stage": "contracted",
    "status": "skipped",
    "problems": [
      "発生から80時間たっている（72時間の上限に近いか超えている）"
    ]
  },
  {
    "id": "bk_c41e02",
    "stage": "booked",
    "status": "sent",
    "http": 200,
    "validationMessages": []
  },
  {
    "id": "bk_7f3a9c",
    "stage": "visited",
    "status": "sent",
    "http": 200,
    "validationMessages": []
  },
  {
    "id": "bk_9d0b7e",
    "stage": "visited",
    "status": "skipped",
    "problems": [
      "client_id がない（Webの訪問とつなぐ鍵がないので送らない）"
    ]
  },
  {
    "id": "[email protected]",
    "stage": "visited",
    "status": "skipped",
    "problems": [
      "個人情報らしい値: booking_ref（email）"
    ]
  }
]
2回目の flush: []
┌─────────┬────────────────────┬──────────────┬───────────┐
│ (index) │ booking_id         │ stage        │ status    │
├─────────┼────────────────────┼──────────────┼───────────┤
│ 0       │ 'bk_7f3a9c'        │ 'visited'    │ 'sent'    │
│ 1       │ 'bk_c41e02'        │ 'booked'     │ 'sent'    │
│ 2       │ 'bk_9d0b7e'        │ 'visited'    │ 'skipped' │
│ 3       │ 'bk_e5a113'        │ 'contracted' │ 'skipped' │
│ 4       │ '[email protected]' │ 'visited'    │ 'skipped' │
└─────────┴────────────────────┴──────────────┴───────────┘

// ga4-mp.mjs — 予約の後に起きた出来事（来館・成約など）を、Measurement Protocol で GA4 へ送る
// サーバー側だけで動かす。api_secret は環境変数から読み、ブラウザへは絶対に渡さない。
const ENDPOINT = {
  prod: 'https://www.google-analytics.com/mp/collect',
  debug: 'https://www.google-analytics.com/debug/mp/collect', // 検証用。レポートには載らない
};

// 予約システムの出来事 → GA4 の推奨イベント（リード用）
export const EVENT_MAP = {
  booked: 'generate_lead',        // 予約を受けた（LINE・電話など、ブラウザの外で受けたとき）
  visited: 'working_lead',        // 来館・来店して担当者と会った
  contracted: 'close_convert_lead', // 成約
  lost: 'close_unconvert_lead',   // 成約に至らなかった
};

const MAX_BACKDATE_MS = 72 * 60 * 60 * 1000;     // ドキュメント上の上限
const SAFETY_MARGIN_MS = 60 * 60 * 1000;          // 送信の遅れを見込んで1時間手前で打ち切る
const NAME_RE = /^[A-Za-z][A-Za-z0-9_]{0,39}$/;   // 英字で始まり、英数字と_、40文字以内
const RESERVED_PREFIX = /^(_|firebase_|ga_|google_|gtag\.)/;

// 個人情報らしい値を送らないための最後の網（これだけに頼らず、送る項目を最初から絞る）
const PII_PATTERNS = [
  { kind: 'email', re: /[^\s@]+@[^\s@]+\.[^\s@]+/ },
  { kind: 'phone', re: /(?<!\d)(?:\+81[-\s]?|0)\d{1,4}[-\s]?\d{1,4}[-\s]?\d{3,4}(?!\d)/ },
];

export function findPii(value) {
  const s = String(value);
  return PII_PATTERNS.filter((p) => p.re.test(s)).map((p) => p.kind);
}

/**
 * 送る前の点検。問題があれば理由の配列を返す（空なら送ってよい）
 * @param {{clientId:string, userId?:string, name:string, params:object, occurredAt:Date}} ev
 */
export function checkEvent(ev, now = new Date()) {
  const errors = [];
  if (!ev.clientId) errors.push('client_id がない（Webの訪問とつなぐ鍵がないので送らない）');
  if (!NAME_RE.test(ev.name)) errors.push(`イベント名が規則に合わない: ${ev.name}`);
  const age = now - ev.occurredAt;
  if (age > MAX_BACKDATE_MS - SAFETY_MARGIN_MS) errors.push(`発生から${Math.floor(age / 3600000)}時間たっている（72時間の上限に近いか超えている）`);
  if (age < -5 * 60 * 1000) errors.push('発生時刻が未来になっている（時計か入力の誤り）');
  const entries = Object.entries(ev.params ?? {});
  if (entries.length > 25) errors.push('パラメータが25個を超えている');
  for (const [k, v] of entries) {
    if (!NAME_RE.test(k) || RESERVED_PREFIX.test(k)) errors.push(`パラメータ名が使えない: ${k}`);
    if (typeof v === 'string' && v.length > 100) errors.push(`値が100文字を超えている: ${k}`);
    const pii = findPii(v);
    if (pii.length) errors.push(`個人情報らしい値: ${k}（${pii.join(',')}）`);
  }
  for (const [k, v] of [['client_id', ev.clientId], ['user_id', ev.userId]]) {
    if (v && findPii(v).length) errors.push(`${k} に個人情報らしい値`);
  }
  return errors;
}

/** Measurement Protocol の本文を組み立てる */
export function buildBody(ev) {
  const body = {
    client_id: ev.clientId,
    timestamp_micros: ev.occurredAt.getTime() * 1000, // マイクロ秒（ミリ秒ではない）
    validation_behavior: 'ENFORCE_RECOMMENDATIONS',   // 72時間より前などは黙って直さず拒否させる
    events: [{ name: ev.name, params: { ...ev.params } }],
  };
  if (ev.userId) body.user_id = ev.userId;
  return body;
}

/** 送る。debug=true なら検証サーバーへ送り、validationMessages を返す */
export async function send(ev, { debug = false, env = process.env, fetchImpl = fetch } = {}) {
  const { GA4_MEASUREMENT_ID: mid, GA4_API_SECRET: secret } = env;
  if (!mid || !secret) throw new Error('GA4_MEASUREMENT_ID と GA4_API_SECRET をサーバーの環境変数に置く');
  const url = `${debug ? ENDPOINT.debug : ENDPOINT.prod}?measurement_id=${encodeURIComponent(mid)}&api_secret=${encodeURIComponent(secret)}`;
  const res = await fetchImpl(url, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify(buildBody(ev)),
  });
  // 本番の /mp/collect は、中身が壊れていてもエラーのコードを返さない。確かめられるのは「届いたか」だけ
  if (!debug) return { status: res.status };
  return { status: res.status, ...(await res.json()) };
}

// outbox.mjs — 送る予定のイベントを DB に積み、1回だけ送るための仕組み（SQLite で確認。PostgreSQL でも同じ考え方）
import { DatabaseSync } from 'node:sqlite';
import { EVENT_MAP, checkEvent, send } from './ga4-mp.mjs';

export function openDb(path = ':memory:') {
  const db = new DatabaseSync(path);
  db.exec(`
    CREATE TABLE IF NOT EXISTS bookings (
      id           TEXT PRIMARY KEY,           -- 予約番号（数字だけにしない。例 bk_7f3a9c）
      channel      TEXT NOT NULL,              -- web / line / phone
      ga_client_id TEXT,                       -- 予約の時点で保存した GA4 の client_id（無ければ NULL）
      member_key   TEXT,                       -- user_id に使う会員の仮名ID（氏名・電話・メールから作らない）
      created_at   TEXT NOT NULL               -- UTC の ISO 形式
    );
    CREATE TABLE IF NOT EXISTS ga4_outbox (
      booking_id  TEXT NOT NULL REFERENCES bookings(id),
      stage       TEXT NOT NULL,               -- booked / visited / contracted / lost
      occurred_at TEXT NOT NULL,               -- 出来事が起きた時刻（UTC）
      status      TEXT NOT NULL DEFAULT 'pending', -- pending / sending / sent / skipped / failed
      note        TEXT,
      updated_at  TEXT,
      UNIQUE (booking_id, stage)               -- 同じ予約の同じ段階は1行だけ＝二重送信の元を作らない
    );
  `);
  return db;
}

/** 管理画面で「来館」などを記録したときに呼ぶ。2回押されても行は増えない */
export function enqueue(db, bookingId, stage, occurredAt) {
  const r = db.prepare(
    `INSERT INTO ga4_outbox (booking_id, stage, occurred_at) VALUES (?, ?, ?)
     ON CONFLICT (booking_id, stage) DO NOTHING`,
  ).run(bookingId, stage, occurredAt.toISOString());
  return r.changes === 1; // false なら積み済み
}

/** 送る前に「送信中」へ変える。別の処理が先に取っていたら false */
function claim(db, bookingId, stage, now) {
  const r = db.prepare(
    `UPDATE ga4_outbox SET status = 'sending', updated_at = ?
      WHERE booking_id = ? AND stage = ? AND status = 'pending'`,
  ).run(now.toISOString(), bookingId, stage);
  return r.changes === 1;
}

function finish(db, bookingId, stage, status, note, now) {
  db.prepare(`UPDATE ga4_outbox SET status = ?, note = ?, updated_at = ? WHERE booking_id = ? AND stage = ?`)
    .run(status, note, now.toISOString(), bookingId, stage);
}

/** 数分おきに動かす送信の処理 */
export async function flush(db, { now = new Date(), debug = false, env, fetchImpl } = {}) {
  const rows = db.prepare(
    `SELECT o.booking_id, o.stage, o.occurred_at, b.channel, b.ga_client_id, b.member_key
       FROM ga4_outbox o JOIN bookings b ON b.id = o.booking_id
      WHERE o.status = 'pending' ORDER BY o.occurred_at`,
  ).all();
  const results = [];
  for (const r of rows) {
    if (!claim(db, r.booking_id, r.stage, now)) continue;
    const ev = {
      clientId: r.ga_client_id,
      userId: r.member_key ?? undefined,
      name: EVENT_MAP[r.stage],
      occurredAt: new Date(r.occurred_at),
      params: { lead_source: r.channel, booking_ref: r.booking_id },
    };
    const problems = checkEvent(ev, now);
    if (problems.length) {
      finish(db, r.booking_id, r.stage, 'skipped', problems.join(' / '), now);
      results.push({ id: r.booking_id, stage: r.stage, status: 'skipped', problems });
      continue;
    }
    try {
      const res = await send(ev, { debug, env, fetchImpl });
      const msgs = res.validationMessages ?? [];
      const status = res.status >= 200 && res.status < 300 && msgs.length === 0 ? 'sent' : 'failed';
      finish(db, r.booking_id, r.stage, status, msgs.map((m) => m.description).join(' / ') || null, now);
      results.push({ id: r.booking_id, stage: r.stage, status, http: res.status, validationMessages: msgs });
    } catch (e) {
      // 届いたか分からないときは pending に戻さず failed で止め、人が確かめてから戻す
      finish(db, r.booking_id, r.stage, 'failed', String(e.message), now);
      results.push({ id: r.booking_id, stage: r.stage, status: 'failed', error: e.message });
    }
  }
  return results;
}

// run-debug.mjs — 検証サーバー（/debug/mp/collect）だけを相手に、積む→点検→送るを通しで動かす
// 本番の /mp/collect には送らない。measurement_id と api_secret は仮の値
import { openDb, enqueue, flush } from './outbox.mjs';

const env = { GA4_MEASUREMENT_ID: 'G-XXXXXXXXXX', GA4_API_SECRET: 'placeholder-secret' };
const now = new Date();
const hoursAgo = (h) => new Date(now.getTime() - h * 3600_000);

const db = openDb();
const addBooking = db.prepare('INSERT INTO bookings VALUES (?, ?, ?, ?, ?)');
addBooking.run('bk_7f3a9c', 'web',   '1838291045.1759550000', 'm_2b8e41d0', hoursAgo(30).toISOString());
addBooking.run('bk_c41e02', 'line',  '402918377.1759552222',  null,         hoursAgo(5).toISOString());
addBooking.run('bk_9d0b7e', 'phone', null,                     null,         hoursAgo(3).toISOString());
addBooking.run('bk_e5a113', 'web',   '771023456.1759100000',  null,         hoursAgo(120).toISOString());
addBooking.run('[email protected]', 'web', '55501234.1759553333', null,     hoursAgo(2).toISOString()); // 悪い例：予約番号にメール

console.log('積む:', enqueue(db, 'bk_7f3a9c', 'visited', hoursAgo(2)));
console.log('同じ来館をもう一度積む:', enqueue(db, 'bk_7f3a9c', 'visited', hoursAgo(2)));
enqueue(db, 'bk_c41e02', 'booked', hoursAgo(5));
enqueue(db, 'bk_9d0b7e', 'visited', hoursAgo(1));
enqueue(db, 'bk_e5a113', 'contracted', hoursAgo(80)); // システムが止まっていて80時間前の成約が残っていた
enqueue(db, '[email protected]', 'visited', hoursAgo(1));

const results = await flush(db, { now, debug: true, env });
console.log(JSON.stringify(results, null, 2));

console.log('2回目の flush:', JSON.stringify(await flush(db, { now, debug: true, env })));
console.table(db.prepare('SELECT booking_id, stage, status FROM ga4_outbox').all());

// probe-debug.mjs — 手元の点検を通さずに、検証サーバーが何を見て何を見ないかを確かめる
const URL_ = 'https://www.google-analytics.com/debug/mp/collect?measurement_id=G-XXXXXXXXXX&api_secret=placeholder-secret';
const nowMs = Date.now();
const base = (ev, extra = {}) => ({ client_id: '1838291045.1759550000', ...extra, events: [ev] });
const cases = {
  '1. 正しい形': base({ name: 'working_lead', params: { lead_source: 'web', engagement_time_msec: 1 } }),
  '2. 80時間前・RELAXED（既定）': base({ name: 'working_lead' }, { timestamp_micros: (nowMs - 80 * 3600e3) * 1000 }),
  '3. 80時間前・ENFORCE_RECOMMENDATIONS': base({ name: 'working_lead' }, { timestamp_micros: (nowMs - 80 * 3600e3) * 1000, validation_behavior: 'ENFORCE_RECOMMENDATIONS' }),
  '4. ミリ秒のまま入れた': base({ name: 'working_lead' }, { timestamp_micros: nowMs, validation_behavior: 'ENFORCE_RECOMMENDATIONS' }),
  '5. 予約済みの名前': base({ name: 'session_start' }),
  '6. 値が101文字・ENFORCE': base({ name: 'working_lead', params: { note: 'あ'.repeat(101) } }, { validation_behavior: 'ENFORCE_RECOMMENDATIONS' }),
  '7. メールと電話をパラメータに入れた': base({ name: 'working_lead', params: { email: '[email protected]', tel: '090-1234-5678' } }, { user_id: '[email protected]' }),
};
for (const [label, body] of Object.entries(cases)) {
  const res = await fetch(URL_, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });
  const j = await res.json();
  console.log(`${label} → HTTP ${res.status}`);
  for (const m of j.validationMessages) console.log(`   ${m.validationCode} ${m.fieldPath}: ${m.description}`);
  if (!j.validationMessages.length) console.log('   （validationMessages は空）');
}