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

I. Tổng quan

1. Vấn đề

• TikTok đang là kênh quảng cáo tăng trưởng nhanh nhất tại Việt Nam, đặc biệt với tệp khách hàng Gen Z và Millennials, nhưng team marketing chưa có công cụ tích hợp TikTok Ads vào luồng quản lý lead và báo cáo CRM.
• Lead từ TikTok Lead Generation Form phải export thủ công từ TikTok Ads Manager, gây trễ 30–60 phút trước khi đến Telesale.
• Hiệu suất video (view rate, completion rate) là chỉ số quan trọng với TikTok nhưng không được theo dõi cùng với dữ liệu kinh doanh trong CRM.

2. Giải pháp

• Tích hợp TikTok Marketing API để:
  • Đồng bộ cấu trúc và chỉ số chiến dịch TikTok Ads về Adahub.
  • Nhận lead từ TikTok Lead Generation Form qua webhook real-time.
  • Theo dõi Video Performance cùng với conversion data từ CRM.
  • Tạo Custom Audience từ dữ liệu KH trong CRM.

3. Đối tượng

• Marketing Manager: Tổng quan hiệu suất và ngân sách TikTok Ads.
• Performance Marketing Specialist: Theo dõi Video Performance, tối ưu Ad Group.
• Content Marketing Team: Phân tích video nào hiệu quả nhất để ra quyết định sản xuất.
• Sales Manager: Tiếp nhận và xử lý leads từ TikTok.

4. Tầm nhìn / Insight

• TikTok Events API (tương đương Facebook CAPI): gửi conversion server-side để tối ưu bidding.
• Tích hợp TikTok Shop: sync đơn hàng từ TikTok Shop về CRM.
• Content performance analytics: so sánh video organic vs paid performance.
• Spark Ads integration: boost video organic từ brand account qua Adahub.

---

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 TikTok Ads | OAuth, quản lý nhiều Ad Accounts | | 2 | Đồng bộ cấu trúc chiến dịch | Campaign → Ad Group → Ad | | 3 | Đồng bộ chỉ số hiệu suất | Reach, Impressions, Clicks, Spend, Leads, CPL | | 4 | Theo dõi Video Performance | View, Completion Rate, Engagement | | 5 | Nhận Lead từ Lead Generation | Webhook real-time → Contact CRM | | 6 | Tạo Custom Audience | Đẩy danh sách KH từ CRM lên TikTok | | 7 | Báo cáo tổng hợp | Attribution từ TikTok → doanh thu CRM |

2. Đặc tả chi tiết

---

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

User story: Là một [Marketing Manager], tôi muốn [kết nối TikTok Ads Manager qua OAuth] để [quản lý chiến dịch TikTok trong cùng giao diện với Google và Meta].

• Use case 1.1 (Happy path): Bấm “Kết nối TikTok Ads” → Redirect TikTok OAuth → Cấp quyền → Chọn Advertiser Account → Xác nhận kết nối.
• Use case 1.2 (Business Center): Nếu user thuộc TikTok Business Center, liệt kê các Advertiser Account để chọn đồng bộ.

Permissions cần thiết:

Permission (Scope)	Mục đích
advertiser.report.read	Đọc chỉ số hiệu suất
campaign.read	Đọc cấu trúc Campaign/Ad Group/Ad
audience.write	Tạo và upload Custom Audience
lead.read	Lấy dữ liệu lead từ Lead Generation

---

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

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

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

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

Cấp	Chỉ số
Campaign	Reach, Impressions, Clicks, CTR, Spend, Budget, Conversions, CPL, CPA
Ad Group	Reach, Impressions, Clicks, Spend, Frequency, CPM
Ad (Video)	Impressions, Clicks, Spend, Video Views, Video Play Rate, 6s View Rate, Completion Rate

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

• Theo ngày, tuần, tháng
• Theo thiết bị (Android / iOS)
• Theo placement (TikTok Feed / Pangle)
• Theo độ tuổi & giới tính (nếu được phép)
• Theo khu vực địa lý

---

Tính năng 4: Theo dõi Video Performance

Đây là tính năng đặc thù của TikTok so với Google và Facebook, vì TikTok là nền tảng video-first.

User story: Là một [Content Marketing Manager], tôi muốn [xem hiệu suất từng video quảng cáo theo nhiều chỉ số video] để [biết loại content nào hiệu quả nhất để tập trung sản xuất].

Chỉ số Video Performance chuyên sâu:

