Rewrite the README for a publisher who has never seen this code - #2
Merged
Merged
Conversation
The old README explained the integration before it let anyone run it: the Running section sat at line 167, after every rationale, and it never said which buttons drive the demo. It also never stated the thing that makes the first five minutes work, that the checked-in ids are CloudX's public sample app, so a clone runs with no account and no setup. Restructured so the order matches what a stranger does: see it, run it, understand it, adopt it. The screenshots move to the top, Run it becomes the second section and names the two buttons, and Required setup becomes Point it at your own app, since none of it is required to see the demo work. Dropped the parts written for a reviewer rather than a reader: the `grep -rn "CloudX\.\|MobileAds\."` proof of UI separation and the paragraph listing which framework imports each integration file uses. The claim those supported is kept. lib/ui and lib/main.dart move out of the copy-this table, which was telling readers to copy a file and ignore it in the same row. Added a Getting help section, which did not exist, and framed the four cycle gotchas as things to understand before adapting the code rather than as loose details. Links now point at /en/flutter/integration directly, because /en/flutter is a 307 to it.
There was a problem hiding this comment.
🟡 Changes recommended
Several setup statements are inaccurate or incomplete for first-time users.
Get a fresh assessment by requesting another Copilot review.
Pull request overview
Rewrites the README to make the Trusted Arbiter demo easier for new publishers to run, understand, and adopt.
Changes:
- Moves setup instructions and screenshots earlier.
- Clarifies the auction flow and integration files.
- Adds troubleshooting, adapter, and support guidance.
File summaries
| File | Description |
|---|---|
| README.md | Reorganizes and expands demo documentation. |
Review details
Suppressed comments (1)
README.md:193
- Calling this the “full CloudX set” is inaccurate: the next paragraph explicitly identifies a CloudX adapter omitted from both lists. Since publishers are being told to select from this inventory, describe it as the set included in this demo rather than implying it enumerates every available adapter.
The adapter list in `android/app/build.gradle.kts` and `ios/Podfile` is the full
CloudX set, so you can see the shape of it. **Take only the networks your
dashboard actually serves**; each one adds to your binary.
- Files reviewed: 1/1 changed files
- Comments generated: 3
- Review effort level: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+24
to
+26
| You need Flutter 3.44 or newer (Dart 3.12), and Xcode if you want the iOS side. | ||
| Nothing else: the ids checked in belong to CloudX's public sample app, so the | ||
| demo runs as-is. |
Comment on lines
+34
to
+37
| Tap **Load both**, wait for both sides to settle, then tap **Show winner**. On | ||
| iOS you will be asked for tracking permission first; see the ATT note under | ||
| [Point it at your own app](#point-it-at-your-own-app) for why that has to come | ||
| before anything else. |
| `lib/ui/` and `lib/main.dart` are the demo's screen and entry point. They are | ||
| here so the app runs; they are not part of the integration. | ||
|
|
||
| **Take fewer files and it will not build.** The controller reports through |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
README only, no code. The old one explained the integration before it let anyone run it, and assumed a reader who already knows CloudX. This reorders it around what a stranger actually does: see it, run it, understand it, adopt it.
What changed and why
Running moved from line 167 to the second section. It sat after every rationale, so the first thing a publisher could act on was six screens down. The screenshots moved to the top for the same reason: the first thing you see is now what you are about to get.
It now says the demo runs with no account. The checked-in ids are CloudX's public sample app, so
flutter runworks on a fresh clone. That was true before and stated nowhere, which is the single most useful fact for the first five minutes.It names the buttons. The old README never mentioned tapping Load both then Show winner. A reader who built the app had no instructions for operating it.
"Required setup" is now "Point it at your own app". Same five steps. The old title implied you needed all of it to run anything, which is false. Step 1 also changed from "enable it in the dashboard" to "ask CloudX to enable Trusted Arbiter for your app", because a new publisher has no toggle for this.
Removed two passages written for a reviewer, not a reader. The
grep -rn "CloudX\.\|MobileAds\."proof that no CloudX call lives outsidelib/cloudx/, and the paragraph listing which framework imports each integration file uses. Both existed to demonstrate the separation holds during review. The claim they supported is kept in one sentence.lib/ui/andlib/main.dartmoved out of the copy-this table. That table is headed "What to copy into your app" and two of its rows said, in effect, copy this and ignore it. They are now a sentence explaining that they are the demo's screen and entry point.The four cycle gotchas are framed rather than listed. Same four items, now introduced as things that are easy to get wrong, already handled in the code, and worth understanding before adapting it.
Added a "Getting help" section, which did not exist: integration guide, Trusted Arbiter page, changelog, the pub.dev package, and that an app key or the arbiter switch comes from a CloudX contact.
Checked
/en/flutteris a 307 to/en/flutter/integration, so links point at the target directly.docs/images/, and no image is referenced that is not in the repo.#point-it-at-your-own-app, matches its heading.Not addressed
This repository has no LICENSE and no CONTRIBUTING, which is unusual for a public demo. Out of scope here and a decision for a human.
The public React Native demo's README still follows the structure this one just moved away from, so the two now diverge. Worth deciding separately whether it follows.