← Tất cả tích hợp

Kết nối TikTok Ads với omniVN

Có thể kết nối

Kết nối TikTok Ads (insights) qua OAuth từ trang Integrations. Shop ≠ Ads — hướng dẫn này chỉ cho TikTok Ads.

Kết nối TikTok AdsTạo tài khoản và làm theo hướng dẫn bên dưới — dùng thử 14 ngày.

Cổng sẵn sàng: Connect Ads chỉ bật khi deployment có TIKTOK_ADS_* + secret store + redirect khớp. Không dán token; OAuth redirect là đường kết nối chính.

Giới hạn hiện tại

Những điểm này ảnh hưởng đến khả năng kết nối hoàn chỉnh.
  • Hướng dẫn này chỉ cho TikTok Ads. TikTok Shop (đơn hàng) là connector/OAuth riêng — Shop ≠ Ads.
  • Production cần vault/secret-manager resolver; local-env chỉ dùng development.

Tổng quan

TikTok Ads dùng TikTok for Business Marketing API (OAuth 2.0, app_id/secret do Omni0 vận hành). Advertiser nhấn Connect Ads trên Omni0, đăng nhập TikTok for Business và cấp quyền; Omni0 đổi auth_code lấy advertiser access token phía máy chủ. TikTok Shop (đơn hàng) là kết nối riêng — không gộp trong hướng dẫn này.

Điều kiện trước khi bắt đầu

  • Tài khoản TikTok for Business với quyền quản trị quảng cáo (advertiser).
  • Omni0 đã đăng ký app trên TikTok for Business Developer Portal (operator).
  • Deployment Convex có TIKTOK_ADS_APP_ID / TIKTOK_ADS_SECRET, secret store, và redirect URI /connectors/tiktok-ads/callback.
  • Trong Omni0: quyền kết nối kênh trên workspace (channels.connect).

Các bước lấy credential

1. Omni0 đăng ký app TikTok for Business

Operator Omni0 tạo app trên business-api.tiktok.com/portal để nhận app_id và secret. Redirect URI: https://<deployment>.convex.site/connectors/tiktok-ads/callback. Credential app do Omni0 giữ — advertiser không dán app_id/secret.

2. Mở TikTok Ads trong Omni0 và nhấn Connect Ads

Vào Integrations → TikTok Ads. Nhấn Connect Ads — Omni0 mở OAuth TikTok for Business (redirect). Không dán Access-Token hay advertiser_id thủ công. Giữ tab Omni0 mở đến khi kết nối xuất hiện.

3. Đăng nhập TikTok for Business và cấp quyền

Đăng nhập tài khoản có quyền advertiser, đồng ý scope Marketing API. TikTok trả auth_code về callback Omni0; backend đổi code lấy access token và lưu secret store.

4. Chọn advertiser (nếu có nhiều)

Nếu TikTok trả nhiều advertiser_id, Omni0 hiện màn Account selection sau OAuth — chọn tài khoản cần gắn. Một advertiser được kích hoạt theo lựa chọn.

Ánh xạ credential với omniVN

Cột "Lấy từ đâu" cho biết giá trị do người dùng nhập, do provider cấp, do omniVN quản lý, hay do OAuth sinh ra.
Field omniVNTên trong tài liệu officialBắt buộcLấy từ đâu
TikTok Ad App IDapp_idBắt buộcoperator_managed

Do Omni0 đăng ký app TikTok for Business.

TikTok Ad SecretsecretBắt buộcoperator_managed
TikTok Ads Access Tokenaccess_tokenBắt buộcoauth_authorization

Lấy từ auth_code sau khi advertiser cấp quyền OAuth.

TikTok Advertiser IDadvertiser_idBắt buộcoauth_authorization

Chọn sau OAuth nếu có nhiều advertiser; không dán tay.

adAppId → TIKTOK_ADS_APP_ID (Convex env, Omni0); adSecret → TIKTOK_ADS_SECRET (Convex env, Omni0); adAccessToken / advertiserId → secret store sau OAuth (không nhập tay trên form).

Vòng đời token

TikTok Ads access token theo tài liệu Marketing API; thu hồi quyền hoặc hết hạn → connection báo reauthorization_required, cần Connect Ads lại. Không dùng token dán tay.

Lỗi thường gặp

Connect báo PROVIDER_CONFIGURATION_INVALID hoặc nút chưa sẵn sàng

Thiếu TIKTOK_ADS_APP_ID/SECRET trên Convex, secret store chưa sẵn, hoặc redirect URI chưa khớp portal. Liên hệ operator — không dán token để vượt qua.

Lỗi invalid auth_code

auth_code hết hạn (~30 phút), redirect_uri không khớp portal, hoặc app_id/secret sai.

Nhiều advertiser ids sau OAuth

Omni0 liệt kê advertiser sau OAuth — chọn trên màn Account selection.

Nguồn chính thức

TikTok for Business API Documentation
business-api.tiktok.com·Cần render JS·Đã kiểm chứng 2026-08-29