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

Có thể kết nối

Doanh nghiệp tự đăng ký app trên TikTok API for Business, bàn giao App ID/Secret cho omniVN, rồi nhấn Connect Ads để advertiser cấp quyền. Shop ≠ Ads — hướng dẫn này chỉ cho TikTok Ads.

Có thể kết nối

Có thể kết nối. TikTok Ads: insights quảng cáo hàng ngày qua OAuth với app TikTok for Business do chính doanh nghiệp đăng ký (BYO). Shop ≠ Ads — hướng dẫn này không gồm TikTok Shop. Trang này được liệt kê trong workspace.

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: app BYO đã duyệt + omniVN đã nhận App ID/Secret + redirect URL khớp + quyền channels.connect. Đường chính: OAuth (Connect Ads).

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.

Cần hai vòng duyệt của TikTok (developer ~3 ngày làm việc, app 2–3 ngày làm việc) trước khi Connect được.
Workspace chưa có form nhập App ID/Secret — bàn giao qua omniVN.
Hướng dẫn này chỉ cho TikTok Ads. TikTok Shop là kết nối riêng — Shop ≠ Ads.

Tổng quan

omniVN kết nối TikTok Ads bằng app TikTok for Business do chính doanh nghiệp sở hữu (BYO): mỗi workspace dùng App ID/Secret riêng, không dùng chung app của omniVN. Trình tự: tạo tài khoản TikTok for Business → đăng ký developer (được duyệt trong khoảng 3 ngày làm việc) → tạo app với redirect URL của omniVN và các quyền đọc (duyệt thêm 2–3 ngày làm việc) → bàn giao App ID/Secret cho omniVN → nhấn Connect Ads và cấp quyền. Tổng thời gian có thể tới khoảng một tuần do hai vòng duyệt của TikTok. TikTok Shop (đơn hàng) là kết nối riêng.

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

Email công ty theo tên miền riêng và website công ty công khai cùng tên miền — TikTok từ chối email cá nhân và developer cá nhân.
Tài khoản TikTok for Business có quyền trên advertiser cần kết nối.
Redirect URL omniVN cung cấp: https://oauth.omnivn.com/connectors/tiktok-ads/callback.
Trong omniVN: quyền kết nối kênh trên workspace (channels.connect).

Các bước lấy credential

1. Tạo tài khoản TikTok for Business

Mở business-api.tiktok.com/portal, chọn đăng ký, nhập email (hoặc số điện thoại) và mật khẩu, đồng ý điều khoản rồi nhấn Sign Up và nhập mã xác minh.

2. Đăng ký làm developer

Trong portal nhấn Become a Developer. Điền tên, email công ty (Send Code → nhập mã), loại người dùng (Direct Advertiser, Agency hoặc Technology Company), tên công ty, website công ty, vị trí và mô tả mục đích (ví dụ: đọc báo cáo quảng cáo của chính doanh nghiệp vào omniVN). Nhấn Submit; TikTok phản hồi trong khoảng ba ngày làm việc.

Biểu mẫu Become a Developer · TikTok API for Business

3. Tạo app, khai báo redirect URL và quyền

Sau khi hồ sơ developer được duyệt, nhấn Create an App: đặt tên, mô tả mục đích sử dụng, điền advertiser redirect URL đúng từng ký tự https://oauth.omnivn.com/connectors/tiktok-ads/callback. Ở Scope of permission chỉ chọn quyền đọc omniVN cần: Ad Account Management → Read Ad Account Information; Reporting → Consolidated Report; Ads Management → Read Campaigns, Read Ad Groups, Read Ads. Nhấn Confirm; app được duyệt trong 2–3 ngày làm việc (xem ở My Apps).

Biểu mẫu Create an App trên TikTok API for Business · TikTok API for Business

4. Lấy App ID và Secret, bàn giao cho omniVN

Khi app được duyệt, mở My Apps → chọn app → Basic Information để thấy App ID và Secret. Workspace omniVN chưa có form tự nhập: gửi hai giá trị này cho omniVN qua kênh bàn giao an toàn omniVN chỉ định (không gửi Secret qua chat hay email thường). omniVN niêm phong Secret vào secret store; sau đó nút Connect Ads mới sẵn sàng.

Danh sách My Apps và trạng thái duyệt · TikTok API for Business

5. Nhấn Connect Ads và cấp quyền advertiser

Trong omniVN → Integrations → TikTok Ads, nhấn Connect Ads. TikTok hiện danh sách quyền: xem lại, đồng ý điều khoản, nhấn Confirm, rồi Send Code và nhập mã email để xác minh. TikTok chuyển về omniVN kèm auth_code (dùng một lần, hiệu lực tối đa một giờ); omniVN đổi lấy access token phía máy chủ.

Trang advertiser xem và xác nhận quyền cho app · TikTok API for Business

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

TikTok trả danh sách advertiser_ids đã cấp quyền. Nếu có nhiều, omniVN hiện màn Account selection để chọn tài khoản cần gắ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 omniVN	Tên trong tài liệu official	Bắt buộc	Lấy từ đâu
TikTok App ID	app_id	Bắt buộc	user_entered App ID của app do doanh nghiệp tạo trên business-api.tiktok.com (My Apps → App Detail → Basic Information). Hiện omniVN nhận qua operator (receiveAdsByoApp), chưa có form trên workspace.
TikTok App Secret	secret	Bắt buộc	user_entered Secret của app BYO; omniVN niêm phong vào secret store, không trả ra trình duyệt.
TikTok Ads Access Token	access_token	Bắt buộc	oauth_authorization omniVN đổi từ auth_code sau khi advertiser cấp quyền; token dài hạn, không nhập tay.
TikTok Advertiser ID	advertiser_id	Bắt buộc	oauth_authorization Trả về trong advertiser_ids sau OAuth; chọn trên màn Account selection nếu có nhiều.

appId, appSecret → app BYO của doanh nghiệp; hiện omniVN nhận qua operator (receiveAdsByoApp), chưa có form trên workspace. accessToken, advertiserId → có sau OAuth, lưu secret store, không nhập tay.

Vòng đời token

auth_code dùng một lần, hết hạn trong vòng một giờ. Access token dài hạn không tự hết hạn; mất hiệu lực khi advertiser hủy ủy quyền (ads.tiktok.com → Authorizations) hoặc app thu hồi token — khi đó connection báo cần kết nối lại. Token chỉ có các quyền advertiser thực sự đồng ý.

Lỗi thường gặp

Connect Ads chưa sẵn sàng / báo Ads BYO app not received

omniVN chưa nhận App ID/Secret của app BYO cho workspace này. Hoàn tất bước bàn giao rồi thử lại.

TikTok báo Redirect Url Not Match

Advertiser redirect URL trên app không khớp từng ký tự với URL omniVN cung cấp. Sửa trên My Apps (thay đổi có thể cần duyệt lại) rồi Connect lại.

Invalid auth code

auth_code đã dùng hoặc hết hạn, hoặc App ID/Secret đã bàn giao không khớp app. Nhấn Connect Ads lại từ omniVN.

Hồ sơ developer bị từ chối

Dùng email cá nhân, website không công khai hoặc khác tên miền email. TikTok không nhận developer cá nhân.