Meta Ads (Facebook / Instagram)

Priority: 2

Overview

Meta covers social prospecting and retargeting for all verticals. Accounts are provisioned under Kobico's parent Business Manager (BM) using Meta’s official 2-Tier Business Manager solution — one child BM per client (ADR 0003). Clients never own ad accounts; they consent via portal OAuth and retain Page/IG assets.

Account model (ADR 0003 — 2-Tier only)

Element	Approach
Parent BM	Kobico agency BM — extended credit, business verification (PRE-2, PRE-8), pays Meta
Per tenant	Child BM via `POST /{parent_bm_id}/owned_businesses`
Automation identity	Admin system user inside each child BM — long-lived token in Secret Manager (per tenant)
Client consent	Facebook Login for Business — user token + shared Page (`shared_page_id`)
Page for ads	Linked at child BM create → verify `GET /{child_bm}/client_pages`
Naming	Child BM / ad account: `kobi_{tenant_slug}_meta`

Meta allows at most 5 API ad accounts on one BM — Kobico uses one child BM per client.

Token model

Action	Token
Create child BM	Client user access token (OAuth) — `owned_businesses`
Create child system user token	Parent system user — `POST /{child_bm}/access_token`
Ad account, pixel, campaigns, catalog	Child BM system user
Share parent LOC to child	Parent BM admin — PRE-2

2-Tier onboarding flow (summary)

Client accepts ToS + data sharing in Kobico portal.
Connect Meta & Instagram — Facebook Login for Business → client picks Facebook Page (+ linked IG).
Backend: POST /{parent_bm_id}/owned_businesses with user token, shared_page_id, child BM name — owned_businesses.
Create Admin system user in child BM — System users.
POST /{child_bm_id}/adaccount + spend_cap from plan — Ad account.
Pixel, catalog (SKU) — Page via client_pages after owned_businesses; CAPI v2

Detail: provisioning spec §5 / §5b.

By default the client does not access the child BM UI; Kobico operates it agency-managed (2-Tier overview).

Access & API readiness

Requirement	Link / ID
2-Tier program access	PRE-10 — Meta rep (platform access)
Marketing API tiers	Limited → Full (rate limits)
App permissions	`ads_management`, `ads_read`, `business_management`, Page/IG scopes — cross-check §4
Extended credit on parent BM	PRE-2
Kobico entity business verification	PRE-8

Onboarding checklist (2-Tier path)

Client Connect Meta & Instagram (OAuth) — required for child BM + Page/IG
Create child BM (owned_businesses)
Create child system user + store token
Create ad account in child BM + spend_cap from plan_id
Pixel + verify client_pages + IG link
Auto-generate implementation pack — vertical browser events, UTM, domain verify (v1)
Catalog + feed (ecommerce SKU) — v1; CAPI relay + offline event set — v2
Domain verification — client DNS if required for optimization events

Not required: client as ad account owner, client BM admin, client payment method on Meta.

Dev verification (2-Tier, Jun 2026)

Engineering spike in app Development mode — scripts in meta-dev/. Confirms ADR 0003 onboarding sequence after one user OAuth consent (Graph API Explorer used for user token in spike; portal Login for Business in product).

Asset	API (child system user unless noted)	Dev status
Child BM	`owned_businesses` (user token)	✅ Verified
Child system user	`POST /{child_bm}/access_token` (parent system user)	✅ Verified
Ad account	`POST /{child_bm}/adaccount`	✅ Verified
Pixel	`POST /act_{id}/adspixels`	✅ Verified
Page on child BM	`GET /{child_bm}/client_pages`	✅ Verified
Catalog	`POST /{child_bm}/owned_product_catalogs` (child token)	⬜ After Catalog App Review + PRE-8
Product set	`POST /{catalog}/product_sets`	✅ Verified
Product feed	`product_feeds` + `uploads?url=`	✅ Verified — `criteo.php` → 87 products, 0 errors
Parent LOC → child	`owning_credit_allocation_configs`	⬜ PRE-2 production

Registry fields validated: parent_bm_id, child_bm_id, child_system_user_id, meta_ad_account_id, meta_pixel_id, meta_catalog_id, meta_product_set_id.

