moreminimore-astroreal/CAPI-SETUP.md

Meta CAPI + Google Enhanced Conversions Setup

สรุปการเปลี่ยนแปลง

1. Client-side Changes

src/components/PageShell.astro

• ✅ เพิ่ม allow_enhanced_conversions: true ใน GA4 config
• ✅ เพิ่ม event_id สำหรับ Meta Pixel PageView
• ✅ เพิ่ม utility functions: generateEventId(), getMetaCookies(), sendConversion()

src/scripts/home.js

• ✅ เพิ่ม Lead event tracking หลัง form submit สำเร็จ
• ✅ Parse ชื่อเป็น firstName + lastName
• ✅ ส่ง email, phone, และ problems[0] ไปยัง /api/conversions

2. Server-side Changes

server.js

• ✅ เพิ่ม import crypto from 'node:crypto' สำหรับ SHA-256 hashing
• ✅ เพิ่ม /api/conversions endpoint:
  • Meta CAPI: ส่ง event พร้อม hashed PII → graph.facebook.com/v22.0/{pixel_id}/events
  • Google Measurement Protocol: ส่ง event พร้อม hashed user_properties → GA4 MP endpoint
• ✅ Logging: console.info/warn สำหรับ debug
• ✅ Graceful degradation: ถ้าไม่มี token/secret ก็ skip แต่ไม่ error

Dockerfile

• ✅ เพิ่ม env vars documentation: META_PIXEL_ID, META_ACCESS_TOKEN, GA4_MEASUREMENT_ID, GA4_API_SECRET

.env.example (ใหม่)

• ✅ Template สำหรับ environment variables

Environment Variables ที่ต้องตั้ง

# Meta Conversions API
META_PIXEL_ID=418349260078648
META_ACCESS_TOKEN=EAAOuKluwl6ABRZC5cjHD8e89zcf5xrUbJrfjYxaTYs2afZBSmJ4uQZARhmYNsv3X7pZBh5fZCpqYlJuaZCMtoKrGBDGiAFR0CSTV3MKOgDjFQSJcKcE8VPW5jTEjlLdchrgDh2VEfF7By3jdAEawmAw0J7hTk7iKOeIZB2s9ZCiXVqScL4bXu2Pq9gfXL3UCjcgZA9wZDZD

# Google Analytics 4 + Enhanced Conversions
GA4_MEASUREMENT_ID=G-74BHREDLC3
GA4_API_SECRET=v1mm1tE6T2mjv2RbqW2Ejg

Event Flow

User submits form
       │
       ├─ Client-side (immediate)
       │  ├─ fbq('track', 'Lead', {...}, {eventID: xxx})
       │  └─ gtag('event', 'Lead', {...})
       │
       └─ Server-side (fetch /api/conversions)
          ├─ Meta CAPI
          │  └─ POST graph.facebook.com/v22.0/418349260078648/events
          │     - event_name: Lead
          │     - event_id: xxx (dedup with client)
          │     - user_data: hashed email, phone, name
          │     - fbp, fbc cookies
          │
          └─ Google Measurement Protocol
             └─ POST www.google-analytics.com/mp/collect
                - event: lead
                - client_id: fbp or random UUID
                - user_properties: hashed email, phone

การทดสอบ

1. Local Development

# 1. ตั้ง env vars
export META_ACCESS_TOKEN="EAAOuK..."
export GA4_API_SECRET="v1mm1tE6T2mjv2RbqW2Ejg"

# 2. Build + Start
npm run build
node server.js

# 3. เปิด http://localhost:4321
# 4. กด "ส่งโจทย์ให้เราดู" → กรอกฟอร์ม → Submit
# 5. เช็ค console logs:
#    [api/conversions] Meta CAPI: {"events_received":1,"..."}
#    [api/conversions] Google MP: {"status":204,"ok":true}

2. Verify Meta CAPI

1. ไปที่ Meta Events Manager: https://business.facebook.com/events_manager2/list/pixel/418349260078648
2. เลือก Test Events tab
3. ส่ง form จากเว็บ → ดู event ปรากฏ real-time
4. เช็ค Event Match Quality (EMQ) ≥ 6.0

3. Verify Google Enhanced Conversions

1. ไปที่ GA4 → Reports → Realtime
2. ส่ง form → ดู event lead ปรากฏภายใน 30 วินาที
3. ไปที่ Admin → Data Display → DebugView (ถ้าต้องการ debug โหมด)

Deduplication

• event_id ถูกสร้างที่ client (generateEventId())
• ส่งไปทั้ง:
  • Client-side Pixel: fbq('track', 'Lead', {}, {eventID: xxx})
  • Server-side CAPI: event_id: xxx
• Meta จะ dedupe event ที่มี event_id เดียวกันภายใน 48 ชั่วโมง
• Expected dedup rate: ≥90%

Security & Privacy

• ✅ PII Hashing: email, phone, name ถูก SHA-256 hash ก่อนส่ง server-side
• ✅ No PII in client-side events: custom_data มีแค่ content_name, content_category
• ✅ IP + User-Agent: server populate จาก request headers
• ✅ Honeypot: field website ใน form กันบอท

Next Steps

1. ✅ Deploy to EasyPanel พร้อม env vars
2. ⏳ รอ 24-48 ชั่วโมง เพื่อให้ Meta/Google เก็บข้อมูลพอ
3. ⏳ เช็ค Event Match Quality ใน Events Manager
4. ⏳ เช็ค Deduplication rate ใน Events Manager → Diagnostics
5. ⏳ ตั้ง Conversion Goal ใน Google Ads (ถ้าใช้)

Troubleshooting

Meta CAPI ไม่เห็น event:

• เช็ค META_ACCESS_TOKEN ตั้งถูกต้องไหม
• เช็ค server logs: [api/conversions] Meta CAPI: {...}
• เช็ค Test Events ใน Events Manager

Google MP ไม่เห็น event:

• เช็ค GA4_API_SECRET ตั้งถูกต้องไหม
• เช็ค server logs: [api/conversions] Google MP: {"status":204}
• status 204 = success (no content response)

EMQ ต่ำ (<6.0):

• เพิ่มข้อมูล: city, state, zip, gender, date_of_birth (ถ้ามี)
• เช็ค email/phone format ถูกต้องไหม
• เช็ค fbp/fbc cookies ส่งมาไหม

---

📊 File Changes:

• Dockerfile: +4 lines (env vars doc)
• server.js: +124 lines (CAPI endpoint + hashing)
• src/components/PageShell.astro: +60 lines (utilities + event_id)
• src/scripts/home.js: +17 lines (Lead tracking)
• .env.example: ใหม่ (template)

✅ Build: ผ่าน (1.56s, 30 pages) ✅ Lint: ผ่าน (no errors)