Chỉ số	Mô tả
Video Views	Tổng lượt xem (tính từ ≥ 2 giây)
Video Play Rate	% impressions dẫn đến lượt xem
6s View Rate	% người xem đến giây thứ 6 (điểm quan trọng của TikTok)
Video Completion Rate	% người xem đến hết video
Average Watch Time	Thời gian xem trung bình (giây)
Engagement Rate	(Like + Comment + Share + Follow) / Impressions
Profile Visit	Lượt vào profile từ quảng cáo

Dashboard Video Performance:

• So sánh các video ads trong cùng chiến dịch: bảng xếp hạng theo Completion Rate, CPL.
• Biểu đồ “Viewing Funnel”: Impressions → Views → 6s → Complete.
• Gợi ý tối ưu: Video có Completion Rate thấp → cảnh báo cần cải thiện 3 giây đầu.

---

Tính năng 5: Nhận Lead từ TikTok Lead Generation Form

User story: Là một [Sales Manager], tôi muốn [nhận lead từ TikTok Instant Form ngay khi KH điền] để [Telesale phản hồi nhanh nhất có thể].

Luồng nhận lead:

KH xem video Ad → Bấm CTA → TikTok Instant Form → Submit →
TikTok gọi Webhook → Adahub nhận → Tạo Contact → 
Phân bổ Telesale → Task "Gọi lại ngay"

• Use case 5.1 (Happy path): Webhook nhận notification lead mới → Adahub gọi TikTok Lead API lấy thông tin → Tạo Contact trong CRM trong ≤ 10 giây.
• Use case 5.2 (Trùng SĐT): SĐT đã tồn tại trong CRM → Update Contact, thêm ghi chú nguồn “TikTok Ads”, tạo Task.
• Use case 5.3 (Webhook missed): Adahub implement scheduled pull: mỗi 15 phút kiểm tra và pull lead chưa xử lý từ TikTok API (safety net cho trường hợp webhook bị miss).

Cấu hình Form Field Mapping:

TikTok Form Field	CRM Field
name	Contact → Họ và tên
phone_number	Contact → Số điện thoại
email	Contact → Email
Custom questions	Custom field tương ứng

Metadata tự động gắn:

• Nguồn lead: TikTok Ads
• Campaign ID, Ad Group ID, Ad ID
• Form ID, Thời gian submit

---

Tính năng 6: Tạo Custom Audience

User story: Là một [Performance Marketer], tôi muốn [đẩy danh sách KH CRM lên TikTok] để [retargeting KH cũ và tìm Lookalike audience trên nền tảng TikTok].

• Use case 6.1 (Customer File Audience): Chọn Segment KH trong CRM → Hash SĐT/Email (SHA-256) → Upload lên TikTok Audience API → TikTok trả về match rate và kích thước audience.
• Use case 6.2 (Sync tự động): Cấu hình sync tự động theo lịch → Audience được cập nhật khi Segment CRM thay đổi.
• Use case 6.3 (Lookalike): Từ Custom Audience đã có → Tạo Lookalike với kích thước 1%–20% của Việt Nam.

TikTok Custom Audience Types hỗ trợ:

Loại	Cách tạo	Mục đích
Customer File	Upload từ CRM	Retargeting KH cũ
Lookalike	Từ Customer File	Tìm KH tiềm năng tương tự

Yêu cầu bảo mật: Hash SHA-256 trước khi upload. Tối thiểu 1,000 KH để tạo Lookalike.

---

Tính năng 7: Báo cáo tổng hợp & Attribution

So sánh hiệu quả chiến dịch:

Chiều phân tích	Chỉ số
Theo chiến dịch	CPL, Tỷ lệ chuyển đổi lead → deal, Revenue
Theo nội dung video	Video tốt nhất (Completion Rate cao, CPL thấp)
Cross-platform	So sánh TikTok vs Facebook vs Google: CPL, CAC, ROAS

Attribution:

• Attribution window mặc định: 7 ngày sau click, 1 ngày sau view.
• Gắn UTM params: utm_source=tiktok, utm_medium=paid, utm_campaign={tên_campaign}.

3. Danh sách nghiệp vụ

• Một workspace có thể kết nối nhiều Advertiser Account TikTok.
• Custom Audience: SĐT/Email PHẢI hash SHA-256 trước upload. Tối thiểu 100 records để tạo audience (tối thiểu 1,000 để tạo Lookalike).
• Lead từ TikTok phải được xử lý idempotent — dù webhook bị duplicate, Contact không được tạo hai lần.
• Chỉ số Video Performance đồng bộ cho tất cả Ad có chứa video (không áp dụng cho image ads nếu có).
• Attribution window có thể cấu hình (mặc định: 7 ngày click, 1 ngày view — theo chuẩn TikTok).

4. Giao diện

