Kết nối Meta Ads với omniVN
Có thể kết nốiKết nối Meta Ads qua OAuth (scope ads_read) từ trang Integrations. Advertiser đăng nhập Facebook — không dán App ID, App Secret hay token từ Graph API Explorer.
Cổng sẵn sàng: META_* + secret store + redirect khớp + (production) Advanced Access ads_read sau App Review. Đường chính: OAuth ads_read.
Giới hạn hiện tại
- App Review / Advanced Access cho ads_read là blocker thật: advertiser không có role trên app sẽ thất bại permission (#200) cho đến khi Meta duyệt Advanced Access — Omni0 không thể bỏ qua cổng này.
- User token hết hạn bắt buộc Connect lại; không dùng token dán từ Graph API Explorer trên workspace.
- OAuth redirect (Connect Meta Ads) là đường chính — không paste App ID/Secret/token.
Tổng quan
Meta Marketing API dùng Facebook Login (authorization code). Omni0 giữ META_APP_ID và META_APP_SECRET trên Convex. Advertiser nhấn Connect Meta Ads, đăng nhập Facebook, cấp ads_read; Omni0 đổi code lấy user token dài hạn (~60 ngày) rồi liệt kê ad account qua /me/adaccounts. Nếu có nhiều tài khoản, Omni0 hiện màn chọn. Không có form dán key trên workspace.
Điều kiện trước khi bắt đầu
- Tài khoản Facebook có quyền trên Ad Account (quản trị hoặc quảng cáo).
- Omni0 đã tạo Business app trên Meta for Developers, bật Marketing API và Facebook Login (operator).
- Deployment Convex có META_APP_ID, META_APP_SECRET, secret store, và redirect URI /connectors/meta-ads/callback.
- Trong Omni0: quyền kết nối kênh trên workspace.
Các bước lấy credential
1. Omni0 đăng ký ứng dụng Meta
Tạo Business type app trên developers.facebook.com, bật Marketing API. Lưu App ID và App Secret vào Convex env (META_APP_ID, META_APP_SECRET). Đây là credential của Omni0, không phải của advertiser — advertiser không dán các giá trị này.
2. Cấu hình miền app và OAuth redirect URI
Trên Meta for Developers, Settings → Basic: thêm nền tảng Website với Site URL https://<deployment>.convex.site/, rồi điền App Domains = <deployment>.convex.site (không có https, không có path). Products → Facebook Login → Settings: bật Web OAuth Login, thêm đúng một Valid OAuth Redirect URI https://<deployment>.convex.site/connectors/meta-ads/callback. Strict Mode yêu cầu khớp từng ký tự, kể cả path. OAuth redirect là đường kết nối chính.
3. Tùy chọn: Facebook Login for Business
Cách Meta khuyến nghị cho tech provider. Tạo configuration (User access token hoặc System-user access token, asset Ad Account, quyền ads_read), lưu Configuration ID vào META_LOGIN_CONFIG_ID. Dialog lúc đó gửi config_id thay vì scope.
4. Advertiser cấp quyền (ads_read)
Trong Omni0 → Integrations → Meta → Connect Meta Ads. Đăng nhập Facebook và chấp nhận ads_read. Không nhập App ID, App Secret hay access token từ Graph API Explorer / Graph Explorer paste.
5. Chọn Ad Account
Một ad account được kích hoạt ngay. Nhiều tài khoản thì chọn trên màn Account selection sau OAuth.
Ánh xạ credential với omniVN
| Field omniVN | Tên trong tài liệu official | Bắt buộc | Lấy từ đâu |
|---|---|---|---|
| App ID | app_id | Bắt buộc | operator_managed Do Omni0 đăng ký app Meta. Convex env META_APP_ID. |
| App Secret | app_secret | Bắt buộc | operator_managed Convex env META_APP_SECRET. Không hiển thị cho advertiser. |
| Login for Business Config ID | config_id | Tùy chọn | operator_managed Tùy chọn. META_LOGIN_CONFIG_ID thay scope=ads_read trên dialog. |
| Access Token | access_token | Bắt buộc | oauth_authorization Cấp sau Facebook Login; lưu secret store, không nhập tay. |
| Ad Account ID | ad_account_id | Bắt buộc | oauth_authorization Chọn từ /me/adaccounts sau OAuth, không nhập tay trên form. |
appId → META_APP_ID (Convex env, Omni0); appSecret → META_APP_SECRET (Convex env, Omni0); loginConfigId → META_LOGIN_CONFIG_ID (tùy chọn); accessToken → secret store sau OAuth; adAccountId → act_… từ /me/adaccounts sau khi user cấp quyền. Không dán từ Graph API Explorer.
Vòng đời token
Code đổi thành token ngắn hạn rồi extend bằng grant_type=fb_exchange_token (~60 ngày). Omni0 gia hạn token còn hạn khoảng 7 ngày trước khi hết. Token hết hạn, user đổi mật khẩu, hoặc thu hồi quyền ứng dụng thì phải Connect lại. System-user token từ Login for Business mặc định không hết hạn nếu operator cấu hình loại đó.
Lỗi thường gặp
Connect báo PROVIDER_CONFIGURATION_INVALID hoặc nút chưa sẵn sàng
Thiếu META_APP_ID hoặc META_APP_SECRET trên Convex, secret store chưa sẵn, hoặc redirect URI chưa khớp Valid OAuth Redirect URIs.
Facebook: Không thể tải URL / miền chưa đưa vào Miền ứng dụng (App Domains)
redirect_uri trỏ tới host Convex HTTP (ví dụ expert-jackal-558.convex.site) nhưng App Domains chưa có host đó, hoặc chưa có Website Site URL cùng host. Thêm subdomain đầy đủ, không thêm mỗi convex.site. Sau khi lưu, bấm Connect lại từ Omni0; đừng mở lại URL dialog cũ vì state hết hạn ~5 phút.
Lỗi insufficient permissions (#200) / ads_read bị từ chối
User từ chối ads_read; hoặc app chưa có Advanced Access cho ads_read với user ngoài app role (App Review — xem blockers); hoặc không có quyền trên Ad Account đã chọn.
Phải Connect lại sau khoảng 60 ngày
Long-lived user token hết hạn và không extend được khi đã expire. Connect lại để lấy code mới. Token hệ thống (Login for Business system user) không theo chu kỳ 60 ngày.