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

Có thể kết nối

Doanh nghiệp tự tạo app Meta (Marketing API), chủ hoặc admin workspace dán App ID/Secret (và Configuration ID) vào trang Meta trong omniVN, rồi nhấn Connect Meta Ads để cấp ads_read.

Có thể kết nối

Có thể kết nối. Insights quảng cáo hàng ngày qua Facebook Login for Business (ads_read) với app Meta do chính doanh nghiệp tạo (BYO). Người bấm Connect cần có role trên app đó. Trang này được liệt kê trong workspace.

Kết nối Meta 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 + workspace đã lưu App ID/Secret (+ Configuration ID) + redirect khớp + người kết nối có role trên app.

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.

Standard Access giới hạn tốc độ gọi theo ad account; người không có role trên app cần Advanced Access qua App Review.
Không dùng token dán từ Graph API Explorer (ngắn hạn). OAuth (Connect Meta Ads) là đường chính; token System User là đường thay thế.

Tổng quan

omniVN kết nối Meta Ads bằng app Meta 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. Doanh nghiệp tạo app với use case Marketing API, khai báo miền và redirect URI của omniVN, tạo cấu hình Facebook Login for Business, rồi chủ hoặc admin workspace dán App ID, App Secret và Configuration ID vào trang Meta trong omniVN; omniVN kiểm tra App ID/Secret với Meta trước khi lưu. Sau đó người có role trên app nhấn Connect Meta Ads; omniVN đổi code lấy token (~60 ngày) và liệt kê ad account để chọn. Vì người kết nối có role trên app, Standard Access là đủ — không cần App Review.

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

Tài khoản Facebook đã đăng ký Meta for Developers và có quyền trên Ad Account (quản trị hoặc quảng cáo).
Người sẽ nhấn Connect phải có role Admin, Developer hoặc Tester trên app.
Giá trị omniVN cung cấp: Site URL https://omnivn.com/, App Domains omnivn.com và oauth.omnivn.com, redirect URI https://oauth.omnivn.com/connectors/meta-ads/callback.
Trong omniVN: vai trò chủ (Owner) hoặc Administrator của workspace để đăng ký app; quyền channels.connect để kết nối.

Các bước lấy credential

1. Tạo app với use case Marketing API

Vào developers.facebook.com/apps → Create app. Ở App details nhập tên app và email liên hệ. Ở Use cases chọn “Measure ad performance data with Marketing API” (đủ cho báo cáo). Ở Business, gắn business portfolio của doanh nghiệp (có thể làm sau). Đi hết Requirements → Overview → Go to dashboard. Use case này tự thêm Facebook Login for Business và ads_read ở Standard Access.

2. Khai báo miền app

App settings → Basic: Add Platform → Website, Site URL = https://omnivn.com/; App Domains = omnivn.com và oauth.omnivn.com (không có https, không có path). Điền Privacy Policy URL và Category nếu dashboard yêu cầu. App ID và App Secret (nhấn Show) nằm ngay trên trang này.

3. Thêm redirect URI của omniVN

Facebook Login for Business → Settings → Client OAuth settings: giữ bật Web OAuth Login và Enforce HTTPS, thêm Valid OAuth Redirect URI https://oauth.omnivn.com/connectors/meta-ads/callback. Strict Mode yêu cầu khớp từng ký tự, kể cả path.

4. Tạo configuration Facebook Login for Business

Facebook Login for Business → Configurations → Create configuration: đặt tên, chọn User access token, chọn asset là Ad Account cần đọc và quyền ads_read, rồi Create. Ghi lại Configuration ID. Meta khuyến nghị dùng config_id thay cho scope. Nếu Facebook Login gặp trở ngại (tài khoản cá nhân bị hạn chế, người kết nối không có role), dùng token System User ở bước cuối.

5. Thêm role cho người kết nối

App roles → Roles: thêm tài khoản Facebook sẽ nhấn Connect làm Admin, Developer hoặc Tester. Ở Standard Access, chỉ người có role trên app mới cấp được quyền; app có thể giữ Development mode.

6. Dán App ID, App Secret, Configuration ID vào omniVN

