Onboarding — Implementation Pack (Auto-Generated per Vertical)

Audience: Engineering (orchestrator), client portal, implementation CS. Defines what Kobico auto-provisions, what the client receives (snippets + checklist), and publish gates for end-to-end onboarding — browser pixel v1; CAPI + offline import v2.

Related: Provisioning spec · Client portal §7 · Meta Ads §2-Tier · ADR 0003 · Dev spike meta-dev/

1. Scope — v1 publish vs v2 deferred

Layer	v1 (publish now)	v2 (later)
Meta infrastructure	2-Tier child BM → child system user → ad account → pixel → `client_pages` → spend_cap → child-owned catalog+feed (ecommerce, after Catalog App Review)	Parent LOC share (PRE-2)
Client site tracking	Base pixel + vertical standard events (browser) + UTM doc + domain-verify instructions	CAPI relay, dedup `event_id`, offline CRM import
Implementation deliverable	Auto-generated `implementation_pack` JSON + PDF/HTML in portal	CAPI endpoint block appended to same pack
Onboarding complete	Accounts + pack delivered; tracking may be yellow (lenient policy)	—
First ad launch (A2)	Tracking green (browser events firing) or ops waiver	CAPI green when SKU requires server-side

Rule: Onboarding publishes accounts and the implementation pack. Launch gates on tracking health — not on CAPI in v1.

2. Orchestrator flow (Meta 2-Tier — publish path)

Triggered after Connect Meta & Instagram (user token) + intake (vertical, plan_id, feed_url if ecommerce).

Step	API / action	Token	Registry field
1	`POST /{parent_bm}/owned_businesses`	User	`child_bm_id`, `shared_page_id`
2	`POST /{child_bm}/access_token`	Parent system user	`child_system_user_id` (+ Secret Manager)
3	`POST /{child_bm}/adaccount`	Child system user	`meta_ad_account_id`
4	`POST /act_{id}` `spend_cap`	Child	`meta_spend_cap_try`
5	`POST /act_{id}/adspixels`	Child	`meta_pixel_id`
6	Verify Page on child BM — `GET /{child_bm}/client_pages` (from `shared_page_id` at step 1)	Child	`meta_page_id`
7	`POST /act_{id}/assigned_users`	Child	(system user assignment)
8	Catalog on child BM — `POST /{child_bm}/owned_product_catalogs` → product set → feed → link `act/catalogs`	Child (`catalog_management`)	`meta_catalog_id`, `meta_product_set_id`, `meta_catalog_feed_id`, `meta_catalog_feed_url`
9	`buildImplementationPack(vertical)`	Internal	`implementation_pack_id`, GCS URI
9b	`GET /{pixel-id}?fields=code,last_fired_time,…`	Child	Populate pack from Graph — see dev runbook §2
10	Optional: assign human ADMIN on child BM	Parent	ops/debug only

Page linkage: Page is linked when owned_businesses is called with shared_page_id. Confirm via client_pages with PROFILE_PLUS_ADVERTISE. Campaigns use promoted_object.page_id.

Dev verified: steps 1–7 — see Meta Ads dev verification. Step 8 after Catalog App Review on Kobico verified BM.

3. Auto-generated `implementation_pack`

Generated once when Meta (and Google, if in same sweep) provisioning succeeds. Stored on onboarding_record + object storage; surfaced in portal Screen 7.

3.1 Top-level schema

{
  "schema_version": "1.0",
  "tenant_id": "uuid",
  "vertical": "tourism",
  "plan_id": "ecommerce_v1",
  "generated_at": "2026-06-14T12:00:00Z",
  "website_url": "https://client.example",
  "platform_ids": {
    "meta_pixel_id": "1654665905839965",
    "meta_ad_account_id": "act_2218945348950888",
    "meta_page_id": "560875737305037",
    "meta_catalog_id": "1745503416620716",
    "meta_product_set_id": "1287164999831326"
  },
  "meta": { },
  "google": { },
  "tiktok": { },
  "utm": { },
  "domain_verification": { },
  "capi": { "phase": "v2_deferred" },
  "offline_import": { "phase": "v2_deferred" },
  "client_checklist": [ ]
}

3.2 `meta` block (always)