• Tab Tài khoản: Danh sách Advertiser Account đã kết nối, trạng thái, lần sync gần nhất.
• Tab Chiến dịch: Bảng Campaign → Ad Group, metrics tổng hợp.
• Tab Video Performance: Bảng xếp hạng video theo Completion Rate, biểu đồ funnel viewing.
• Tab Leads: Danh sách leads từ TikTok, thời gian xử lý, trạng thái phân bổ.
• Tab Audiences: Danh sách Custom Audience, match rate, trạng thái.

---

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

• Lead latency: Từ KH submit form đến Contact được tạo ≤ 10 giây qua webhook, ≤ 15 phút qua pull backup.
• Video metrics sync: Chỉ số video cập nhật hàng ngày lúc 3:00 AM (sau khi TikTok finalize data ngày hôm trước).
• Rate limit: Tuân thủ TikTok Marketing API rate limit: 1,000 requests/phút mặc định.
• Audience upload: Hỗ trợ upload tối đa 1,000,000 records/lần, xử lý batch nếu vượt quá.
• Uptime webhook: ≥ 99.5% — downtime đồng nghĩa với mất lead.

---

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

• TikTok Marketing API (v1.3+): Đọc campaign/ad metrics, Lead Form API, Custom Audience API.
• TikTok Webhook (Lead Notifications): Nhận sự kiện lead mới real-time.
• TikTok Events API: (Tính năng tương lai) Gửi conversion server-side.
• CRM – Contact Management: Tạo Contact từ lead.
• Chiến dịch Telesale: Nhận leads từ TikTok và phân bổ agent.
• Adaflow: Trigger “Khi có lead mới từ TikTok Ads”.
• Dashboard Module: Tổng hợp cross-platform metrics.

---

V. API Contract (Dev viết)

API 1: Kết nối TikTok Ads

• Method & Endpoint: POST /api/v1/integrations/tiktok-ads/connect
• Request Body: { "auth_code": "xxxxx", "advertiser_id": "1234567890" }
• Response 200: { "connected": true, "advertiser_name": "Company Vietnam" }

API 2: Webhook nhận Lead từ TikTok

• Method & Endpoint: POST /api/v1/webhooks/tiktok/lead (TikTok gọi vào)
• Payload (TikTok format):

  {
    "event": "form_submission",
    "data": {
      "advertiser_id": "1234567890",
      "form_id": "111222333",
      "lead_id": "999888777",
      "ad_id": "444555666",
      "campaign_id": "777666555"
    }
  }
  

• Response 200: { "code": 0, "message": "ok" }

API 3: Lấy Video Performance metrics

• Method & Endpoint: GET /api/v1/integrations/tiktok-ads/{advertiser_id}/video-performance?campaign_id={id}&date_range=last_30_days
• Response 200:

  {
    "ads": [
      {
        "ad_id": "444555666",
        "ad_name": "Product Demo Video - June",
        "video_views": 125000,
        "play_rate": 0.68,
        "six_second_view_rate": 0.45,
        "completion_rate": 0.23,
        "avg_watch_time_seconds": 12.4,
        "spend": 8500000,
        "leads": 87,
        "cpl": 97701
      }
    ]
  }
  

API 4: Upload Custom Audience

• Method & Endpoint: POST /api/v1/integrations/tiktok-ads/{advertiser_id}/audiences
• Request Body:

  {
    "audience_name": "CRM - KH đã mua hàng 2026",
    "audience_type": "CUSTOMER_FILE",
    "data": [
      { "phone_number": "sha256_hash_1" },
      { "phone_number": "sha256_hash_2" }
    ]
  }
  

---

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 → Advertiser Account hiển thị, trạng thái “Đã kết nối”.
• TC1.2: Thiếu permission lead.read → Thông báo cụ thể permission cần thêm.

Video Performance:

• TC2.1: Sync metrics → Completion Rate của Ad hiển thị đúng với TikTok Ads Manager.
• TC2.2: Ad không phải video (nếu có image ad) → Không hiển thị Video Performance metrics, không báo lỗi.

Nhận Lead:

• TC3.1: KH submit TikTok form → Contact được tạo trong CRM trong ≤ 10 giây.
• TC3.2: Webhook bị miss → Cơ chế pull backup lấy lead trong vòng 15 phút.
• TC3.3: Cùng lead_id webhook gửi 2 lần → Contact chỉ tạo 1 lần (idempotent).

Custom Audience:

• TC4.1: Upload 2,000 SĐT đã hash → Match rate > 50% sau khi TikTok xử lý.
• TC4.2: Upload < 100 records → Hệ thống cảnh báo kích thước audience quá nhỏ.
• TC4.3: Tạo Lookalike từ audience < 1,000 records → Hệ thống chặn và thông báo lý do.