Dossier Kobico Digital Ads · Board pack · v1.9.31 Board pack · v1.9.31

Lifecycle · Draft

Onboarding

Created 9 Jun 2026·Updated 17 Jun 2026

Latest change: Rebrand dossier from Kobi to Kobico

Draft document — deep-dive spec incomplete; content will be updated before and during build. Do not treat as signed-off implementation detail. Pack overview

Objective

Move a signed client from intake to ready for media planning — ad platform accounts and tracking assets provisioned via API where possible, client consents captured, implementation guides delivered.

Client portal UX (what they see, provide, and what remains): Onboarding client portal.

Phase 1 scope (current)

In scope now Deferred (later phase)
Create ad accounts + sub-assets programmatically (API) Publish tags in GTM (we ship guides only)
Meta + TikTok pixels, catalogs, CAPI endpoints Full automated domain verification
Meta + Instagram Connect (client consent) DV360 (unless SKU + contract)
Merchant Center — full API create + client feed URL only Search Console
GA4 → Ads link via API when client grants Admin (optional) Kobico-operated GA4 property create
Plan-based spend limits, implementation guide

GA4 remains long-term source of truth (ga4-source-of-truth.md). ADR 0002 (accepted): v1 uses soft gate — client invites Kobico as GA4 Admin on an existing property or skips; we only link Ads↔GA4 when Admin is granted. OAuth auto-provision is Phase 3+ consideration only.

Inputs

  • Client contract / SKU (vertical, budget tier, channels)
  • Business type (onboarding intake — drives Special Ad Category eligibility; default campaign flag remains NONE per ADR 0004)
  • Brand assets (logo, URLs, social pages)
  • Website URL (for pixel + domain verification instructions)
  • Ecommerce: product feed URL (client pastes in portal — Shopify, CMS, static URL)
  • CRM tenant ID
  • Billing terms — monthly invoicing to client; no client payment method on ad platforms
  • ToS and data-sharing consent
  • Optional: client grants Kobico GA4 Admin on their property (portal invite or Google account link)

Not required Phase 1: GTM container access.

Outputs

  • onboarding_record with platform account ID map
  • Pixels (Meta, TikTok if SKU) + CAPI relay
  • Merchant Center sub-account + data source (ecommerce) — if feed URL provided
  • Ads ↔ GA4 link — if client granted GA4 Admin
  • tracking_implementation_guide (manual + GTM templates)
  • Event: client.onboarding.completed

Process steps (Phase 1)

YesNoIntake + plan_idToS + data consenttenant_registryGoogle Ads APIMerchant Center ifecommerce + feed URLClient granted GA4Admin?API link Ads + GA4Skip GA4 this onboardingMeta APIConnect Meta + IGTikTok if SKUImplementation guideCRM webhookVerification sweeponboarding.completed

Programmatic account creation — yes, via API

Platform Create via API? Client provides (not billing)
Google Ads ✅ —
Merchant Center ✅ Full auto Feed URL (+ country/currency if needed)
Meta ✅ Page/IG consent (OAuth) — required for 2-Tier child BM (ADR 0003)
TikTok ✅ (if SKU) —
GA4 link ✅ If Admin granted Admin access on existing property
CRM ✅ —

Client never: payment details, manual ad account creation in Google/Meta/TikTok UIs.

If the client grants Kobico Administrator on their GA4 property (invite Kobico service account or automation user):

Step API Auto
Accept / confirm access Client invite in GA4 UI or Google Admin Client one-time
Link GA4 property ↔ Ads customer GA4 Admin properties.googleAdsLinks.create and/or Ads ProductLinkService (GOOGLE_ANALYTICS) ✅
Import GA4 conversions to Ads Enabled by link + conversion action config ✅
Read metrics (SoT) Analytics Data API ✅
Client GA4 → BigQuery — Out of scope (client’s GCP)

