Tích hợp Facebook Ads (Meta) — Đặc tả tính năng

I. Tổng quan

1. Vấn đề

Facebook/Instagram là kênh quảng cáo lớn nhất Việt Nam, nhưng dữ liệu lead từ Facebook Lead Ads thường bị trễ 15–30 phút (do export thủ công) trước khi đến tay Telesale — trong khi KH “nóng” nhất ngay sau khi điền form.
Không có cầu nối giữa thành tích quảng cáo trên Meta (reach, spend) và kết quả kinh doanh thực tế trong CRM (deal, doanh thu).
Custom Audience và Lookalike trên Facebook được tạo thủ công và cập nhật không thường xuyên, dẫn đến retargeting lỗi thời.

2. Giải pháp

Tích hợp Meta Marketing API để đồng bộ cấu trúc và chỉ số chiến dịch về Adahub.
Nhận lead từ Facebook Lead Ads (Instant Form) qua webhook real-time (Webhook Subscriptions API) — lead được xử lý trong vòng 5 giây.
Đẩy Custom Audience và Lookalike Audience từ CRM lên Facebook tự động theo lịch.
Tích hợp Facebook Conversions API (CAPI) để gửi conversion event từ CRM về Meta — cải thiện độ chính xác tracking khi iOS 14+ block pixel.

3. Đối tượng

Marketing Manager: Quản lý ngân sách và hiệu suất chiến dịch.
Performance Marketing Specialist: Tối ưu Ad Set, audience, creative.
Sales Manager: Xử lý lead từ Facebook, tracking tỷ lệ chuyển đổi.
Data/Growth Team: Xây dựng Custom Audience và phân tích attribution.

4. Tầm nhìn / Insight

Tích hợp Conversions API (CAPI) server-side để bypass iOS tracking limitation.
Auto-create Lookalike Audience từ KH đã chốt deal (Seed Audience chất lượng cao).
A/B test creative ngay trong Adahub mà không cần vào Ads Manager.

II. Yêu cầu chức năng

1. Danh sách tính năng

2. Đặc tả chi tiết

Tính năng 1: Kết nối tài khoản Meta Business

User story: Là một [Marketing Manager], tôi muốn [kết nối Meta Business qua OAuth] để [quản lý nhiều tài khoản quảng cáo của công ty từ một nơi].

Use case 1.1 (Happy path): Bấm “Kết nối Facebook” → OAuth Facebook Login → Cấp quyền ads_read, leads_retrieval, ads_management → Chọn Ad Account và Facebook Page cần kết nối → Xác nhận.
Use case 1.2 (Business Manager): Nếu user có nhiều Business Manager, liệt kê để chọn đúng BM cần kết nối.
Use case 1.3 (Quyền không đủ): User không cấp đủ quyền cần thiết → Hiển thị danh sách quyền bị thiếu và hướng dẫn cấp lại.

Permissions cần thiết:

Permission	Mục đích
`ads_read`	Đọc cấu trúc và chỉ số chiến dịch
`ads_management`	Tạo Custom Audience, điều chỉnh budget
`leads_retrieval`	Lấy lead từ Lead Ads
`pages_read_engagement`	Xác thực Page kết nối

Tính năng 2 & 3: Đồng bộ cấu trúc & Chỉ số hiệu suất

Cấu trúc đồng bộ:

Ad Account
└── Campaign (Chiến dịch)
    └── Ad Set (Nhóm quảng cáo)  ← Audience, Placement, Budget
        └── Ad (Mẫu quảng cáo)  ← Creative, CTA

Chỉ số đồng bộ:

Cấp	Chỉ số
Campaign	Reach, Impressions, Clicks, CTR, Spend, Budget, Leads, CPL, ROAS
Ad Set	Reach, Impressions, Clicks, Spend, Frequency, CPM, Leads
Ad	Impressions, Clicks, CTR, Spend, Video Views (nếu video ad)

Breakdowns (phân tích theo chiều):

Theo ngày, tuần, tháng
Theo thiết bị (Mobile / Desktop)
Theo placement (Facebook Feed / Instagram / Audience Network)
Theo tuổi & giới tính (nếu được phép theo chính sách Meta)

Tính năng 4: Nhận Lead từ Facebook Lead Ads (Real-time)

User story: Là một [Sales Manager], tôi muốn [nhận lead từ Facebook Instant Form ngay lập tức] để [Telesale gọi lại trong vòng 5 phút, tối đa tỷ lệ chuyển đổi].

Luồng nhận lead real-time:

KH click Ad → Điền Facebook Instant Form → 
Meta gửi Webhook (leadgen event) → 
Adahub nhận event → Gọi Leads API lấy thông tin → 
Tạo Contact → Phân bổ Telesale → Tạo Task

