Meta (Facebook and Instagram ads)

Reads campaigns and ad sets, daily spend by country, per-ad results (video views, plays to the end, link taps) and spend by placement (Facebook Feed, Instagram Reels, Audience Network…).

"meta": { "enabled": true, "adAccounts": ["act_1234567890"] }

Token

Earnback needs one access token with the ads_read permission, saved as meta-token (a text file with just the token, or the EARNBACK_META_TOKEN environment variable).

System user token (recommended, doesn’t expire):

1. Create an app at developers.facebook.com/apps (type Business) and add the Marketing API product.
2. In Business settings → Users → System users, add a system user (role Employee is enough).
3. Assign assets: give it your ad account with View performance only.
4. Generate new token for your app with the ads_read permission, no expiry.
5. Save the token as meta-token in your secrets folder.

Long-lived user token (simpler, expires after 60 days): in the Graph API Explorer, pick your app, add ads_read, generate a token, then extend it in the Access Token Debugger. You will need to repeat this every two months.

What it reads

• Campaigns (including deleted ones that still have spend in the period) with their ad sets’ budgets, schedule, optimisation goal and targeting summary.
• Daily spend, impressions and link clicks per campaign and country.
• Per ad and day: spend, impressions, link clicks, 3-second video plays and ThruPlays (played to the end, or for 15 seconds on longer videos). These feed the hook, hold and tap rates.
• Spend per platform and position.

The last 28 days are re-read on every sync (Meta’s attribution window).

Caveats

• Meta can’t see installs unless its SDK is in your app. Earnback doesn’t use Meta’s install counts: players come from GA4, which recognises Meta’s Install button by the store referrer (apps.facebook.com, fb4a, Instagram). Expect Meta players to be undercounted; the Unknown bucket holds the rest.
• “Taps” are link clicks (taps on Install or the link), not all clicks.
• Lifetime budgets are shown as lifetime, not divided into days.

Errors