Bỏ qua

Ads Data Platform — King Studio

Đây là cổng tài liệu kỹ thuật của đội Data Platform tại King Studio. Bạn dùng nó khi cần lấy số liệu quảng cáo của các game King từ Meta, TikTok và Google Ads: cách xác thực, cách gọi từng endpoint, cách đọc kết quả và những điểm cần nhớ khi xây pipeline theo ngày. Gặp từ lạ, mở Glossary.

Cả ba API đi qua API gateway của Data Platform (*.huydata.com). Cách gọi giống hệt API gốc của từng nền tảng: cùng đường dẫn, cùng tham số, cùng cấu trúc response. Bạn chỉ đổi host.

Nền tảng Base URL API
Meta (Facebook / Instagram Ads) https://graph.huydata.com/v21.0 Meta Marketing API (Graph API)
TikTok Ads https://business-api.huydata.com/open_api/v1.3 TikTok Marketing API
Google Ads (chiến dịch video YouTube) https://googleads.huydata.com/v18 Google Ads API (REST)

King Studio chạy paid UA (user acquisition: mua người dùng bằng quảng cáo trả tiền) cho 10 game di động (6 Android, 4 iOS) tại 14 nước. Mỗi game có một tài khoản quảng cáo (ad account / advertiser / customer) trên mỗi nền tảng. Mã game, id tài khoản và geo id của từng nước nằm trong Bảng tra cứu. Số liệu theo ngày có từ 2026-06-30 trở đi; mỗi đêm thêm một ngày mới.

Ba nền tảng khác nhau ở mọi thứ: authentication, request format, paging, cấu trúc response và cách báo lỗi. Không có "mẫu chung". Bạn tích hợp nền tảng nào thì đọc phần của nền tảng đó.

Data model

Cả ba nền tảng dùng cùng một entity hierarchy (xem Khái niệm quảng cáo):

Account (one per game)
└── Campaign        objective + daily budget          e.g. CCS_FB_AND_T1_VALUE_202607
    └── Ad set / Ad group   targeting (countries, audience)   e.g. T1_Broad_AU-CA-DE-GB-US
        └── Ad      one creative                     e.g. VID_Gameplay15s_v2

Đọc cây trên từ trên xuống:

  • Account (tài khoản quảng cáo): mỗi game một tài khoản.
  • Campaign (chiến dịch): có objective (mục tiêu chiến dịch) và daily budget (ngân sách ngày).
  • Ad set / Ad group (nhóm quảng cáo): quyết định targeting: nước nào, audience (tệp đối tượng) nào.
  • Ad (quảng cáo): một creative (nội dung quảng cáo) cụ thể, ví dụ một video 15 giây.

Số liệu được đo ở grain (mức chi tiết nhỏ nhất) report date × ad × country. Mỗi dòng có ít nhất: impressions (lượt hiển thị), clicks (lượt bấm), spend (chi tiêu, USD), installs (lượt cài) và purchases (lượt mua trong app).

Data freshness và attribution window

Số liệu quảng cáo không chốt ngay. Bốn điều cần nhớ:

  • Data freshness (dữ liệu mới đến đâu, khi nào có): một report date (ngày báo cáo, theo UTC) có mặt vào khoảng 00:10 UTC ngày hôm sau, tức 07:10 sáng giờ Việt Nam. Batch job chạy mỗi đêm; không có số liệu trong ngày. Nếu job bị trễ, gọi /health trên mỗi API để xem latest_report_date. Mọi tài khoản đều dùng múi giờ UTC.
  • Spend, impressions và clicks là final (đã chốt) ngay khi report date có mặt.
  • Installs và purchases còn tăng trong 3 ngày sau report date. Lý do là attribution window (khoảng 3 ngày sau khi bấm quảng cáo để install, purchase được ghi nhận cho quảng cáo đó): người bấm quảng cáo ngày D nhưng cài hoặc mua vào ngày D+2 vẫn được cộng vào ngày D. Đây là late-arriving data (số về muộn): con số bạn lấy hôm nay cho ngày hôm qua sẽ lớn hơn khi bạn lấy lại vào mai. Pipeline cần số final thì phải lấy lại 3 report date gần nhất.
  • Dòng không có hoạt động (campaign tạm dừng, ad chưa tạo) không được trả về. Đừng mặc định mỗi ad đều có một dòng mỗi ngày.

Rate limit

Mỗi access token được gọi 60 request mỗi phút trên mỗi nền tảng. Khi bạn vượt quá, mỗi nền tảng phản ứng một kiểu; xem trang Errors của từng phần. Cách xử lý đúng: backoff (chờ) rồi retry. Không mở thêm kết nối hay dùng nhiều token để vượt rate limit.

Lấy credentials

Đội Data Platform cấp cho bạn 4 secret: một access token Meta, một access token TikTok, một Google OAuth access token và một Google developer token. Token gắn với tên bạn; mọi request được ghi log theo token. Không đưa token vào code đã chia sẻ hay repo. Xem Bắt đầu.

Tài liệu được xây dựng như trong doanh nghiệp bởi Huydata. Dành riêng cho các khoá học Data tại Huydata.