Open for production: PRE-10 (2-Tier at scale), PRE-2 (extended credit), Catalog API App Review + PRE-8 (child-owned catalog — required for ecommerce SKU). spend_cap from billing module (dev: run-2tier-phase5-verify.ps1).

Pixel from Graph: GET /{pixel-id}?fields=code,last_fired_time,… — runbook §2.

Official docs

Topic	URL
2-Tier BM solution	https://developers.facebook.com/docs/marketing-api/2tier-bm-solution/
Setup child BM	https://developers.facebook.com/docs/marketing-api/2tier-bm-solution/guides/setup-cbm/
Onboard at scale	https://developers.facebook.com/docs/business-sdk/common-scenarios/onboard-at-scale/
`owned_businesses`	https://developers.facebook.com/docs/marketing-api/reference/business/owned_businesses/
System users	https://developers.facebook.com/docs/marketing-api/system-users
Ad account API	https://developers.facebook.com/docs/marketing-api/reference/ad-account
Marketing API overview	https://developers.facebook.com/docs/marketing-apis
Facebook Login for Business	https://developers.facebook.com/docs/facebook-login/facebook-login-for-business/
Ad account limits (Help Center)	https://www.facebook.com/business/help/1026272311098874

Internal: ADR 0003 · Implementation pack · B1 blocker

Collaborative Ads (CPAS) — Phase 2

Not standard owned-catalog ads. Phase 2 core track — marketplace shares catalog segment; campaigns use catalog_segment_id; measurement via shared-item metrics. Marketplace onboarding (Trendyol, Hepsiburada, …) API vs manual TBD.

Full spec: Meta CPAS (Collaborative Ads)

Feed / catalog

Product catalog synced from feed service
Match rates monitored; catalog errors block dynamic ads launch

Conversion tracking

Method	Use case
Meta Pixel (browser)	Standard events; declining reliability — pair with CAPI
Conversions API (CAPI)	Primary server-side; dedupe with `event_id`
Offline conversions	CRM events uploaded to offline event set
EMQ	Event Match Quality monitored in dashboard

First-party readiness:

Use client subdomain CAPI endpoint or Kobico-hosted relay
Pass hashed email/phone per Meta guidelines

Data to GA4

URL tags with dynamic macros: utm_campaign={{campaign.id}}, utm_content={{ad.id}}, utm_source={{site_source_name}} — UTM spec
GA4 attributed via UTMs + fbclid; join campaign ID first (not campaign name)
Cross-check: Meta vs GA4 within tolerance bands in reporting

Agent capabilities

Campaign / ad set / ad creation (ASC, prospecting, retargeting templates)
Audience application from plan (custom, lookalike specs — creation may need data minimums)
Budget pacing within guardrails
Creative rotation per approved assets only

ADR 0004: Kobico does not publish organic posts to client Page/IG feeds. No pages_manage_posts OAuth scope.

Pattern	In scope?	Notes
Standard paid ads (image/video/carousel)	✅	Approved creative assets from sibling module
Dark / unpublished post as ad creative	✅	Engagement/traffic objectives without feed visibility
Boost / promote existing organic post	✅	Client (or their team) published the post; Kobico runs paid promotion
Organic feed publishing / social calendar	❌	Out of scope — paid media module only

Human touchpoints

OAuth / Page admin verification (client)
Ad policy disapprovals (health, housing, credit special categories)
Special Ad Categories selection
Agency billing profile change (Kobico ops only — not client)

Compliance notes

Special Ad Categories (exact list): HOUSING, EMPLOYMENT, FINANCIAL_PRODUCTS_SERVICES (replaced CREDIT in Jan 2025), ISSUES_ELECTIONS_POLITICS. Health and schools/education are not Special Ad Categories by default — campaigns declare special_ad_categories: NONE unless the ad concerns those topics.
Every campaign must set special_ad_categories + special_ad_category_country when applicable.
EU note: social-issue/electoral/political ads are banned in the EU (TTPA, since Oct 2025).

Dependencies

GA4 baseline for landing measurement
CRM → CAPI pipeline for offline events
PRE-10 for production 2-Tier