Field	Content
`base_pixel_snippet`	Standard Meta base code with `{pixel_id}`
`events[]`	Vertical template — see §4
`utm_note`	Link to UTM spec + dynamic macros for Meta
`test_instructions`	Events Manager → Test events; portal health probe targets
`capi_placeholder`	“Server-side tracking will be enabled in a future update” (v1)

Base pixel (template):

<!-- Kobico Meta Pixel — {tenant_slug} -->
<script>
!function(f,b,e,v,n,t,s){if(f.fbq)return;n=f.fbq=function(){n.callMethod?
n.callMethod.apply(n,arguments):n.queue.push(arguments)};if(!f._fbq)f._fbq=n;
n.push=n;n.loaded=!0;n.version='2.0';n.queue=[];t=b.createElement(e);t.async=!0;
t.src=v;s=b.getElementsByTagName(e)[0];s.parentNode.insertBefore(t,s)}(window,
document,'script','https://connect.facebook.net/en_US/fbevents.js');
fbq('init', '{meta_pixel_id}');
fbq('track', 'PageView');
</script>

Orchestrator substitutes {meta_pixel_id} from registry. Production: prefer GET /{pixel-id}?fields=code from Graph API — see dev runbook §2.

4. Vertical event templates (browser — v1)

Applied from provisioning_template.{vertical}. Each event entry:

{
  "id": "meta_lead",
  "meta_event_name": "Lead",
  "type": "standard",
  "description": "Form submit or qualified inquiry",
  "trigger_hint": "Thank-you page or CRM form success",
  "browser_snippet": "fbq('track', 'Lead');",
  "gtm_event_name": "kobi_meta_lead",
  "optimize_for_ads": true
}

4.1 Health

Meta event	Trigger hint	GTM event
`Lead`	Form success / appointment request	`kobi_meta_lead`
`Schedule`	Booking confirmed	`kobi_meta_schedule`
`Contact`	Click-to-call / chat handoff	`kobi_meta_contact`
`PageView`	(base pixel)	—

4.2 School

Meta event	Trigger hint	Notes
`Lead`	Inquiry form	Default optimize
`CompleteRegistration`	Application submitted	Special Ad Category NONE unless housing/employment ad

4.3 Tourism

Meta event	Trigger hint	Notes
`Lead`	Inquiry / WhatsApp click	Primary for prospecting
`InitiateCheckout`	Start booking flow
`Purchase`	Confirmed booking (if online payment)	Match GA4 `purchase` where possible
`ViewContent`	Property / villa detail view	Soft signal

Optional catalog (tourism + feed URL): same ecommerce catalog block; DPA for properties.

4.4 Ecommerce

Meta event	Trigger hint	Notes
`ViewContent`	Product detail
`AddToCart`	Add to cart
`InitiateCheckout`	Checkout start
`Purchase`	Order confirmation	value + currency params required

Catalog: feed URL from intake → automated (no client snippet for catalog). Client only maintains feed URL accuracy.

Example Purchase snippet (orchestrator fills currency):

fbq('track', 'Purchase', {
  value: {order_value},
  currency: '{account_currency}',
  content_ids: ['{product_id}'],
  content_type: 'product'
});

5. Domain verification block

Included in every pack when website_url present:

{
  "domain_verification": {
    "meta": {
      "required_for": ["Purchase", "Lead optimization at scale"],
      "methods": ["dns_txt", "meta_tag"],
      "instructions_url": "https://business.facebook.com/settings/owned-domains",
      "domain": "client.example"
    },
    "note": "Client IT — not blocking onboarding.complete in v1; blocking strict A2 if optimization events required"
  }
}

6. UTM block (Meta)

{
  "utm": {
    "meta_default": "utm_source=facebook&utm_medium=paid&utm_campaign={{campaign.name}}&utm_content={{ad.name}}",
    "capture_click_ids": ["fbclid"],
    "crm_fields": ["fbclid", "utm_campaign", "utm_content"]
  }
}

Full spec: UTM & attribution.

7. CAPI & offline — v2 appendix (document now, implement later)

Pack includes placeholder section so clients see the roadmap; orchestrator does not provision in v1.

{
  "capi": {
    "phase": "v2_deferred",
    "summary": "Server-side Conversions API will relay the same vertical events with deduplication.",
    "planned_events": ["Lead", "Purchase"],
    "relay_url": null,
    "test_event_code": null
  },
  "offline_import": {
    "phase": "v2_deferred",
    "summary": "CRM qualified leads and bookings will upload via offline event set.",
    "crm_events": ["qualified_lead", "booking"]
  }
}

