After a server-driven layout change in a mobile app, one customer segment sees a broken promotions section while everyone else is fine; how do you design to find and reproduce it?
answer
- which layout did this user get
- an id and revision on every layout
- echo the inputs that composed it
- log fallbacks with build and schema
- validate each segment per schema version
basics
~20 sMake every layout traceable: an id and revision plus the inputs that composed it, such as segment, schema version and locale. Log client fallbacks against that id, keep composed layouts retrievable, and validate each change per segment and schema version before publishing.
solid answer
~50 sThe design must answer one question: which layout did this user actually receive? Every response carries a **layout id and revision** and echoes its **composition inputs**, such as segment, schema version, locale and test arm, and the client attaches them, with its build version, to every fallback, validation failure and slow render it logs. Composed layouts are stored immutably by id, so the team can fetch exactly what that user got, and an internal build can load a layout by id to reproduce the screen without the user's account. Before publishing, each segment's composed layout is validated against every supported schema version, and because layouts are data, the previous revision can be restored in minutes. Typical culprits: a component an old schema lacks, empty segment data, long localised text, a deep tree, or a shared cache mixing segments.
go deeper
Remember that a server-driven screen depends on both the build and the layout the user received, so each layout needs an id the app can report.
Explain which fields a layout response and a client log must carry so a team can fetch exactly what one user saw.
Diagnose by cause, from composition gaps and empty data to locale text, deep trees and shared caches, and build pre-publish validation per segment and schema version.
Decide how much tooling, preview and staged publishing the layout platform needs before merchandisers can change screens without engineers watching each publish.
## Why segment-only breakage is the signature server-driven bug In a hard-coded screen, everyone on the same build sees the same code. In a server-driven screen, what a user sees is the product of **their build** and **the layout composed for them**, and that layout depends on inputs: customer segment, region, locale, schema version, an experiment arm. A merchandiser's change that renders perfectly for the team's own accounts can break for loyalty members in one region on a build that is a year old. The team cannot see it on their phones, crash reports may show nothing because the client fell back politely, and the only report is "the deals section is empty for me". The design work is to make that combination visible and reproducible. ## Make every layout traceable - **Layout id and revision.** Each composed layout gets an identifier and a revision number that changes on every publish. - **Echoed composition inputs.** The response states what it was composed from: segment, schema version, locale, test arm. The client does not need to understand them, only to report them. - **Immutable storage.** The service keeps each composed layout addressable by id for a retention period, so "what did this user get?" is a lookup, not a guess. - **Client outcome logs.** Every fallback, validation failure, skipped node and render that exceeded a time budget is logged with the layout id, the node path and type, the build version and the schema version. - **Privacy by design.** Logs carry ids and inputs, never the user's personal data, so they can be shared freely inside the team. How those logs are batched and uploaded is the telemetry design's job; the layout design decides what each record must contain. ## Common causes and the signal that finds each | Cause | What the segment sees | Signal that exposes it | |---|---|---| | Composition sends a type an old schema lacks, for this segment only | Section missing or whole-screen fallback | Fallback logs grouped by schema version and segment | | Data source empty for this segment | Section renders with no items | Render logs show an empty source for that layout id | | Long localised text in one locale | Text clipped or overlapping | Reproduction with that locale's composed layout | | Deep tree on low-end phones | Slow or janky section | Render-time logs by device class and layout id | | Shared cache ignoring personalisation | Another segment's layout appears | Echoed segment differs from the user's real segment | ## Reproducing one user's screen 1. From the user's report or logs, take the layout id and revision. 2. Fetch that exact composed layout from storage, not the current one, which may already have changed. 3. Load it into an internal build of the same version through a debug entry point that accepts a layout id. 4. Supply that segment's test data rather than the user's account, so no personal data is needed. 5. Compare against the layout composed for the team's own segment to isolate the difference. ## Stopping it before it ships - **Validate every segment against every supported schema version** before publishing, using each version's component list and required props. - **Preview a grid**, segment by schema version by locale, so a merchandiser sees the layouts real users will get, not just their own. - **Publish in steps** where the layout service supports it, watching fallback rates on the first audience before widening. - **Keep revert instant.** Because layouts are data, restoring the previous revision is a server operation measured in minutes, unlike a binary already installed on phones. ## The performance side A segment can also be "broken" by cost rather than correctness. Deep, generic trees take longer to parse and lay out, and low-end phones feel it first. Keep trees shallow, parse layouts off the main thread, cap nesting depth in pre-publish validation, and log render time per layout id with the device class, so a slow layout is attributable to the change that made it slow. A layout that passes every correctness check can still fail the segment that runs the oldest, slowest phones, which is why render time belongs in the same dashboard as fallback rates.
- The broken section appears only for users behind a shared cache in front of the layout service; what is the likely cause?A personalised layout stored by the shared cache and replayed to users in other segments. Responses composed per user or per segment should carry `Cache-Control: private`, so a shared cache does not store them, while the device's own cache still may. The echoed segment in the logged layout is the tell: it differs from the segment that user actually belongs to.
- Why is the app version plus a screenshot not enough to reproduce a server-driven screen?A screenshot shows the symptom, not the layout tree, the composition inputs or the fallback that fired, and the app version says nothing about which layout revision or segment the user received. Without the layout id the team reproduces their own layout, finds it fine, and either closes the report or changes something unrelated.
- If the layout renders on the team's own phones, it renders for every segment.
- The app version alone is enough to reproduce what a server-driven screen showed.
- A broken server-driven layout can only be fixed by shipping a new build.
- No crash reports means no users are seeing a degraded server-driven screen.
- Validating a layout against the newest schema version is enough before publishing.