Lifecycle · Draft
Onboarding — Client Portal Experience (Phase 1)
Audience: Product, UX, client success, implementation. Defines what the client sees, what they provide, what Kobico finishes, and what remains after onboarding — without exposing agency internals (MCC, system users, PRE setup).
Related: Onboarding process · Provisioning spec · Implementation pack · API cross-check
Design principles
| Principle | Detail |
|---|---|
| Agency-owned accounts | Client never creates or logs into Google Ads / Meta Ads Manager / TikTok Ads as account owner |
| No platform billing | Never ask for card or bank details for ad platforms — client is invoiced by Kobico monthly |
| Minimal client IT | Target: legal consents + Meta OAuth + paste feed URL (ecommerce) + optional GA4 + install guide later |
| Hide ops complexity | No MCC/BM/BC IDs, system users, developer tokens, or ONB-* codes in UI — translate to plain status |
| Honest completion | End screen separates “Kobico finished” vs “Your next steps” vs “Waiting on Google/Meta” |
| SKU-aware | Steps appear only if channel is in contract (ecommerce, social, TikTok, CRM) |
| Any-email login | Client portal auth via Google Identity Platform (email + password or magic link) — Gmail not required; RBAC and tenant_id in the BFF — see security doc |
Portal journey (screens)
Estimated client active time: 15–25 minutes (excluding site install, which is post-onboarding).
Screen-by-screen
0 — Welcome
| Client sees | Plan name, included channels (Google, Meta, TikTok…), monthly media cap in client currency, vertical, assigned Kobico contact, estimated timeline |
| Client provides | Nothing — contract already signed; account activated by sales/ops |
| Kobico behind the scenes | tenant_id, plan_id, onboarding_record created; entitlements loaded |
| CTA | Start onboarding |
Do not show: raw customer_id, act_*, internal SKU codes.
1 — Legal & privacy (required)
| Client sees | Kobico ToS, data-processing summary, sub-processor list (Google, Meta, TikTok…), link to privacy policy |
| Client provides | Checkbox accept ToS + data sharing (GDPR/KVKK scope for tracking + CAPI) |
| Unlocks | Provisioning agent; tracking asset creation |
| Blocks if skipped | Cannot proceed |
Stored as consent_record → linked to onboarding_record.
2 — Business profile (required)
| Client sees | Form prefilled from contract where possible |
| Client provides |
| Field | Required | Used for |
|---|---|---|
| Legal business name | Yes | Naming, invoices, guides |
| Website URL | Yes | Pixels, domain-verify instructions, MC claim |
| Primary country / currency | Yes | Account timezone, feed, ads |
| Logo (optional) | No | Reports / future creative |
| CRM tenant ID | If CRM SKU | Webhook mapping |
| Contact email for IT | Recommended | Tracking install reminders |
| Kobico after submit | Validates URL; stores intake; may start Google Ads create in background | | CTA | Continue |
3 — Product feed (ecommerce SKU only)
| Client sees | “Connect your product catalog” — one field + help links (Shopify, WooCommerce, static URL) |
| Client provides | Feed URL; optional sale country if multi-country |
| Client does not | Create Merchant Center, link Ads, or platform billing |
| Kobico after submit | MCA sub-account, data source, Ads link, first fetch poll |
| Status shown | ⏳ Setting up catalog → ✅ Catalog connected or ⚠️ Feed needs attention (human-readable error) |
Can skip screen? No if ecommerce in SKU — blocks shopping channel until URL provided.
4 — Connect Meta & Instagram (social / Meta SKU)
| Client sees | Short explanation: “Link the Facebook Page and Instagram you advertise with. You stay owner; Kobico runs ads under agency access.” |
| Client provides | Meta OAuth — login, grant permissions, pick Page + IG |
| Client does not | Create ad account, add payment, become BM admin |
| Kobico after OAuth | Ad account (if not already), pixel link, Page/IG promoted to ad account |
| If fails / timeout | Portal shows “Need help connecting?” → support / partner-invite instructions (HITL A4 — internal) |
Can skip? Only if Meta not in SKU. If in SKU and skipped → onboarding cannot complete for social placements.
5 — Google Analytics (optional)
| Client sees | “Connect GA4 for unified reporting (recommended)” — benefits bullet list |
| Client provides | Either: Invite Kobico in GA4 Admin (instructions + Kobico service account email) or Skip for now |
| Kobico if granted | Ads ↔ GA4 link via API |
| If skipped | Onboarding still can complete; reporting uses platform + CRM until connected later |
Re-openable from portal settings after onboarding.
6 — We are setting up your channels (read-only progress)
| Client sees | Progress checklist — plain language, no API jargon |
| Row (client label) | Shown when |
|---|---|
| Google Search & Shopping accounts | Google in SKU |
| Meta & Instagram advertising | Meta in SKU |
| TikTok advertising | TikTok in SKU |
| Product catalog | Ecommerce |
| Conversion tracking (browser pixel + guide) | Always |
| CRM lead connection | CRM SKU |
| Analytics link | GA4 Admin granted |
| Status icons (client-facing) | Meaning |
|---|---|
| ✅ Ready | Kobico finished this row |
| ⏳ In progress | Agent running |
| 👤 Waiting for you | Client action on earlier screen |
| 🌐 Waiting on Google/Meta | Platform async (policy, crawl) — not client fault |
| ⏸ Skipped | Optional path not taken |
| 🔧 Support | Kobico ops resolving — client sees “We’re on it” |
Client provides | Nothing — watch progress; email when done or if action needed.
Do not show: ONB-11, token errors, MCC, spend_cap integers — map to Support or Waiting rows.
7 — Tracking on your website
| Client sees | Implementation pack (download + in-portal checklist) — auto-generated for their business type: pixel ID, vertical event snippets (browser), GTM import JSON, UTM doc, domain-verify steps. CAPI / offline CRM blocks show “Coming soon” (v2). |
| Client provides | Install on site (developer or IT) — check off steps in portal when done |
| Kobico provides | Pre-built platform assets + implementation_pack from orchestrator spec; health probe when client marks installed |
| Health indicators | Meta pixel test event (browser), Google conversion action, TikTok (if SKU) — green / yellow / red. CAPI not gated in v1. |
Blocks onboarding.completed? Configurable:
| Policy | Behavior |
|---|---|
| Lenient (default Phase 1) | Onboarding can complete with tracking yellow — media planning can start; launch gated at A2 |
| Strict | Complete only when tracking green or client acknowledges “install within X days” |
Recommend lenient + hard launch gate (A2) until tracking green.
8 — Complete — summary dashboard
The most important screen for expectations.
Section A — What Kobico finished
| Deliverable (client language) | Technical equivalent (internal) |
|---|---|
| Your Google advertising account is ready | Ads customer + conversions + guardrails |
| Your Meta advertising account is ready | act_* + pixel + Page linked |
| Your TikTok account is ready (if SKU) | Advertiser + pixel |
| Your product catalog is connected (if ecommerce) | MCA + data source + Ads link |
| Facebook Page & Instagram linked (if done) | Page/IG IDs on record |
| Google Analytics linked (if done) | GA4 ↔ Ads link |
| CRM can receive campaign leads (if SKU) | Webhook registered |
| Monthly spend limit applied per your plan | monthly_media_cap, Meta spend_cap |
| Implementation pack delivered (snippets for your business type) | implementation_pack artifact |
Section B — Your next steps (left after onboarding)
| Item | Owner | Urgency | Blocks |
|---|---|---|---|
| Install tracking on website (implementation pack) | Client IT | High before launch | Campaign go-live (A2) |
| Domain verification (DNS/meta-tag) | Client IT | Medium | Some optimization events |
| Grant GA4 Admin (if skipped) | Client | Low | Unified GA4 reporting |
| Fix product feed errors (if any) | Client + Kobico | High for Shopping | Shopping ads launch |
| Review UTM / CRM fields in pack | Client marketing | Medium | Attribution quality |
| Server-side tracking (CAPI) — when available | Client IT | Low v1 | Enhanced match (v2) |
Section C — Waiting on platforms (not client homework)
| Item | Typical duration | Client message |
|---|---|---|
| Google product policy review | Hours–days | “Google is reviewing your catalog” |
| Merchant Center website claim | 1–3 days | “Confirm store URL in guide if prompted” |
| Meta ad account limits (rare) | Variable | “We’re working with Meta support” |
Section D — What happens next
| Step | Who |
|---|---|
| Media planning | Kobico planner + client review |
| Plan approval | Client (A1 when exposed) |
| First campaign launch | Kobico after A2 launch confirmation |
CTA: Go to dashboard · Download guide again · Connect GA4 (if skipped)
Event emitted: client.onboarding.completed when internal gates satisfied (see completion rules).
What the client never sees or does
| Hidden / not asked | Why |
|---|---|
| Google/Meta/TikTok payment | Agency billing inherit |
| Business verification docs | Kobico entity — PRE |
| MCC, BM, BC, system users, developer apps | Agency infra |
| Create ad account in platform UI | API under Kobico |
| GTM publish by Kobico on their site | v1 deferred — guide only |
| DV360 | Unless contracted later |
| Internal red-flag codes | Ops translation only |
SKU matrix — which screens appear
| Screen | Base | +Ecommerce | +Meta/Social | +TikTok | +CRM |
|---|---|---|---|---|---|
| Legal | ✅ | ✅ | ✅ | ✅ | ✅ |
| Business profile | ✅ | ✅ | ✅ | ✅ | ✅ |
| Product feed | — | ✅ | ✅ | ✅ | ✅ |
| Connect Meta + IG | — | — | ✅ | optional¹ | — |
| GA4 optional | ✅ | ✅ | ✅ | ✅ | ✅ |
| Progress rows | per SKU | +catalog | +Meta | +TikTok | +CRM |
¹ TikTok ads may use Meta Page for creative on some setups — Meta Connect still required if Meta in SKU.
Completion rules
client.onboarding.completed when all of:
| Gate | Required |
|---|---|
| ToS + data sharing accepted | Yes |
| Business profile complete | Yes |
| Feed URL | Yes if ecommerce SKU |
| Meta Page/IG connected | Yes if Meta in SKU |
| Agent provisioning sweep | No open ONB-* for included channels |
| Plan limits on registry | Yes (internal) |
Not required for complete (v1 lenient):
- Tracking installed on site (yellow OK)
- GA4 connected
- Domain verified
- Google policy approval (async)
Required before first ad launch (A2):
- Tracking health green (or ops waiver)
- Shopping: feed policy acceptable if Shopping in plan
Client vs Kobico vs left — one-page summary
| Client provides in portal | Kobico finishes by end | Left after onboarding | |
|---|---|---|---|
| Always | ToS, data consent, business profile | Google Ads shell, conversions, guide, plan caps, CRM hook (if SKU) | Install tracking; optional domain verify |
| Ecommerce | Feed URL | MCA + data source + Ads link | Feed/policy fixes; website claim |
| Meta | OAuth Page + IG | Ad account, pixel, catalog (if ecom), implementation pack | — if OAuth succeeded |
| TikTok | — (if SKU) | Advertiser, pixel, Events API | — |
| GA4 | Optional Admin invite | Ads ↔ GA4 link if granted | Connect GA4 if skipped |
| Never client | Platform billing, tax IDs for ads, ad account UIs | Agency billing inherit, business verify (Kobico entity) | — |
Notifications (email / in-app)
| Trigger | Message |
|---|---|
| Onboarding started | Welcome + link to portal |
| Action needed | “Connect Meta” / “Add feed URL” |
| Provisioning done, tracking pending | “Your accounts are ready — install tracking from your implementation pack (15 min)” |
| Onboarding complete | Summary + next steps + planner intro |
| Platform async delay | “Catalog under Google review — you can still plan campaigns” |
Phase 2+ additions (portal)
When Kobico Relay ships, add screen “First-party tracking (optional)”:
| UI block | Client action | Default |
|---|---|---|
| Delivery mode | First-party CNAME vs third-party loader (reduced mode) | First-party |
| DNS / CNAME | Instructions + verify button | Required for first-party |
| Loader snippet | Copy k.js tag after CNAME green |
Auto-generated |
| Consent provider | Kobico CMP (included) | Client CMP | Bundled partner CMP | GTM hybrid | Kobico CMP |
| Banner approval | Privacy policy URL + TR/EN copy approve | Required for Kobico CMP |
| BYO CMP | Vendor picker (Cookiebot, OneTrust, iubenda, …) + integration checklist | Only if not default |
Onboarding must not require purchasing a CMP elsewhere before Relay works. Global CMP partnerships and bundled resell are leadership-track — see relay doc § Global CMP partnerships. Does not replace v1 implementation guide until client opts in.
Related documents
- Onboarding implementation pack — auto-generated snippets per vertical; v1/v2 gates
- Onboarding — automation matrix, technical flow
- Onboarding provisioning spec — packages, consents §7
- Human-in-the-loop — A4 access, A2 launch gate
- First-party tag relay — Phase 2+ client steps