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 ที่ต้องตั้ง

```bash
# 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

```bash
# 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)