Meta Ads

Meta Ads — launch and verification

Everything here was learned by getting it wrong in production first. The API rejections are real rejections, the permission chain is the one that actually unblocks, and the verification section exists because measuring the wrong thing produced three confidently-wrong conclusions in a single session.

1. Verification comes first, because it is where the damage happens

Read this before believing any test result.

Three separate false negatives in one launch. Each looked like a real bug. Each was the instrument, not the system.

The pattern: absence of evidence was read as evidence of absence, from an instrument that structurally could not observe the thing being measured. Before concluding something is broken, ask what the instrument can actually see.

Confounded variables. One "isolation test" removed two variables at once and the wrong one got the blame. Change one thing.

2. The permission chain (the part that actually blocks you)

To create ads via API you need four separate grants. Missing any one gives a different, unhelpful error.

1. A Meta app — you almost certainly already have one; don't create a new one.
2. The system user has a ROLE ON THE APP. Business Settings → Apps → app → Assign people → pick the system user → Develop app. Skipping this gives No permissions available — assign an app role to the system user at the token-generation step, with no hint about which grant.
3. The system user has the ASSETS. System Users → user → Assign assets:
   • Ad account → Manage campaigns (not "Manage ad accounts", which is finances and permissions)
   • Page → Ads only
   • Pixel/dataset → Use events dataset
4. Generate the token — System Users → Generate token → app → Never expiry → tick ads_management.

Two more that only surface at ad-creation time:

• Instagram account connected to the ad account. Advantage+ placements include IG, and creation fails with "Ad account has no access to this Instagram account". Fix: Business Settings → Instagram accounts → account → Connect assets → the ad account.
• The app must be Live, not Development. "Ads creative post was created by an app that is in development mode". Publishing needs a Privacy Policy URL and a Category, then Publish. Development mode blocks creative creation only — the rest of the API works, so this fails late.

Expiry: prefer Never for a system-user token you control. A time-boxed token lapses silently and takes the integration with it.

3. Special Ad Category (Employment, Housing, Credit)

Employment strips the targeting you would normally rely on:

• no age or gender targeting — Meta forces 18–65, all genders
• no detailed interest or behaviour targeting
• minimum 15-mile radius on location targeting
• no earnings claims anywhere — "$2k/week", "/hr", "$X per job" are rejection risk even when true

Consequence: the creative IS the targeting. With no interest targeting, the only thing making the right person recognise themselves is the ad itself. Put the audience identifier in the image as literal words — SAVANNAH DIESEL MECHANICS — not a clever hook.

Guard the money rule in code, in every place copy can be edited, and fail loudly:

jsCopy code
const MONEY = /\$\s?\d|\b\d+\s?(k|dollars|usd)\b|\bper hour\b|\/hr\b/i;

Avoid "now hiring" for contractor work — it pulls W2 job seekers who click, fail qualification, and cost money on the way through.

4. Creative: the crop-safe zone

A 1080×1920 asset is cropped for feed placements. 4:5 removes ~285px from each end; 1:1 removes ~420px. Anything near the top or bottom is destroyed in exactly the placement where most impressions land.

Keep every critical element inside the 1:1 safe band: y 420 → 1500. Stack the identifier, caption and CTA as one block centred in that band, so the whole message survives any crop.

Verify by simulating the crops rather than trusting the full-size render:

jsCopy code
for (const h of [1350, 1080]) {
  await sharp(file).extract({ left: 0, top: (1920 - h) / 2, width: 1080, height: h })
    .toFile(`crop_${h}.jpg`);
}

Then look at the ad preview in Ads Manager, which renders each placement for real. That is what caught the cropped identifier.

Native caption look: IG/TikTok put a rounded box behind each individual line, not one flat band — a single band reads as a slide. Heavy bold-italic in a system sans, not a brand face. No fake platform chrome (progress bars, reply boxes, swipe-up arrows) — Meta rejects creative that mimics its UI, but a plain caption band is fine.

Auto-fit rather than trusting copy length. SVG cannot size a rect to its own text, so estimate width and shrink until it fits. Italic overhangs its advance width — widen horizontal padding when italic is on.

Opt out of Advantage+ creative enhancements. They auto-crop and overlay text. The API field standard_enhancements is deprecated with a moving per-feature replacement, so set it in the UI. Check degrees_of_freedom_spec on the creative to confirm advantage_plus_creative: OPT_OUT.

