Bring In Ads & Meta Sync
Complete guide to connecting Meta Ads Manager, generating System User Tokens, and managing asset ingestion.
Meta Ads Manager is the primary source of truth for live campaigns, historical retention curves, and financial metrics (Spend, ROAS, CPA, CTR). Ingestion syncs campaigns, ad sets, ads, video files, and static image assets into your Brand Room.
1. Connecting Meta Ads Manager
You can connect your Meta account via the Dashboard Onboarding Banner, the Sidebar Platform Status badge, or under Settings → Integrations (/settings/integrations).
sequenceDiagram
actor User as Media Buyer
participant App as AdHelix App
participant Meta as Meta Graph API
User->>App: Click "Connect Meta Business Account"
App->>Meta: OAuth Request (ads_read, read_insights, business_management)
Meta-->>User: Meta Authentication & Asset Selection Modal
User->>Meta: Authorize Ad Accounts
Meta-->>App: Access Token Exchanged
App->>Meta: Trigger Initial Sync (Campaigns, Creatives, Video URLs)
App-->>User: Initial Ingestion Complete 🎉Required Meta Graph API Permissions
AdHelix operates strictly with read-only permissions and never modifies live bids, budgets, or ad statuses without user approval:
ads_read: Read ad creatives, copies, headlines, and placements.read_insights: Pull hourly and daily spend, impression, video play, and conversion metrics.business_management: Discover accessible Ad Accounts across your Business Portfolio.
2. Generating Long-Lived System User Tokens
For production deployments, agency multi-brand environments, or 24/7 automated midnight sync runs, we strongly recommend generating a System User Token in Meta Business Manager:
- Open Meta Business Settings (
business.facebook.com/settings/system-users). - Click Add to create a new System User with the role of Admin.
- Under Assigned Assets, assign the target Ad Accounts with View Performance / Manage Campaigns permissions.
- Click Generate New Token:
- Select the App ID.
- Choose Token Expiration: Never (Permanent).
- Check the scopes:
ads_read,read_insights,business_management.
- Copy the generated access token and paste it into Settings → Integrations → System User Token in AdHelix.
3. Ingestion Pages & Asset Navigation
Once connected, data is organized across four dedicated views:
| View | Path | Purpose |
|---|---|---|
| Campaigns | /campaigns | Browse live Meta campaign hierarchy down to Ad Sets and Ads |
| Creative Library | /creatives | View synced creative variants, filter by status, and launch analysis |
| Asset Library | /assets | Manage media files, direct uploads, and custom video drafts |
| Queue & Processing | /analysis | Real-time analysis status tracker, batch queue, and token telemetry |
4. Troubleshooting Empty Syncs
| Symptom | Probable Cause | Resolution |
|---|---|---|
| No campaigns displayed | Wrong Ad Account selected | Click the top-left switcher and verify the active Meta Ad Account ID (act_...). |
| "Meta Token Expired" alert | OAuth session invalidated | Re-authenticate via Settings → Integrations or supply a permanent System User Token. |
| Missing video files | Direct unpublished post | Ensure the ad creative has completed Meta ad review and has accumulated at least 1 impression. |
| Currency formatting mismatch | Multi-currency ad accounts | AdHelix dynamically formats spend in the local currency of the active Ad Account (USD, EUR, CHF, GBP). |
[!IMPORTANT] Automated Sync Cadence: Ingestion automatically syncs rolling 7-day and 30-day performance curves every night at 00:00 UTC. To force an immediate on-demand refresh, click the Sync Now button on
/campaigns.