Hướng dẫn kết nối dữ liệu Marketing

1. Cách hoạt động#

• Vào Kết nối → nhóm Marketing & Web → bấm + Kết nối trên connector cần dùng.
• Khoá bí mật được mã hoá envelope (AES‑GCM) ngay khi lưu — không hiển thị lại được; sửa đổi = dán khoá mới đè lên. Không gửi khoá qua chat/email, dán trực tiếp vào form.
• Sau khi lưu, bấm Kiểm tra — hệ thống gọi một API đọc-nhẹ để xác nhận khoá dùng được.
• Có thể bấm Kiểm tra ngay trong form trước khi lưu; probe dùng đúng config không-secret và credential đang nhập. Test xanh chỉ chứng minh quyền đọc nhẹ, không chứng minh dữ liệu lịch sử/reconciliation.
• Đồng bộ chạy tự động theo lịch (mặc định theo connector) và luôn kéo lùi một cửa sổ (lookback) để nhận số liệu nguồn tự điều chỉnh: GA4 kéo lùi 3 ngày (GA4 tự điều chỉnh tới ~72h), Search Console 5 ngày (số trễ 2–3 ngày).
• Chỉ chủ sở hữu / quản trị viên tổ chức thêm được kết nối. Mỗi nền tảng một khoá cho mỗi thương hiệu theo chính sách vận hành. Database hiện chưa enforce uniqueness platform/brand; tránh tạo row trùng cho tới khi schema/RLS change được phê duyệt.
• Đồng bộ tay cho marketing luôn dùng rolling lookback của connector. Bounded date-range backfill chưa hỗ trợ; UI không gửi marketing job sang order/file queue và sẽ từ chối mode không hợp lệ.

2. Google Tag Manager — KHÔNG cần connector#

GTM là công cụ triển khai tag, không có API số liệu để ingest. Số liệu website đi qua GA4: chỉ cần trong GTM đã bắn tag GA4 (Google tag / GA4 Configuration) về đúng Property ID sẽ kết nối ở mục 3 — dữ liệu sessions/users/conversions sẽ tự chảy về qua connector GA4. Không có việc gì phải làm thêm ở GTM.

3. Service account Google dùng chung (làm MỘT lần cho cả GA4 + Search Console)#

1. Vào console.cloud.google.com → chọn (hoặc tạo) một project cho công ty.
2. APIs & Services → Library → bật (Enable) 2 API:
   • Google Analytics Data API
   • Google Search Console API
3. IAM & Admin → Service Accounts → Create service account — đặt tên gợi nhớ, ví dụ ucip-marketing-reader. Không cần cấp role nào ở bước IAM (quyền cấp ở phía GA4/GSC).
4. Mở service account vừa tạo → tab Keys → Add key → Create new key → JSON → tải file JSON về. File này là khoá bí mật — sẽ dán nguyên văn vào form.
5. Ghi lại email của service account (dạng ucip-marketing-reader@<project>.iam.gserviceaccount.com) — 2 mục dưới sẽ mời email này vào GA4 và GSC.

4. Google Analytics 4#

Cấp quyền (người quản trị GA4 làm):

1. GA4 → Admin → Property access management → + → dán email service account ở mục 3 → vai trò Viewer là đủ (connector chỉ đọc, scope analytics.readonly).
2. Lấy Property ID: Admin → Property settings → con số ở góc phải (ví dụ 123456789). Không phải Measurement ID G-XXXX.

Điền form (Kết nối → Google Analytics 4):

Bấm Kiểm tra → trạng thái xanh nghĩa là service account đọc được property. Dữ liệu về: phiên truy cập, người dùng, người dùng mới, phiên tương tác, sự kiện chính, doanh thu GA4 — theo ngày × nhóm kênh, xem tại Hiệu quả Marketing → Website & Tìm kiếm.

5. Google Search Console#

Cấp quyền (chủ sở hữu property GSC làm):

1. search.google.com/search-console → chọn property → Settings → Users and permissions → Add user → dán email service account → quyền Restricted là đủ (chỉ đọc, scope webmasters.readonly).
2. Ghi lại Site URL ĐÚNG NGUYÊN VĂN như GSC hiển thị — đây là lỗi kết nối phổ biến nhất:
   • Domain property → sc-domain:example.com
   • URL-prefix property → https://example.com/ (đủ cả https:// và / cuối)

Điền form (Kết nối → Google Search Console):

Dữ liệu về: lượt nhấp, hiển thị, CTR, vị trí trung bình theo site/ngày + top 200 truy vấn/ngày — xem tại Hiệu quả Marketing → Website & Tìm kiếm. Lưu ý: số theo-ngày và số theo-truy-vấn không cộng khớp nhau (Google ẩn truy vấn hiếm để bảo vệ riêng tư — đây là hành vi của Google, không phải lỗi). Core hiện chưa ingest grain page/country/device.