We do not need to create GA4 or Search Console to link Ads — only Admin on existing property + API calls both sides.

If client declines GA4 Admin: skip link; onboarding still completes; reporting uses platform data + CRM until GA4 connected later.

Merchant Center — fully automated (client feed URL only)

There is no fundamental blocker to API-creating Merchant Center for ecommerce. Client pastes feed URL; connector does the rest.

Step Who API
1. Kobico agency MCA exists Ops once (like MCC) Pre-launch
2. Create sub-account per tenant Agent Accounts.create ✅
3. Client submits feed URL in portal Client —
4. Create data source (scheduled fetch) Agent DataSources.create ✅
5. Link sub-account ↔ Google Ads customer Agent Accounts.link + Ads ProductLinkService ✅
6. Poll feed / policy status Agent Accountstatuses / Productstatuses ✅

What does not block account creation:

  • Client feed URL — that is the input we want
  • Client payment — never asked; MCA uses Kobico agency billing

What can delay shopping launch (not account create):

  • Google product policy review after first fetch (async hours/days)
  • Website claim on Merchant Center (store URL) — may need meta-tag/DNS; include in implementation guide
  • Disapproved products — QC + human fix feed

So: onboarding creates MCA + feed + Ads link in one API flow; launch approval waits on Google policy crawl, same as any agency.

Tracking — pixels yes, GTM publish later

Step Phase 1
Create Meta / TikTok pixels + CAPI ✅ API
Google conversion actions ✅ API
Implementation guide (manual + GTM template) ✅
Publish GTM on client site ⏸ Later
Kobico Relay (CNAME + one script, server-side fan-out) ⏸ Phase 2+ — first-party tag relay

Business verification (Kobico entity — not client)

Platform business verification uses the Kobico legal entity on MCC / Business Portfolio / Business Center — not client incorporation documents. New shell accounts inherit the verified agency master.

Platform How Per-client warning?
Google Ads MCC Verification Hub (bulk across managed accounts); poll status via API where available No — PRE-7
Meta Kobico BM business verification (one-time) No — PRE-8
TikTok Kobico BC business verification (one-time) No — PRE-9

If submit is UI-only, MCC bulk is the acceptable default for Google. Connectors never ask clients for tax IDs or business licenses for platform verification.

Domain verification (client website — separate)

Proves client website ownership to Meta/Google/TikTok (DNS TXT or meta tag) — not GA4, not Search Console, not Kobico entity docs. Phase 1: steps in implementation guide; optional DNS delegate.

TikTok

One-time Kobico developer app approval before TikTok SKU. After that, API provisioning like other platforms — not a per-client issue.

Platform order (Phase 1)

  1. Google Ads
  2. Merchant Center (ecommerce + feed URL from client)
  3. GA4 ↔ Ads link (if client granted Admin)
  4. Meta (+ Connect Page/IG)
  5. TikTok (if SKU)
  6. CRM webhook + implementation guide

Onboarding automation matrix (Phase 1)

Three buckets: what the agent runs via API, what needs client portal approval / OAuth / paste, and what cannot be fully automated (ops pre-launch, human, or platform async).

✅ Fully automated (Onboarding Agent / connector)

No client action during the run — assumes contract signed, plan_id set, PRE agency masters exist.

Area What runs automatically
Internal tenant_registry, plan entitlements (monthly_media_cap, credit_sub_limit), onboarding_record, ToS/consent capture (after client clicks in portal), client.onboarding.completed event
Google Ads create_customer_client, naming, currency, timezone, MCC link, API user access, auto-tagging, conversion actions + goals, Enhanced Conversions config, Merchant link, offline import setup, inherit agency billing, internal spend guardrails
Merchant Center Sub-account create, data source from feed URL, Ads link, feed/policy poll (after client pasted URL)
Meta Ad account create, spend_cap from plan, system user + token, pixel, CAPI endpoint config, catalog + offline event set (ecommerce SKU), inherit agency billing
TikTok Advertiser create (if SKU + app Live), pixel, Events API config, internal guardrails, inherit BC billing
CRM Webhook register, schema mapping, test event stub
Tracking assets Pixels + conversion actions created in platforms; implementation guide generated (PDF/HTML + GTM import template)
GA4 ↔ Ads If client already granted Admin — link APIs both sides, conversion import config
Verification sweep Poll account health, token scopes, registry limits

