Facebook Ads Integration with PostTrack (via System User)

The connection is made by your Business Manager administrator. All steps take 10–15 minutes.

---

What You'll Need

• Administrator access to your Business Manager.
• Our App ID (PostTrack app in Meta for Developers).
• Ability to create System User in your BM.
• System User token with ads_read permission (optionally business_management for reading BM structure).

---

Step 1. Add PostTrack App to Your BM

1. Open Business Settings.
2. Go to Accounts → Apps → Add → Connect an App ID.
3. Paste PostTrack App ID and confirm.

---

Step 2. Create System User (Read-Only)

1. Business Settings → Users → System Users → Add.
2. Type: Employee.
3. Name: e.g., PostTrack Read SU.

---

Step 3. Link System User to App

1. Open the created System User card.
2. Add Assets → Apps → select PostTrack → Assign.

---

Step 4. Give System User Access to Ad Accounts

1. In System User card, click Add Assets → Ad Accounts.
2. Select all needed accounts.
3. Role: Ad Account Analyst (read-only).
4. If available — enable option for all current and future accounts.

   To read creatives/catalogs, additionally grant Read on Catalogs / Pixels.

---

Step 5. Generate System User Access Token

1. In System User card, click Generate New Token.
2. App: PostTrack.
3. Duration: maximum available.
4. Permissions (scopes): minimum ads_read and read_insights, optionally business_management (read).
5. Copy Access Token and save.

---

Step 6. Insert Token in PostTrack

1. In PostTrack: Integrations → Meta Ads → Secure Mode (System User).
2. Paste Access Token and save — validation and import will begin.

---

What PostTrack Does After Token Insertion

1. Token validation:
   • GET https://graph.facebook.com/v19.0/me?access_token=...
   • (optionally) GET /debug_token with App Token.
2. Account import:
   • GET https://graph.facebook.com/v19.0/me/adaccounts?limit=500 (with pagination).
   • Save act_id, name, currency, status, visible=true.
3. Cross-check with expected (if CSV with act_id was uploaded).
4. Synchronizations:
   • Insights every hour: https://graph.facebook.com/v19.0/act_{AD_ACCOUNT_ID}/insights at account|campaign|adset|ad levels, window today + last 7–14 days.
   • Discovery every 30–60 min: repeat me/adaccounts.
   • History backfill — in batches.
5. Monitoring:
   • 403/permissions → visible=false, notification.
   • Rate-limit → automatic backoff and window narrowing.

---

Verification (Checklist)

• SU is linked to App, role Ad Account Analyst on needed accounts.
• Token has ads_read (optionally business_management).
• GET /me/adaccounts returns all needed act_....
• In PostTrack, source is visible, account list and fresh data (today/yesterday).
• No persistent 403/190 in logs.

---

Common Errors and Solutions

Symptom	Cause	Solution
In assignments only see Apps/WhatsApp, no "Ad Accounts"	Assignment not at System User or no Admin rights	Open Users → System Users → your SU → Add Assets → Ad Accounts; verify Business Admin role
Not all accounts visible	SU not granted Analyst on some accounts	System User → Add Assets → Ad Accounts and add missing ones
190: Token expired/invalid	Token expired/created without needed scope	Generate new token with ads_read and replace
200/10: Insufficient permissions	Insufficient permissions at account level	Ensure SU has Analyst on this account
429/Rate limit	Too frequent requests	Wait; PostTrack will slow down frequency and narrow window

---

Security

• We store tokens encrypted (field-level AES-GCM; keys in KMS).
• Grant only read-only access, regularly revoke old tokens.
• Integration access — only for trusted users.

---

FAQ

Is ads_management needed? No, ads_read is sufficient. Accounts from different BMs? Yes, if those BM owners grant your SU Analyst role or give partner access to your BM. How to add new accounts later? Grant SU Analyst role on them — PostTrack will find them automatically within an hour. Different currencies? Not a problem: analyze by accounts or use conversion in PostTrack.