Trong omniVN, vào Integrations → Meta Ads: khi workspace chưa có app, trang hiện khung “Register your Meta app”; nếu đã có, dùng Settings → Meta app → Update app. Dán App ID và App Secret (App settings → Basic) và Configuration ID nếu có, rồi nhấn Save app. omniVN kiểm tra cặp App ID/Secret với Meta, mã hoá App Secret và không bao giờ hiện lại; đừng gửi App Secret qua chat hay email. Sau đó nút Connect Meta Ads sẵn sàng. Không dùng token từ Graph API Explorer.

7. Nhấn Connect Meta Ads và chọn Ad Account

Trong omniVN → Integrations → Meta → Connect Meta Ads. Đăng nhập Facebook bằng tài khoản có role, đồng ý cấp quyền. 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.

8. Cách thay thế: kết nối bằng token System User

Business Settings → Người dùng hệ thống → Thêm (vai trò Nhân viên). Gán tài sản: Ad Account (Xem hiệu quả), Page và Instagram (Thông tin chi tiết; thêm Hoạt động cộng đồng nếu cần bài đăng và bình luận), app của doanh nghiệp (Thử nghiệm ứng dụng). Tạo mã cho đúng app đã lưu trong omniVN, chọn thời hạn và tối thiểu quyền ads_read. Trong omniVN → Integrations → Meta → Use a system-user token instead, dán token. omniVN kiểm tra token với Meta, mã hoá và không bao giờ hiển thị lại.

Á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
App ID	app_id	Bắt buộc	user_entered App settings → Basic trên app Meta của doanh nghiệp. Hiện omniVN nhận qua operator (receiveAdsByoApp), chưa có form trên workspace.
App Secret	app_secret	Bắt buộc	user_entered App settings → Basic → Show. omniVN niêm phong vào secret store, không trả ra trình duyệt.
Configuration ID	config_id	Tùy chọn	user_entered Facebook Login for Business → Configurations. Khi có, dialog gửi config_id thay cho scope=ads_read (Meta khuyến nghị).
Access Token	access_token	Bắt buộc	oauth_authorization Cấp sau Facebook Login; omniVN đổi code và gia hạn ~60 ngày, lưu secret store.
Ad Account ID	ad_account_id	Bắt buộc	oauth_authorization Chọn từ /me/adaccounts sau OAuth, không nhập tay.

appId, appSecret, loginConfigId → app BYO của doanh nghiệp; chủ hoặc admin workspace dán vào form trên trang Meta, omniVN kiểm tra với Meta rồi mã hoá vào secret store. accessToken → secret store sau OAuth hoặc sau khi dán token System User; adAccountId → act_… chọn từ /me/adaccounts. Không dán token từ Graph API Explorer.

Vòng đời token

Code đổi thành token ngắn hạn rồi gia hạn bằng fb_exchange_token (~60 ngày). omniVN gia hạn token còn hạn khoảng 7 ngày trước khi hết. Token hết hạn, đổi mật khẩu, thu hồi quyền app hoặc gỡ role của người kết nối thì phải Connect lại. Token System User đặt Không bao giờ hết hạn thì không cần gia hạn và không phụ thuộc tài khoản cá nhân; thu hồi nó trong Business Settings.

Lỗi thường gặp

Connect báo Ads BYO app not received hoặc nút chưa sẵn sàng

Workspace chưa lưu App ID/Secret của app Meta. Chủ hoặc admin dán chúng ở khung “Register your Meta app” trên trang Meta Ads rồi thử lại.

Facebook: Không thể tải URL / miền chưa đưa vào Miền ứng dụng (App Domains)

App Domains hoặc Website Site URL chưa có omnivn.com / oauth.omnivn.com, hoặc redirect URI chưa có trong Valid OAuth Redirect URIs. Sửa rồi bấm Connect lại từ omniVN; đừ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

Người kết nối không có role trên app (Standard Access chỉ cho role users), từ chối ads_read, hoặc không có quyền trên Ad Account đã chọn. Chỉ cần Advanced Access (App Review, xác minh doanh nghiệp) nếu người không có role phải kết nối.