Tích hợp Google Ads — Đặc tả tính năng

I. Tổng quan

1. Vấn đề

  • Team marketing chạy Google Ads trên nhiều tài khoản, nhưng dữ liệu leads và chi phí nằm hoàn toàn trên Google Ads Manager, tách biệt với CRM — không thể biết lead nào từ Google Ads đã chuyển thành deal, và deal đó mang lại bao nhiêu doanh thu.
  • Nhân sự phải thủ công export data từ Google Ads rồi import vào CRM hàng ngày, tốn thời gian và dễ sai lệch.
  • Không có attribution rõ ràng: không biết chiến dịch Google Ads nào đóng góp nhiều nhất vào doanh thu thực tế.

2. Giải pháp

  • Tích hợp Google Ads API để đồng bộ tự động cấu trúc và chỉ số hiệu suất về Adahub.
  • Nhận lead từ Google Lead Form Extension qua webhook real-time, tự động tạo Contact trong CRM và phân bổ cho Telesale.
  • Đẩy Customer Match (danh sách KH từ CRM) lên Google Ads để tạo Custom Audience cho retargeting và Lookalike.
  • Báo cáo End-to-End Attribution: từ chi phí Google Ads đến doanh thu thực tế trong CRM.

3. Đối tượng

  • Marketing Manager: Xem tổng quan hiệu suất, phân bổ ngân sách giữa các chiến dịch.
  • Performance Marketing Specialist: Theo dõi chi tiết chỉ số từng Ad Group, từ khóa; tối ưu bidding.
  • Sales Manager: Nhận leads từ Google Ads, theo dõi tỷ lệ chuyển đổi từ lead sang deal.

4. Tầm nhìn / Insight

  • Tự động tạo chiến dịch Google Ads từ Adahub (hiện tại chỉ đọc, tương lai viết).
  • Tích hợp Smart Bidding: đẩy conversion data từ CRM về Google Ads để tối ưu bidding theo giá trị thực tế.
  • Cảnh báo tự động khi CTR giảm mạnh hoặc CPC tăng bất thường.

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

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

| # | Tính năng | Mô tả | |:—|:—|:—| | 1 | Kết nối tài khoản Google Ads | OAuth 2.0, quản lý nhiều tài khoản | | 2 | Đồng bộ cấu trúc chiến dịch | Campaign → Ad Group → Keyword/Ad | | 3 | Đồng bộ chỉ số hiệu suất | Impressions, Clicks, Spend, Conversions | | 4 | Nhận Lead từ Lead Form | Webhook real-time → tạo Contact CRM | | 5 | Quản lý ngân sách | Theo dõi budget, cảnh báo overspend | | 6 | Tạo đối tượng Customer Match | Đẩy danh sách KH từ CRM lên Google Ads | | 7 | Báo cáo Attribution | Từ click quảng cáo đến doanh thu CRM |

2. Đặc tả chi tiết

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

User story: Là một [Marketing Manager], tôi muốn [kết nối tài khoản Google Ads vào Adahub qua OAuth] để [quản lý tập trung mà không cần cung cấp thông tin đăng nhập].

  • Use case 1.1 (Happy path): Bấm “Kết nối Google Ads” → Redirect OAuth Google → Chọn tài khoản Ads Manager → Authorize → Adahub nhận access token và refresh token → Hiển thị danh sách tài khoản (Customer ID) đã kết nối.
  • Use case 1.2 (MCC – Manager Account): Nếu tài khoản là Google Ads Manager (MCC), hệ thống liệt kê toàn bộ sub-accounts để người dùng chọn đồng bộ account nào.
  • Use case 1.3 (Token hết hạn): Refresh token tự động khi access token expire. Nếu refresh token cũng hết hạn → Thông báo kết nối lại.

Thông tin tài khoản cần lưu:

Field Mô tả
Customer ID Google Ads Customer ID (xxx-xxx-xxxx)
Account Name Tên tài khoản quảng cáo
Currency Đơn vị tiền tệ (VND / USD)
Timezone Múi giờ báo cáo của tài khoản
MCC ID ID tài khoản manager (nếu có)

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

User story: Là một [Performance Marketer], tôi muốn [xem toàn bộ cấu trúc và chỉ số chiến dịch Google Ads trong Adahub] để [không phải mở Google Ads Manager riêng khi báo cáo].

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

Account
└── Campaign (Chiến dịch)
    └── Ad Group (Nhóm quảng cáo)
        ├── Keyword (Từ khóa)
        └── Ad (Mẫu quảng cáo)

Chỉ số đồng bộ theo ngày:

Cấp Chỉ số
Campaign Impressions, Clicks, CTR, Spend, CPC, Conversions, CPA, ROAS, Budget
Ad Group Impressions, Clicks, CTR, Spend, CPC, Conversions
Keyword Impressions, Clicks, CTR, Spend, CPC, Quality Score, Search Volume
Ad Impressions, Clicks, CTR, Spend