Lưu ý kỹ thuật: Facebook Webhook chỉ gửi lead_id, không gửi thông tin lead. Adahub phải gọi API GET /v18.0/{form_id}/leads/{lead_id} để lấy dữ liệu thực tế.

Use case 4.1 (Happy path): Webhook nhận lead_id → Adahub gọi Leads API trong ≤ 2 giây → Tạo Contact → Phân bổ agent → Tạo Task “Gọi lại ngay”.
Use case 4.2 (Trùng SĐT): SĐT đã tồn tại → Merge/update Contact, tạo ghi chú “Lead mới từ Facebook Ads”.
Use case 4.3 (Page resubscribe): Webhook subscription cho Page bị mất → Hệ thống cảnh báo, tự động resubscribe.

Cấu hình Form Field Mapping:

Facebook Form Field	CRM Field
`full_name`	Contact → Họ và tên
`phone_number`	Contact → Số điện thoại
`email`	Contact → Email
`city`	Contact → Thành phố
Custom questions	Custom field tương ứng

Metadata tự động gắn:

Nguồn: Facebook Ads
Page ID, Form ID, Ad ID, Campaign ID, Ad Set ID
Thời gian nhận lead

Tính năng 5 & 6: Custom Audience & Lookalike Audience

User story: Là một [Performance Marketer], tôi muốn [đẩy danh sách KH chất lượng cao lên Facebook để retargeting và tạo Lookalike] để [tiếp cận đúng đối tượng tiềm năng mà không cần tìm thủ công].

Custom Audience từ CRM:

Use case 5.1 (Tạo audience): Chọn Segment KH trong CRM → Hệ thống hash SĐT/Email (SHA-256) → Upload lên Meta Custom Audience API → Meta xử lý và trả về match rate.
Use case 5.2 (Sync tự động): Cấu hình lịch sync: daily/weekly → Danh sách KH trong Segment được cập nhật tự động lên audience trên Meta.

Lookalike Audience:

Use case 6.1: Chọn Custom Audience đã tạo làm Seed → Chọn quốc gia và kích thước audience (1–10% dân số) → Hệ thống gọi Meta API tạo Lookalike.

Loại Custom Audience phổ biến từ CRM:

Audience	Segment CRM tương ứng	Mục đích
KH đã mua hàng	Có ít nhất 1 Deal Closed	Upsell / Cross-sell
KH VIP	Deal value > 10 triệu	Retention, loyalty offer
Lead chưa chuyển đổi	Lead nhận > 30 ngày, chưa có Deal	Re-engagement
KH đã churned	Không tương tác > 6 tháng	Win-back campaign

Tính năng 7: Facebook Conversions API (CAPI)

User story: Là một [Growth Marketer], tôi muốn [gửi conversion event từ CRM về Meta server-side] để [tối ưu thuật toán Meta Ads và đo lường chính xác hơn sau iOS 14+].

Conversion Events gửi về Meta:

Sự kiện trong CRM	Meta Event tương ứng
Contact mới được tạo từ Lead Ads	`Lead`
Telesale tạo Deal mới	`InitiateCheckout`
Deal chuyển sang `Closed Won`	`Purchase` với `value` và `currency`
KH hoàn thành onboarding	`CompleteRegistration`

Use case 7.1: Deal chuyển sang Closed Won → Adahub gửi event Purchase lên CAPI với value, currency, event_id, event_source_url, user_data (hashed phone/email) → Meta nhận và báo cáo conversion.
Use case 7.2 (Deduplication): Pixel và CAPI cùng gửi cùng event → Meta sử dụng event_id để deduplicate, tránh tính double conversion.

Tính năng 8: Báo cáo Attribution

Attribution Model hỗ trợ:

Model	Mô tả
Last Click	Gán 100% credit cho lần click cuối
First Click	Gán 100% credit cho lần click đầu
Linear	Chia đều credit cho tất cả touchpoints

Báo cáo Attribution hiển thị:

Số Lead → Contact → Deal → Revenue từng chiến dịch Facebook
CPL (Cost Per Lead), CAC (Customer Acquisition Cost), ROAS thực tế từ CRM
Comparison: ROAS theo Facebook vs ROAS theo CRM (data-driven)

3. Danh sách nghiệp vụ

Mỗi workspace có thể kết nối nhiều Ad Account Meta (ví dụ: ad account VN, ad account HCM).
Webhook Subscription phải được đặt ở cấp App (không phải Page) để nhận lead từ nhiều Page.
Custom Audience: SĐT/Email PHẢI hash SHA-256 trước khi upload. Tuân thủ Meta Custom Audience Terms of Service và PDPA.
CAPI event phải gửi kèm event_time chính xác (Unix timestamp) để Meta deduplicate đúng.
Attribution window mặc định: 7 ngày sau click, 1 ngày sau view (theo chuẩn Meta attribution mới).
Không lưu trữ data hash sau khi đã upload lên Meta.