When v2 ships: append capi.relay_url, capi.access_note (no secret in pack), enable Conversion Tracking Service routes.

8. Client checklist (portal Screen 7)

Auto-generated client_checklist[]:

#	Item	Owner	Blocks A2 launch
1	Install base Meta pixel on all pages	Client IT	Yes
2	Add vertical events per guide	Client IT	Yes (optimize events)
3	Confirm test event in portal (PageView)	Client IT	Yes
4	Add UTM parameters to Meta ad links (Kobico sets at ad create)	Kobico	—
5	Domain verification (DNS or meta-tag)	Client IT	If optimizing Lead/Purchase
6	Keep product feed URL valid (ecommerce)	Client	Shopping/DPA
7	CAPI — coming soon	Kobico	v2

Portal polls health probe: GET pixel stats / Events Manager test → tracking_checklist.meta_pixel_browser.

9. Publish gates

9.1 `client.onboarding.completed`

Gate	v1
Consents + business profile	Required
Meta OAuth + Page (if SKU)	Required
Feed URL (ecommerce)	Required
Meta worker steps 1–9	Required
`implementation_pack` generated	Required
Browser tracking installed	Not required (yellow OK)
CAPI / offline	Not required (v2)

9.2 First campaign launch (A2)

Gate	v1
`client_pages` contains OAuth Page + ADVERTISE	Required
`meta_pixel_id` + PageView test event	Required
Vertical primary event firing (e.g. Lead or Purchase)	Required for conversion campaigns
Catalog product_count > 0 (DPA)	Required for catalog campaigns
CAPI	Optional v1; required v2 for CRM-heavy SKUs

10. Worker contract (TypeScript sketch)

Full reference implementation (tourism): specs/provisioning/examples/tourism-onboarding.worker.ts · Zod: specs/provisioning/schemas/implementationPack.ts · Errors: dev runbook.

type Vertical = 'health' | 'school' | 'tourism' | 'ecommerce';

interface MetaOnboardingInput {
  tenantId: string;
  vertical: Vertical;
  planId: string;
  userAccessToken: string;
  sharedPageId: string;
  feedUrl?: string;
  spendCapTry: number;
}

interface MetaOnboardingResult {
  registry: TenantMetaIds;
  implementationPack: ImplementationPack;
}

async function runMetaOnboarding(input: MetaOnboardingInput): Promise<MetaOnboardingResult> {
  // 1–8: Graph API sequence (idempotent per step)
  // 9: buildImplementationPack(input.vertical, registry)
  // 10: persist + emit onboarding.meta.ready
}

Templates live in specs/provisioning/templates/ (copy to packages/provisioning/templates/ in product repo). Full tourism example: tourism-onboarding.worker.ts.

11. Remaining engineering (post-spec)

Item	Owner	Notes
`meta_onboarding_worker` in product monorepo	Eng	Port `meta-dev/` scripts
`buildImplementationPack()`	Eng	This doc §3–6
Portal Screen 6–7 render pack	Product	Download + checklist
Health probe job	Eng	Poll pixel `last_fired_time`
Phase 5 script: verify `client_pages` + spend_cap	Eng	`run-2tier-phase5-verify.ps1`
CAPI relay	Eng v2	Kalkan `metaCapi.ts` pattern
Offline event set	Eng v2	CRM SKU

Meta dev runbook — errors, Graph payloads, pixel GET, ads readiness
Onboarding client portal
Onboarding API cross-check §4 Meta
Data & tracking

1. Scope — v1 publish vs v2 deferred

2. Orchestrator flow (Meta 2-Tier — publish path)

3. Auto-generated implementation_pack

3.1 Top-level schema

3.2 meta block (always)

4. Vertical event templates (browser — v1)

4.1 Health

4.2 School

4.3 Tourism

4.4 Ecommerce

5. Domain verification block

6. UTM block (Meta)

7. CAPI & offline — v2 appendix (document now, implement later)

8. Client checklist (portal Screen 7)

9. Publish gates

9.1 client.onboarding.completed

9.2 First campaign launch (A2)

10. Worker contract (TypeScript sketch)

11. Remaining engineering (post-spec)

12. Related documents

3. Auto-generated `implementation_pack`

3.2 `meta` block (always)

9.1 `client.onboarding.completed`