5. Campaign creation — the rejections, in order

Each of these is a real 400 that stops creation. Fix them up front.

jsCopy code
// CAMPAIGN
{
  objective: 'OUTCOME_LEADS',
  status: 'PAUSED',
  special_ad_categories: ['EMPLOYMENT'],
  buying_type: 'AUCTION',
  is_adset_budget_sharing_enabled: false,  // required when budget is on the ad set
}

// AD SET
{
  daily_budget: 3000,                       // CENTS
  billing_event: 'IMPRESSIONS',
  bid_strategy: 'LOWEST_COST_WITHOUT_CAP',  // required; a cap throttles a cold pixel
  optimization_goal: 'OFFSITE_CONVERSIONS',
  promoted_object: { pixel_id, custom_event_type: 'LEAD' },
  targeting: {
    geo_locations: { custom_locations: [{ latitude, longitude, radius: 25, distance_unit: 'mile' }] },
    age_min: 18, age_max: 65, genders: [1, 2],
  },
}

Errors and their causes:

The null budget was a caller bug worth remembering: argv[argv.indexOf('--flag') + 1] returns argv[0] when the flag is absent, because indexOf gives -1. Number('--apply') is NaN, which JSON.stringify turns into null. Guard the flag's presence and range-check before sending.

Always create PAUSED, verify, then enable deliberately.

Clean up orphans. A failed run leaves a campaign or ad set behind; delete it before retrying or you accumulate duplicates.

6. Conversion tracking that is actually proven

Both paths, one event id. Browser pixel and server CAPI send the same event_id; Meta collapses them into one conversion. The server path survives ad blockers — roughly a third of an audience — so it is not optional.

The browser must forward what the server cannot know:

jsCopy code
meta: {
  event_id: evId,
  event_source_url: window.location.href,
  fbp: cookie('_fbp'),   // first-party cookies on YOUR domain; the function
  fbc: cookie('_fbc'),   // runs elsewhere and never receives them otherwise
}

Make the server report its own outcome. A CAPI call is correctly non-fatal — losing an attribution event must never fail a form submission — which means it can rot silently forever. Return the result:

tsCopy code
return jsonResponse({ success: true, id, meta_capi: result.ok ? `sent:${n}` : `failed:${err}` })

One curl then proves the whole server path in isolation. This is the only thing that definitively settled it.

Fire events on what you mean. A Schedule fired when a calendar renders means "someone saw a calendar", not "someone booked" — optimising toward it trains Meta to find people who arrive and leave. Use the embed's own success callback (bookingSuccessful for Cal.com) and make the rendering a custom event.

Optimise for volume, measure on truth. Meta needs ~50 conversions/week per ad set to leave learning. If the true outcome is rarer than that, bid on the higher-volume upstream event and keep the real one for reporting.

Watch for automatic events. Meta's automatic event detection invents events (e.g. Subscribe) from form interactions. They can pollute optimisation — disable in pixel settings.

7. CSP will silently break all of it

If the site sends a Content-Security-Policy, these must be allowed or the pixel and any embed die with no visible error:

Copy code
script-src   https://connect.facebook.net  https://app.cal.com
connect-src  https://www.facebook.com  https://connect.facebook.net
frame-src    https://www.facebook.com   (+ any embed origin)

Blocked fbevents.js leaves fbq as the inline stub: it queues events and sends nothing, forever.

The check that detects it:

jsCopy code
typeof window.fbq.callMethod === 'function'   // real library loaded
window.fbq.queue.length                        // >0 and growing = stub, blocked

fbq.loaded and fbq.version are set by the inline stub and prove nothing.

Launch checklist

• System user has app role, ad account, Page, pixel
• App published (not Development)
• Instagram connected to the ad account
• Token ads_management, Never expiry
• Copy contains no money figures — guarded in code
• Creative content inside y 420–1500; crops simulated
• Advantage+ creative enhancements OPT_OUT
• Created PAUSED; ad previews checked in Ads Manager
• fbq.callMethod is a function on the deployed site
• Lead confirmed Processed in Test Events
• Server CAPI confirmed sent:N via its own response
• Test records deleted from the database afterwards
• Token revoked/rotated if it appeared in any transcript or log