Tần suất đồng bộ:

  • Chỉ số ngày hôm qua: Đồng bộ tự động lúc 2:00 AM hàng ngày.
  • Chỉ số intraday (hôm nay): Có thể trigger đồng bộ thủ công, cập nhật mỗi 4 giờ.
  • Cấu trúc Campaign/Ad Group: Đồng bộ khi user vào trang hoặc theo lịch 1 lần/ngày.

Tính năng 4: Nhận Lead từ Google Lead Form Extension

User story: Là một [Sales Manager], tôi muốn [nhận lead từ Google Ads ngay khi KH điền form] để [Telesale gọi lại trong vòng 5 phút, tối đa tỷ lệ chuyển đổi].

Luồng nhận lead:

KH click Ad → Điền Google Lead Form → Google gọi Webhook → 
Adahub nhận payload → Tạo Contact → Phân bổ cho Telesale → 
Tạo Task "Gọi lại ngay" → Thông báo cho Agent
  • Use case 4.1 (Happy path): Google gửi webhook khi KH submit form → Adahub nhận trong ≤ 5 giây → Tạo Contact với đầy đủ thông tin (tên, SĐT, email, nguồn lead) → Tự động phân bổ cho agent Telesale theo quy tắc Round-Robin → Tạo Task “Gọi lại ngay” với deadline 30 phút.
  • Use case 4.2 (Trùng SĐT): SĐT đã tồn tại trong CRM → Cập nhật thông tin (không tạo mới), gắn thêm tag nguồn “Google Ads”, tạo Task follow-up.
  • Use case 4.3 (Webhook thất bại): Google retry webhook 3 lần (5 phút, 15 phút, 45 phút). Adahub phải trả về HTTP 200 trong ≤ 3 giây để tránh bị retry.

Cấu hình Lead Form Mapping:

Field Google Form Field CRM Bắt buộc
FULL_NAME Contact → Họ và tên ✅
PHONE_NUMBER Contact → Số điện thoại ✅
EMAIL Contact → Email ❌
CITY Contact → Thành phố ❌
Custom question Contact → Custom field ❌

Metadata tự động gắn:

  • Nguồn lead: Google Ads
  • Campaign ID, Ad Group ID, Ad ID, Keyword
  • Ngày nhận lead, Form ID

Tính năng 5: Quản lý ngân sách

  • Use case 5.1 (Cảnh báo ngưỡng): Khi chi tiêu chiến dịch đạt 80% budget hàng ngày → Gửi thông báo in-app và email cho Marketing Manager.
  • Use case 5.2 (Tổng hợp chi tiêu): Dashboard hiển thị tổng chi tiêu theo ngày/tuần/tháng, so sánh với budget đã đặt, biểu đồ burn rate.
  • Use case 5.3 (Cập nhật budget từ Adahub): (Tính năng nâng cao) Cho phép điều chỉnh Daily Budget của Campaign trực tiếp từ Adahub mà không vào Google Ads Manager.

Tính năng 6: Tạo đối tượng Customer Match

User story: Là một [Performance Marketer], tôi muốn [đẩy danh sách KH từ CRM lên Google Ads] để [retargeting KH cũ hoặc tìm Lookalike audience chất lượng cao].

  • Use case 6.1 (Tạo Customer Match list): Chọn Segment KH trong CRM (ví dụ: KH đã mua trong 3 tháng) → Hệ thống hash SĐT/Email (SHA-256) → Đẩy lên Google Ads API → Google tạo Customer Match audience.
  • Use case 6.2 (Sync tự động): Cấu hình sync lịch: mỗi ngày hoặc mỗi tuần, danh sách KH trong Segment được cập nhật tự động lên Google Ads.
  • Use case 6.3 (Lookalike – Similar Audiences): Sau khi tạo Customer Match, Google tự động tạo Similar Audiences — không cần thao tác thêm từ Adahub.

Yêu cầu bảo mật: SĐT và Email PHẢI được hash SHA-256 trước khi gửi lên Google Ads API. Không lưu dữ liệu hash sau khi upload.

3. Danh sách nghiệp vụ

  • Mỗi workspace có thể kết nối nhiều tài khoản Google Ads (nhiều Customer ID).
  • Dữ liệu chỉ số được đồng bộ về Adahub chỉ để đọc và báo cáo — không sửa dữ liệu trên Google Ads từ Adahub (ngoại trừ tính năng quản lý ngân sách nâng cao).
  • Lead từ Google Ads gắn UTM params: utm_source=google, utm_medium=cpc, utm_campaign={campaign_name}.
  • Attribution window mặc định: 30 ngày (configurable). Nghĩa là deal được tạo trong vòng 30 ngày kể từ khi lead được nhận vẫn được tính là conversion của chiến dịch đó.
  • Customer Match: chỉ upload dữ liệu đã hash. Tuân thủ Google Customer Match Policy và GDPR/PDPA.