4. Giao diện

Tab Tài khoản: Danh sách Ad Account đã kết nối, trạng thái webhook, Page đã subscribe.
Tab Chiến dịch: Bảng Campaign → Ad Set → Ad, với metrics tổng hợp. Bộ lọc theo Campaign Objective.
Tab Leads: Danh sách lead real-time, trạng thái phân bổ, thời gian phản hồi trung bình.
Tab Audiences: Danh sách Custom/Lookalike Audience, match rate, ngày sync gần nhất.
Tab CAPI: Log các conversion event đã gửi, trạng thái, event match quality score.

III. Yêu cầu phi chức năng

Lead latency: Từ khi KH submit form đến khi Contact được tạo trong CRM ≤ 10 giây (end-to-end).
Webhook availability: Adahub phải trả về HTTP 200 với Facebook Webhook trong ≤ 5 giây (Meta timeout là 20 giây, nhưng phải xử lý async nhanh).
Rate limit Meta API: Tuân thủ rate limit theo Business Use Case (BUC): tránh bị throttle khi đồng bộ nhiều chiến dịch.
CAPI event match quality: Phấn đấu Event Match Quality Score ≥ 7/10 bằng cách gửi đầy đủ user data.
Uptime webhook: Hệ thống xử lý webhook phải có uptime ≥ 99.9% (downtime = mất lead).

IV. Dependency (liên quan & phụ thuộc)

Meta Marketing API (v18.0+): Đọc cấu trúc campaign, metrics; tạo Custom/Lookalike Audience; Lead Form API.
Meta Webhooks (Leads): Subscribe sự kiện leadgen từ Facebook Page.
Facebook Conversions API (CAPI): Gửi server-side conversion events.
CRM – Contact Management: Tạo Contact từ lead, tra cứu trùng SĐT.
Chiến dịch Telesale: Nhận và phân bổ lead từ Facebook.
Deal Module: Trigger CAPI event khi Deal thay đổi trạng thái.
Adaflow: Trigger “Khi có lead mới từ Facebook Ads”.

V. API Contract (Dev viết)

API 1: Kết nối Meta Business

Method & Endpoint: POST /api/v1/integrations/meta/connect
Request Body: { "access_token": "EAAxxxxx...", "ad_account_id": "act_123456789" }
Response 200: { "connected": true, "ad_account_name": "Company Vietnam Ads" }

API 2: Webhook từ Facebook Lead Ads

Method & Endpoint: POST /api/v1/webhooks/meta/leads (Meta gọi vào)

Payload (Meta format):

{
  "object": "page",
  "entry": [{
    "id": "page_id",
    "changes": [{
      "field": "leadgen",
      "value": {
        "lead_id": "123456789",
        "page_id": "987654321",
        "form_id": "111222333",
        "ad_id": "444555666"
      }
    }]
  }]
}

Response 200: { "status": "ok" } (phải trả trong ≤ 5 giây)

API 3: Gửi Conversion Event qua CAPI

Method & Endpoint: POST /api/v1/integrations/meta/conversions (Adahub gọi Meta)

Payload gửi đến Meta:

{
  "data": [{
    "event_name": "Purchase",
    "event_time": 1720310400,
    "event_id": "deal_001_closed",
    "user_data": {
      "ph": ["sha256_hashed_phone"],
      "em": ["sha256_hashed_email"]
    },
    "custom_data": {
      "value": 5000000,
      "currency": "VND"
    }
  }]
}

VI. Test case (BA hoặc Tester viết)

Kết nối tài khoản:

TC1.1: Kết nối OAuth thành công → Ad Account hiển thị, trạng thái “Đã kết nối”, webhook active.
TC1.2: Thiếu permission leads_retrieval → Hiển thị cụ thể permission bị thiếu và link hướng dẫn cấp.

Nhận Lead real-time:

TC2.1: KH submit form → Contact được tạo trong CRM trong ≤ 10 giây.
TC2.2: Lead trùng SĐT → Contact cũ được cập nhật, không tạo mới, Task mới được tạo.
TC2.3: Adahub downtime 2 phút → Facebook retry → Khi lên lại, lead được xử lý đúng (idempotent).

Custom Audience:

TC3.1: Upload 5,000 KH → Match rate > 60% sau khi Meta xử lý.
TC3.2: Upload file có SĐT sai format → Hệ thống báo lỗi, không upload.

Conversions API:

TC4.1: Deal Closed Won → CAPI gửi event Purchase → Meta Event Manager xác nhận nhận được.
TC4.2: Pixel và CAPI cùng gửi event Lead với cùng event_id → Meta chỉ tính 1 conversion.