Từ điển thuật ngữ¶
Trang này gom tất cả từ chuyên môn dùng trong tài liệu. Gặp từ lạ ở trang nào, quay lại đây. Mỗi từ có một câu giải thích và một ví dụ bằng số để bạn hình dung ngay.
Dấu chấm hay dấu phẩy?
Trong code và JSON, dấu chấm là phần thập phân: 854.51 nghĩa là 854,51 USD.
Văn xuôi tiếng Việt trong tài liệu viết 854,51 USD và 1.000.000. Cùng một con số, chỉ khác cách viết.
Đối tượng quảng cáo¶
Đây là "các thứ" bạn sẽ gặp khi gọi API: tài khoản, chiến dịch, nhóm quảng cáo, quảng cáo. Hãy nghĩ như thu phóng bản đồ: account là cả nước, campaign là tỉnh, ad set là huyện, ad là xã.
| Thuật ngữ | Gọi là | Giải thích một câu (có ví dụ) |
|---|---|---|
| account / ad account / advertiser / customer | tài khoản quảng cáo | Nơi "trả tiền" cho quảng cáo. Ở sandbox, 1 tài khoản = 1 game trên mỗi nền tảng, ví dụ game DMS có act_199454714457591 trên Meta. Meta gọi là ad account, TikTok gọi advertiser, Google gọi customer. |
| campaign | chiến dịch | Một đợt chạy quảng cáo có mục tiêu và ngân sách ngày. Ví dụ DMS_FB_AND_T1_VALUE_202607 là chiến dịch của game DMS, chạy trên Facebook, Android, nhóm nước T1, bắt đầu tháng 07/2026. |
| ad set / ad group | nhóm quảng cáo | Nằm trong campaign, trả lời "cho ai xem?": nước nào, hệ điều hành nào, tệp đối tượng nào. Meta gọi ad set, TikTok và Google gọi ad group. |
| ad | quảng cáo (một mẫu cụ thể) | Mẫu quảng cáo người dùng thật sự nhìn thấy, ví dụ VID_Gameplay15s_v2. Số liệu được đo ở cấp này; cấp trên là tổng của cấp dưới. |
| creative | nội dung quảng cáo (video / ảnh / playable) | Phần "nhìn thấy" của một ad: video 15 giây, ảnh tĩnh, hoặc bản chơi thử. Một ad gắn với đúng một creative. |
| objective (INSTALL, VALUE) | mục tiêu chiến dịch | Chiến dịch chạy để làm gì. INSTALL: nhiều lượt cài rẻ nhất. VALUE: ít lượt cài hơn nhưng người cài chịu mua hàng. |
| status | trạng thái (giá trị giữ tiếng Anh) | Đang chạy, tạm dừng hay đã kết thúc. Giá trị giữ nguyên tiếng Anh như ACTIVE, PAUSED; ngày tạm dừng không có dòng số liệu. |
| daily budget | ngân sách ngày | Số tiền tối đa được chi mỗi ngày. Ngân sách 200 USD thì chi thực tế thường quanh 190–200 USD. |
| targeting / geo target | nhắm mục tiêu / nước được nhắm | Chọn ai được xem quảng cáo. Ví dụ ad set T1_Broad_AU-CA-DE-GB-US nhắm 5 nước Úc, Canada, Đức, Anh, Mỹ. |
| audience | tệp đối tượng | Nhóm người được chọn để xem. Broad là ai cũng được, Lookalike_Payers là người giống những ai đã trả tiền. |
| app id / store id | mã ứng dụng trên cửa hàng | Mã của game trên Google Play hoặc App Store, ví dụ com.novaplay.dragonmerge hoặc id1600000011. Đây là "chìa khoá" nối ba nền tảng với nhau. |
| Ads Manager | giao diện web xem báo cáo, dùng để đối chiếu | Trang web https://ads-manager.huydata.com hiện cùng số liệu với API. Bạn so dòng Totals ở đó với kết quả chương trình của mình. |
| pipeline | chương trình tự động lấy số liệu mỗi ngày | Đoạn code chạy mỗi sáng, gọi API lấy số liệu hôm qua rồi lưu lại. Mục tiêu cuối của khoá học là bạn viết được một pipeline. |
| sandbox | môi trường giả lập để học | Bản "mô hình" của ba API thật, số liệu là giả nhưng cách gọi giống y. Làm sai ở đây không tốn tiền ai. |
Chỉ số¶
Chỉ số là các con số đo hiệu quả. Hãy nhớ một ví dụ xuyên suốt: chi 100 USD, 10.000 lượt hiển thị, 200 lượt bấm, 20 lượt cài, 2 người mua tổng 30 USD.
| Thuật ngữ | Gọi là | Giải thích một câu (có ví dụ) |
|---|---|---|
| impression | lượt hiển thị | Số lần quảng cáo xuất hiện trên màn hình. Một người xem 3 lần tính 3 impressions. |
| reach | số người tiếp cận (mỗi người tính một lần) | Số người khác nhau đã xem. 10.000 impressions tới 4.000 người thì reach = 4.000. |
| frequency | tần suất = impressions / reach | Trung bình mỗi người xem bao nhiêu lần. 10.000 / 4.000 = 2,5 lần. |
| click | lượt bấm | Số lần người xem bấm vào quảng cáo. Ví dụ: 200 lượt bấm. |
| CTR | tỷ lệ bấm = clicks / impressions | Bao nhiêu phần trăm lượt xem dẫn tới bấm. 200 / 10.000 = 2 %. |
| CPC | giá mỗi lượt bấm | Chi tiêu chia cho lượt bấm. 100 USD / 200 = 0,5 USD mỗi lượt bấm. |
| CPM | giá cho 1.000 lượt hiển thị | Chi tiêu chia cho impressions rồi nhân 1.000. 100 / 10.000 × 1.000 = 10 USD. |
| spend / cost | chi tiêu (USD) | Tiền đã chi. Meta và TikTok trả chuỗi "100.00"; Google trả cost_micros = 100000000. |
| install / conversion | lượt cài đặt | Số người cài game sau khi xem hoặc bấm quảng cáo. Meta gọi mobile_app_install, TikTok gọi conversion, Google gọi conversions. |
| CPI | giá mỗi lượt cài = spend / installs | Chi 100 USD được 20 lượt cài → CPI = 5 USD. |
| eCPI | CPI thực tế tính từ tổng | CPI tính từ tổng chi tiêu chia tổng lượt cài của cả kỳ, không phải trung bình các CPI từng ngày. Tổng 700 USD / 140 cài = 5 USD. |
| purchase | lượt mua trong app | Số giao dịch mua trong game được tính cho quảng cáo. Ví dụ: 2 lượt mua. |
| purchase value / conversions value / revenue | doanh thu | Tổng tiền từ các lượt mua đó. 2 người mua tổng 30 USD → doanh thu 30 USD. |
| ROAS | doanh thu trên chi tiêu = purchase value / spend | Mỗi 1 USD chi ra thu về bao nhiêu. 30 / 100 = 0,3 (chưa hoà vốn; trên 1 là có lời). |
| micros | phần triệu (1 USD = 1.000.000 micros) | Google đếm tiền bằng phần triệu đô. cost_micros: 854510000 nghĩa là 854,51 USD. |
Thời gian và dữ liệu¶
Số liệu quảng cáo không "chốt" ngay. Phần này giải thích vì sao cùng một ngày mà hôm nay lấy ra một số, mai lấy ra số khác.
| Thuật ngữ | Gọi là | Giải thích một câu (có ví dụ) |
|---|---|---|
| report date | ngày báo cáo (theo UTC) | Ngày mà số liệu thuộc về, tính theo giờ UTC. Dòng có date_start: "2026-10-20" là số liệu của ngày 20/10. |
| UTC | giờ quốc tế (Việt Nam = UTC+7) | Mốc giờ chung toàn cầu. 00:10 UTC là 07:10 sáng ở Việt Nam. |
| attribution window | cửa sổ quy công (3 ngày) | Hạn 3 ngày để "tính công" cho quảng cáo: ai cài game trong 3 ngày sau khi xem thì được cộng vào lượt cài. Vì vậy installs của ngày D còn tăng tới D+3. |
| late-arriving data | số liệu đến muộn | Lượt cài và lượt mua "điểm chưa chốt", vài ngày sau mới có điểm cuối. Hôm qua thấy 120 cài, hôm nay cùng ngày đó có thể là 127. |
| data freshness | độ tươi dữ liệu | Số liệu mới tới đâu. Ngày D có từ 00:10 UTC ngày D+1; không có số liệu trong ngày. |
| as_of / "Data as reported on" | số liệu tính đến ngày… | Xem lại bảng điểm đúng như ngày hôm đó. Chọn "Data as reported on" = 21/10 để thấy ngày 20/10 trông thế nào vào sáng 21/10. |
| date preset | khoảng ngày có sẵn | Khoảng ngày chọn nhanh thay vì gõ tay, ví dụ last_7d là 7 ngày gần nhất. |
| time_increment / granularity | độ chia thời gian | Chia số liệu theo ngày hay gộp cả kỳ. time_increment=1 là một dòng mỗi ngày. |
| breakdown / dimension / segment | chiều tách dữ liệu (theo ngày, theo nước) | Tách một dòng thành nhiều dòng, như bảng điểm chia theo môn. Tách theo nước thì 1 ad có 5 dòng cho 5 nước. |
| level / data_level | cấp dữ liệu | Muốn số liệu ở cấp nào: account, campaign, ad set hay ad. Giống thu phóng bản đồ từ cả nước xuống xã. |
Cách gọi API¶
API là cách để chương trình "hỏi" máy chủ. Hãy tưởng tượng bạn đến một toà nhà có nhiều quầy giao dịch, mỗi quầy làm một việc.
| Thuật ngữ | Gọi là | Giải thích một câu (có ví dụ) |
|---|---|---|
| API | cách để chương trình "hỏi" máy chủ | Thay vì bấm trên web, code gửi câu hỏi và nhận câu trả lời dạng JSON. Ba API ở đây mô phỏng Meta, TikTok, Google Ads. |
| endpoint | địa chỉ nhận yêu cầu (một "quầy") | Mỗi quầy làm một việc. Quầy /me/adaccounts trả danh sách tài khoản; quầy /insights trả số liệu. |
| request / response | yêu cầu / phản hồi | Phiếu yêu cầu bạn gửi và phiếu trả lời máy chủ gửi về. Một lần gọi API = 1 request + 1 response. |
| GET / POST | cách gửi: GET lấy, POST gửi kèm nội dung | GET chỉ hỏi (Meta, TikTok). POST gửi kèm nội dung, ví dụ Google nhận câu GAQL trong body. |
| header | dòng thông tin kèm yêu cầu | Ghi chú ngoài bì thư, ví dụ Access-Token: abc123 cho TikTok biết bạn là ai. |
| query parameter | tham số trên URL (sau ?) |
Ô điền trên phiếu, viết sau dấu ? và nối bằng &. Ví dụ ?fields=id,name&limit=100. |
| request body | nội dung gửi kèm (JSON) | Tờ giấy kèm trong bì thư, dùng với POST. Google nhận {"query": "SELECT ..."} ở đây. |
| token / access token | thẻ truy cập | Thẻ ra vào, như thẻ học sinh quẹt cổng. Mất thẻ là người khác vào bằng tên bạn, nên không bao giờ đưa token lên mạng. |
| developer token | mã nhà phát triển (chỉ Google) | Giấy phép hành nghề của ứng dụng. Google đòi cả thẻ ra vào (access token) và giấy phép này. |
| login-customer-id | tài khoản quản lý dùng để đăng nhập (Google) | Tài khoản "mẹ" quản lý các tài khoản game. Ở sandbox luôn là 9990001111. |
| JSON | định dạng dữ liệu có {} và [] |
Phiếu viết theo mẫu máy đọc được: {"spend": "854.51"}. Dấu {} là một "hồ sơ", [] là một danh sách. |
| paging / pagination | phân trang | Kết quả dài được chia thành nhiều trang, như lật trang sách. Muốn đủ dữ liệu phải lật hết. |
cursor / page token / after / nextPageToken |
dấu kẹp sách (vị trí trang tiếp theo) | Chuỗi đánh dấu "đọc tới đây rồi". Gửi lại nó để lấy trang tiếp; không còn dấu kẹp là hết sách. |
| rate limit / quota | giới hạn lượt gọi (60 / phút / token / nền tảng) | Cổng soát vé chỉ cho 60 người qua mỗi phút. Gọi lần thứ 61 trong phút đó sẽ bị chặn. |
| Retry-After / back off | chờ rồi thử lại | Bảo vệ nói "chờ rồi vào". Header Retry-After: 30 nghĩa là chờ 30 giây rồi gọi lại. |
| HTTP status code | mã trạng thái | Con dấu trên phiếu trả lời: 200 xong, 400 bạn điền sai, 401 sai thẻ, 403 không được phép, 404 sai quầy, 429 chờ chút, 500 lỗi phía họ. |
| error envelope | "vỏ" thông báo lỗi | Khối JSON bọc thông tin lỗi, ví dụ {"error": {"code": 190, "message": "..."}}. Mỗi nền tảng có vỏ khác nhau. |
| request id | mã số của lần gọi | Mã duy nhất cho mỗi lần gọi, ví dụ fbtrace_id hoặc request_id. Gửi mã này khi hỏi hỗ trợ. |
| GAQL | ngôn ngữ truy vấn của Google Ads | Câu hỏi theo mẫu SELECT cột FROM bảng WHERE điều kiện, như phiếu tra cứu thư viện. |
| resource / field (Google) | bảng / cột | Resource là bảng (campaign, ad_group_ad), field là cột (metrics.clicks). GAQL chọn cột từ bảng. |
| searchStream vs search | lấy một lần hết / lấy theo trang | searchStream trả hết một lần, search trả từng trang với pageToken. Cùng một câu GAQL. |
| URL-encode | mã hoá ký tự đặc biệt trên URL | Ký tự lạ như dấu cách, [, " phải đổi thành %20, %5B, %22 để URL hợp lệ. curl -G --data-urlencode làm việc này cho bạn. |