6. Google Ads#

Cần 5 khoá + 1 mã tài khoản. Người có quyền quản trị tài khoản MCC (Manager) làm. UCIP hiện dùng credential khách cung cấp; host-owned OAuth app/callback "bấm Connect" chưa được build:

1. Developer Token: đăng nhập tài khoản MCC → Tools & settings → Setup → API Center → xin token. Mức Basic access là đủ để đọc số liệu tài khoản trong MCC (mức Test chỉ gọi được tài khoản test — phải nâng lên Basic trước khi kết nối thật).
2. OAuth client: Google Cloud Console (project mục 3 dùng được) → APIs & Services → Credentials → Create credentials → OAuth client ID → loại Desktop app → lấy Client ID + Client Secret. Bật Google Ads API trong Library.
3. Refresh Token (một lần): vào developers.google.com/oauthplayground → bánh răng ⚙ → tick Use your own OAuth credentials → dán Client ID/Secret ở bước 2 → Step 1 nhập scope https://www.googleapis.com/auth/adwords → Authorize APIs (đăng nhập bằng tài khoản Google CÓ QUYỀN trên MCC) → Step 2 Exchange authorization code for tokens → copy Refresh token. (Nếu OAuth client ở trạng thái Testing, refresh token hết hạn sau 7 ngày — chuyển app sang In production để token sống lâu.)
4. Customer ID: mã 10 số của tài khoản Ads cần kéo số (góc phải màn hình Google Ads, 123-456-7890). Login Customer ID: mã MCC (điền khi truy cập tài khoản con qua MCC; để trống nếu kết nối thẳng tài khoản lẻ).

Điền form (Kết nối → Google Ads): Client ID · Client Secret · Refresh Token · Developer Token · Login Customer ID (tuỳ chọn) · Customer ID.

Lưu ý: connector chỉ nhận tài khoản đơn vị tiền VND — tài khoản ngoại tệ sẽ báo lỗi GOOGLE_ADS_NON_VND_ACCOUNT (chưa có quy đổi tỷ giá ở bản này).

7. Meta Ads (Facebook/Instagram)#

Đường khuyến nghị cho khoá vận hành: System User trong Business Manager (ít phụ thuộc tài khoản cá nhân). "Never expire" vẫn có thể bị revoke do quyền, app secret, asset ownership hoặc policy. Người quản trị Business làm và phải xác nhận app/access requirements trong Meta tooling:

1. business.facebook.com/settings → Users → System users → Add → loại Employee (đủ để đọc) → tạo. (Cần một App trong Business: Accounts → Apps → Add — app loại Business, không cần lên review vì chỉ đọc tài sản của chính Business.)
2. Chọn system user → Add assets → Ad accounts → chọn tài khoản quảng cáo → bật quyền View performance.
3. Generate new token → chọn App → chọn thời hạn Never expire (60 ngày nếu tổ chức yêu cầu xoay vòng) → tick scope ads_read (thêm read_insights nếu có) → copy token.
4. Ad Account ID: trong Ads Manager, mã dạng act_1234567890 (dán cả act_...).

Điền form (Kết nối → Meta Ads): Access Token · Ad Account ID.

Runtime core hiện pin Meta Graph API v23.0; onboarding phải xác nhận app còn hỗ trợ version này trước khi test. Nâng API version là code/test change, không sửa riêng trong guide.

Cũng chỉ nhận tài khoản VND; token bị thu hồi (đổi quyền/xoá system user) sẽ hiện lỗi vĩnh viễn ở nhật ký đồng bộ — tạo token mới và dán lại.

8. TikTok Ads#

1. business-api.tiktok.com → Become a developer → tạo App (loại Business), xin scope Reporting (đọc báo cáo).
2. Từ trang app → Authorization → mở link uỷ quyền → đăng nhập tài khoản có quyền trên TikTok Ads Manager → duyệt advertiser → hệ thống trả long-term Access Token.
3. Advertiser ID: trong TikTok Ads Manager (mã số dài, xem ở Account settings).

Điền form (Kết nối → TikTok Ads): Access Token · Advertiser ID.

Lưu ý hiển thị: TikTok chưa xác nhận được ngữ nghĩa "giá trị chuyển đổi" qua API — cột giá trị chuyển đổi/ROAS của TikTok Ads hiển thị — (không bịa số), các cột chi tiêu/hiển thị/nhấp/chuyển đổi đầy đủ.

9. Shopee Ads#

