App · first run · proposal

Onboarding, rebuilt

A clickable proposal for how a first-time player gets into the Kaki app. Three taps to real content, no account needed. Every question is asked at the moment its answer pays off. Try each branch with the buttons under the phone.

Today’s flow (read from the code)

  1. /intro is a 3-slide pager in English with emoji glyphs (Discover, Open tables, Community). It collects nothing and only sets kaki.introSeen. It explains in words instead of showing anything, and promises “venues around you” while city detection is off.
  2. Home as a guest is scoped to “All locations”. The city is never asked; it is a chip that opens the city sheet.
  3. /sign-in offers an email code, Apple (iOS) and Google on one English screen. It doesn’t say whether you are signing up or signing in, and it doesn’t mention the Terms. On success it goes to /, so the action that sent you here is lost.
  4. Push prompt PushSync asks for OS notification permission the moment a session exists, before the player has any reason to say yes. iOS asks only once.
  5. /onboarding “completing” The server mints a player row (name and handle from the email or OAuth name) with profileBasicsDue. The root gate then forces gender + player level (5 levels, no default) + the Terms tick. It is required, the only exit is Sign out, and it re-fires on every navigation. The minted name and username are never shown for you to confirm.
  6. Legacy “create” mode (when GET /me is null) is one long form: name, username, styles, gender, level, Terms.
  7. /signup (W6) has 7–9 one-per-screen questions (WhatsApp + OTP, email, experience, experience per style). It is registered in the app, but nothing navigates to it; only the web uses it.

What goes wrong

  • Asks before it shows. The flow goes text slides, then a sign-in wall, then a cold push prompt, then a forced form. Gender is asked before the player has seen a single table.
  • A hard client gate on a server flag loops. On 2026-08-06 the gate re-pushed onboarding over Home (“have to close first”). Later the Terms rule left profileBasicsDue true after a 200, so every new account looped back to onboarding with Sign out as the only exit.
  • Data the app needs is never collected. Minted accounts never pick mahjongTypes, although Cari Kaki and events match on them. Names like “dewi.lestari” come from the email and are never confirmed.
  • Three profile flows (onboarding create, onboarding completing, the unreachable W6) and three languages of copy (English chrome, Indonesian basics, the owner’s slang in W6).

New flow

  1. Welcome is one screen, not a pager. It shows tiles, not text. “Lihat-lihat dulu” (primary) or “Masuk atau daftar”. ID/EN switch (the app already has @kaki/i18n, default id).
  2. City is one tap, and you can skip it. It writes the existing city store, so Home is relevant from the first frame.
  3. “Sudah pernah main?” is one tap, and you can skip it. It is kept on the device only. It tailors Home’s first card and pre-selects the level later.
  4. Home works as a guest: browse, book and pay, and keep score, with no account (5.1.1(v)).
  5. Sign in only when asked or needed. The screen says what you will return to. Apple (iOS only), Google, or an email code.
  6. New account: “Ini kamu?” confirms the minted name and username. The Terms tick moves here.
  7. “Dua hal singkat” asks gender + level, with the level pre-selected. Variant: ask them at the first Cari Kaki join instead (switch below the phone).
  8. Resume. You land back in the action that asked: the join request is sent, the booking is saved to the account, or the game is saved.

Old step → new step

OldNew
/intro (3 slides)Welcome (1 screen) + optional City + optional Experience
City chip onlyCity asked at first run (skippable); chip stays on Home
/sign-in → “/”Sign-in with a context line → back to the action
Push at sign-inA soft ask after the first join request or booking, then the OS prompt
Forced “completing” form“Ini kamu?” (name, username, Terms) + “Dua hal singkat”, inside the sign-up and never as a later gate
Legacy create formSame two screens (name/username are prefilled when minted, typed otherwise)
W6 styles / experienceExperience at first run (device); styles after the first recorded game
Guest checkoutUnchanged (name + email), plus “Simpan ke akun” on the ticket

What each field is for, and when it is asked

FieldUsed forAsked
CityScopes Home venues, events, Cari Kaki (device city store)First run, skippable
ExperienceHome’s first card; pre-selects levelFirst run, skippable, device only
NameShown on tables, rosters, boards“Ini kamu?” (prefilled)
UsernameFriend search, links; change later in Settings“Ini kamu?” (prefilled)
Terms tickApple 1.2 UGC EULA, recorded server-side (0118)“Ini kamu?”
GenderPrivate; the open-table gender criterion and filterSign-up, or the first Cari Kaki join (variant)
LevelCari Kaki skill filter and badge; table criteriaSame as gender, pre-selected
StylesMatching tables and events; legacy mahjongTypeAfter the first recorded game or table post
NotificationsJoin accepted, booking-end reminders (local), inboxAfter the first join request or booking
Guest name + emailTicket and receipt for a guest bookingCheckout (unchanged)
PhotoAvatar (monogram until then)Never asked; Profile edit
WhatsAppW6 only; nothing in the app reads itNot asked (see questions)

What changes under the hood (for later)

  • Sign-in keeps a returnTo and resumes it, instead of replace("/").
  • PushSync registers a token only if permission was already granted, and never prompts.
  • The basics step is part of sign-up, not a gate that re-fires on every navigation. If profileBasicsDue is still set later, show a card, not a redirect. That ends the whole class of onboarding loops.
  • No new API endpoints. City and experience are device state; the rest are today’s PATCH /me fields.

Questions for the owner

  1. Gender + level: on 09-15 you asked for them at account creation. Keep that (the default here), or move them to the first Cari Kaki join, where they are used?
  2. Terms: keep the explicit tick on “Ini kamu?”, or a “Dengan lanjut, kamu setuju…” line on sign-in? The tick is the safer choice for Apple 1.2.
  3. W6 (WhatsApp + per-style experience): retire it from the app, or is that data still wanted? If so, where should it be asked?
  4. Level ladder: the server has 5 levels (Pemain baru … Pemain jago). The first-run question has 3 answers that map to new / casual / regular. OK?
  5. City at first run while detection is off. OK to ask, or keep “Semua lokasi” until the player picks?
19:04●●●
Start
Account on sign-in (simulated)
Gender + level asked
Theme