Client never automates: platform billing, business verification with client entity docs, raw ad account creation in Google/Meta/TikTok UIs.

👤 Client approval, OAuth, or portal input

Client acts in Kobico portal or platform OAuth UI — agent waits, then continues.

Step Client action Agent after
Kobico ToS Accept in portal Continue intake
Data sharing / subprocessors Accept (GDPR/KVKK) Unlock tracking + CAPI
Contract / SKU Signed before onboarding starts plan_id drives limits
Ecommerce feed URL Paste URL (+ country/currency if needed) MC DataSources.create + poll
Connect Meta + Instagram Portal → Meta OAuth → pick Page + IG Page on child BM via client_pages
GA4 Admin (optional) Invite Kobico user/SA in GA4 or accept portal invite Ads ↔ GA4 link via API
Website / brand inputs URL, logo, social links at intake Used in naming, guides, domain-verify steps
DNS / domain verify (optional) Add TXT / meta-tag or delegate DNS to Kobico Unlocks some optimization events — not account create
Install tracking on site Follow implementation guide (snippet / GTM import) Health probe turns green
Consent banner (Relay Phase 2+) Approve copy; Kobico CMP included by default — or select client / bundled partner CMP Relay fan-out gated

Partial automate: Meta partner invite — API sends; client must accept if OAuth Connect fails (HITL A4).

❌ Cannot fully automate (per tenant)

Class Examples Who Blocks onboarding.completed?
🔧 PRE — agency one-time MCC invoicing, Meta credit, TikTok BC funding, MCA, TikTok app Live, DV360 contract, Kobico-entity business verify Kobico finance/ops/legal No — must exist before first client; not ONB per tenant
🚩 ONB — per-tenant failure Page/IG consent timeout, Meta ad account limit, missing plan limits on registry, bad token scope, MC policy without feed/catalog HITL / ops Yes for affected SKU channel
Platform async Google product policy crawl, MC website claim review, account suspension flags Wait + poll May block shopping go-live, not always account create
Human / no API GTM publish on client site (v1 deferred) Client IT from guide No — onboarding can complete; tracking not green until installed
Deferred SKU DV360 without GMP contract, TikTok without Live app Sales / engineering Exclude channel from plan
Phase 2+ Kobico Relay CNAME + loader, full automated domain verify Client DNS / dev No in v1

Minimum client checklist (Phase 1 happy path)

  1. Sign contract + accept ToS + data sharing in portal
  2. Meta: Connect Page + IG (OAuth) — required for social SKU
  3. Ecommerce: paste feed URL
  4. Optional: grant GA4 Admin
  5. After onboarding: install tracking from guide (not a blocker for onboarding.completed if policy allows incomplete tracking)

Everything else — ad accounts, pixels, CAPI, billing inherit, plan caps, catalogs — agent.

Agent vs human (Phase 1)

Step Agent (API) Human
Ad accounts + MC + feed URL ✅ Client pastes feed URL only
GA4 ↔ Ads link ✅ if Admin Client grants GA4 Admin (optional)
Pixels, catalogs, CAPI ✅ Client installs from guide
Meta + IG Connect ✅ after Client OAuth
Platform billing (inherit) ✅ auto on create 🔧 PRE one-time only — no per-client warning
Business verification (Kobico entity) ✅ inherit / ⚠️ status poll 🔧 PRE-7…PRE-9 — never client entity
Plan budgets (post-approval) ✅ API from plan_version —
GTM publish — Deferred