4. Giao diện

  • Tab Tài khoản: Danh sách tài khoản Google Ads đã kết nối, trạng thái sync, thời gian sync gần nhất.
  • Tab Chiến dịch: Bảng Campaign với metrics tổng hợp, drill-down xuống Ad Group và Keyword.
  • Tab Leads: Danh sách leads từ Google Ads, trạng thái phân bổ, trạng thái xử lý.
  • Tab Đối tượng: Danh sách Customer Match list, số lượng khớp, trạng thái.
  • Dashboard Attribution: Biểu đồ funnel: Clicks → Leads → Contacts → Deals → Revenue.

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

  • Webhook latency: Xử lý lead webhook trong ≤ 5 giây và trả về HTTP 200.
  • Sync hiệu năng: Đồng bộ chỉ số của tài khoản có 100+ campaigns trong ≤ 5 phút.
  • Rate limit: Tuân thủ Google Ads API rate limit (1,000 requests/1,000 customers/giờ theo Developer Token).
  • Bảo mật: Không lưu plain-text SĐT/Email sau khi hash. Refresh token được mã hóa AES-256 khi lưu.
  • Retry policy: Nếu Google Ads API trả về 5xx, retry tối đa 3 lần với backoff.

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

  • Google Ads API (v17+): Đọc dữ liệu campaign, Ad Group, Keyword metrics; upload Customer Match; đọc Lead Form data.
  • Google OAuth 2.0: Xác thực và phân quyền truy cập tài khoản Ads.
  • CRM – Contact Management: Tạo Contact từ lead, tra cứu trùng SĐT.
  • Chiến dịch Telesale: Nhận leads và tạo phân bổ cho agent.
  • Adaflow: Trigger “Khi có lead mới từ Google Ads” để tự động hóa luồng xử lý lead.
  • Dashboard Module: Tổng hợp metrics từ tất cả kênh quảng cáo.

V. API Contract (Dev viết)

API 1: Kết nối tài khoản Google Ads

  • Method & Endpoint: POST /api/v1/integrations/google-ads/connect
  • Request Body: { "authorization_code": "4/0Ae..." } (từ OAuth callback)
  • Response 200: { "account_id": "123-456-7890", "account_name": "Company XYZ Ads" }

API 2: Webhook nhận Lead từ Google

  • Method & Endpoint: POST /api/v1/webhooks/google-ads/lead (Google gọi vào)
  • Payload (Google format): 
    {
  "lead_id": "ggl_lead_001",
  "campaign_id": "1234567890",
  "form_id": "9876543210",
  "user_column_data": [
    { "column_id": "FULL_NAME", "string_value": "Nguyễn Văn A" },
    { "column_id": "PHONE_NUMBER", "string_value": "+84901234567" }
  ]
}
  • Response 200: { "status": "received" }

API 3: Lấy metrics chiến dịch

  • Method & Endpoint: GET /api/v1/integrations/google-ads/{account_id}/campaigns?date_range=LAST_30_DAYS
  • Response 200: 
    {
  "campaigns": [
    {
      "id": "1234567890",
      "name": "Brand Search - Vietnam",
      "status": "ENABLED",
      "spend": 15000000,
      "clicks": 2500,
      "impressions": 85000,
      "ctr": 2.94,
      "conversions": 45,
      "cpa": 333333
    }
  ]
}

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

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

  • TC1.1: OAuth thành công → Tài khoản hiển thị trong danh sách, trạng thái “Đã kết nối”.
  • TC1.2: User revoke quyền trên Google → Adahub phát hiện lỗi 401 → Hiện thông báo “Kết nối đã bị hủy, vui lòng kết nối lại”.

Nhận Lead:

  • TC2.1: Google gửi webhook lead → Contact được tạo trong CRM trong ≤ 5 giây.
  • TC2.2: Lead có SĐT đã tồn tại → Cập nhật Contact, không tạo mới, Task follow-up được tạo.
  • TC2.3: Webhook timeout (Adahub không trả 200 kịp) → Google retry → Adahub xử lý idempotent (không tạo lead trùng).

Đồng bộ metrics:

  • TC3.1: Trigger sync thủ công → Dữ liệu metrics hôm qua hiển thị đúng với Google Ads Manager.
  • TC3.2: Tài khoản có currency VND → Số liệu hiển thị đúng đơn vị VND, không bị nhân nhầm tỷ giá.

Customer Match:

  • TC4.1: Upload 1,000 SĐT → Google xác nhận nhận được, Customer Match list tạo thành công.
  • TC4.2: Upload thất bại một phần → Hệ thống báo cáo số lượng thành công/thất bại.