1. open.shopee.com → đăng ký Open Platform app (loại Shop Authorized App) → lấy Partner ID + Partner Key.
2. Chạy luồng uỷ quyền shop (Authorization link từ console) → chủ shop đăng nhập duyệt → nhận Shop ID + Access Token + Refresh Token.
3. Connector tự làm mới token khi hết hạn (nếu có Refresh Token) và tự lưu cặp token mới.

Điền form (Kết nối → Shopee Ads): Partner ID · Partner Key · Access Token · Refresh Token (tuỳ chọn) · Shop ID.

⚠️ Đối chiếu lần đồng bộ đầu: API Shopee không trả trường đơn vị tiền — sau lần kéo số đầu tiên PHẢI so sánh tổng chi tiêu trên dashboard với số trong Shopee Seller Center cùng kỳ trước khi tin số. Nếu lệch thang (×1000…), báo đội phát triển điều chỉnh — tuyệt đối không tự nhân hệ số.

10. Gắn một tab Google Sheets hoặc một model Odoo vào Bộ dữ liệu (HR/Tài chính)#

Mục này dành cho workspace bộ dữ liệu riêng (HR hôm nay, Tài chính tiếp theo — ADR 0038/0048/0049), KHÔNG phải workspace Marketing ở trên. Google Sheets vẫn là MỘT connector — chỉ khác đường xử lý: một tab bind vào Bộ dữ liệu đi qua dataset_record, không đi qua các bảng chuẩn Marketing.

• Sheet. Vào Kết nối → nhóm Marketing & Web → kết nối connector-google-sheets như bình thường (mục 1). Sau đó vào Bộ dữ liệu → chọn dataset (hoặc tạo mới từ tab) → Kết nối → chọn tab → "Bộ dữ liệu": nền tảng lấy mẫu tab và ĐỀ XUẤT khung trường (kiểu dữ liệu, chiều/số đo), người quản trị XÁC NHẬN từng trường và khai báo grain (khoá tự nhiên của một dòng — ví dụ tháng + pháp nhân + mã tài khoản + trung tâm chi phí), rồi ánh xạ cột và gắn (connectors.bindDatasetTab). Một tab chỉ bind được khi DÒNG CỦA TAB LÀ BẢN GHI — không join hai tab, không tách một dòng thành nhiều kỳ, không gộp sẵn ở mức thô hơn khai báo (ADR 0038 amendment (b)).
• Odoo (connector-odoo-hr, chưa bật mặc định). Sau khi kết nối, vào Bộ dữ liệu → chọn dataset ĐÃ CÓ (không tạo mới từ đây — nguồn Odoo không mang theo dòng mẫu để đề xuất khung trường, khác Sheet ở trên) → Đọc lại danh sách nguồn (connectors.listDatasetSources, gọi trực tiếp hr.employee/hr.contract/hr.applicant/hr.leave/hr.attendance) → ánh xạ cột và gắn (cùng connectors.bindDatasetTab, nhận sourceKey là tên model thay vì dải ô). Một dataset đã có tab Sheet có thể chuyển sang nguồn Odoo cùng cách này — cùng một dòng lịch sử mẫu ánh xạ, không tạo dòng thứ hai. Mức sẵn sàng: mã đã có (ADR 0049), CHƯA có xác nhận kết nối thật với một Odoo instance — cùng nguyên tắc "có code chưa phải đã kết nối live" đã nêu ở trên; probe kiểm chứng: scripts/connectors/probe-odoo-hr.ts.
• Trường nhạy cảm (lương, chi phí nhân sự…) đọc được chỉ khi người xem có quyền tương ứng của tổ chức — một quyền brand không phải một quyền lương (ADR 0038 D6 + amendment (f)); từ chối hiện ra là dấu gạch ngang có lý do, không bao giờ là số 0.

11. Sau khi kết nối#

1. Bấm Kiểm tra trên từng kết nối — xanh là khoá dùng được.
2. Chờ lượt đồng bộ đầu (hoặc bấm đồng bộ tay nếu có) — dữ liệu đổ vào các bảng chuẩn và hiện ở Hiệu quả Marketing: Tổng quan (GMV/Chi phí – MER, ngân sách), Quảng cáo (từng nền tảng + chiến dịch), Website & Tìm kiếm (GA4 + Search Console).
3. Nguyên tắc số liệu: chỉ CHI TIÊU được cộng gộp giữa các nền tảng; chuyển đổi/giá trị/ROAS là số từng nền tảng tự báo cáo, không bao giờ cộng chéo; MER tính trên đơn hàng thật của sàn, không phải conversion của nền tảng quảng cáo.

Lỗi thường gặp