docs(docs): bootstrap Android SDK guides through the docs pipeline#381
Merged
Conversation
Add native/android.md, the verified fact base for the beta com.contentful.java:optimization-android Kotlin library, feeding both Android guides. Like iOS, the Android SDK runs the shared CoreStateful runtime through a JS bridge (QuickJS here), so behavioral facts anchor to the resolvable optimization-js-bridge/core-sdk keys and concept docs; Kotlin-only surface uses extern: pointers naming the exact file+symbol, since knowledge:check cannot resolve Kotlin #symbol pointers (no package.json/src). Records the Android-vs-iOS divergences: suspend initialize/resolveOptimizedEntry, StateFlow/SharedFlow (not Combine), replay-64 event streams, and the 10.0.2.2 emulator localhost. Passes pnpm knowledge:check. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Two per-UI blueprints for the one Android SDK, parallel to the iOS pair. Both omit the personalization explainer's managed-fetch clause (no fetch-by-ID) and prove "init + one accepted screen event" rather than an entry render. They encode the Android divergences from iOS (suspend init, StateFlow, replay-64 event streams) and, for Views, drive a full restructure: split the screen/custom-events section, move Identity into Core, and require the Application-diff plus AndroidManifest registration in the quick start. Passes pnpm guides:check. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Review escalation: the Views guide filtered eventStream on event["type"] == "screen" || "screenViewEvent", but the KB had no fact for the emitted event map's type field. Tracing source showed screenViewEvent is never emitted by core (it exists only as dead/defensive arms in the reference apps); screen views carry exactly type == "screen". Add the fact so the guide's corrected single-value check is grounded. Passes pnpm knowledge:check. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Rewrite both Android integration guides to the current archetype from their new blueprints and the Android knowledge base. Both gain the personalization explainer (managed-fetch clause omitted), two-milestone framing, and a prose "Before you start" replacing the old setup-inventory table. Quick starts now prove "init + one accepted screen event" with performable logcat verification and honest scoping, and describe the Kotlin reactive idiom (StateFlow/SharedFlow, replay-64 event streams) rather than iOS Combine semantics. Views additionally undergoes a full restructure: section reorder to the blueprint map, splitting screen tracking from custom events, moving Identity into Core, and a SceneDelegate-equivalent Application diff plus the AndroidManifest android:name registration inline with its silent-failure mode. Applies the three-role review: fixes the OptimizedEntry onTap baseline-vs-resolved mislabel, glosses selectedOptimizations/optimizationPossible/changes and the ResolvedOptimizedEntry wrapper, drops the untaught page from pre-consent blocked lists, and corrects the screenViewEvent filter (only type == "screen" is emitted). Passes pnpm guides:check and knowledge:check. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add the two Android blueprints to the authoring index and note the native Android family is now covered (with the Kotlin extern:-pointer exception, shared with iOS). Fold the durable rules the Android review surfaced into the authoring checklist: a required host-registration step (Android Application android:name) shown inline with its silent-failure mode; cross-SDK contrast asides bounded in a single-target guide; and a verify step that can distinguish success from failure (no unfalsifiable "renders baseline or variant" proof). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Tim Beyer (TimBeyer)
requested review from
Lotfi Anwar L Arif (Lotfi-Arif),
Felipe Mamud (fmamud) and
Charles Hudson (phobetron)
as code owners
July 20, 2026 15:42
Charles Hudson (phobetron)
previously approved these changes
Jul 20, 2026
Charles Hudson (phobetron)
left a comment
Charles Hudson (phobetron)
left a comment
Collaborator
There was a problem hiding this comment.
Seems reasonable (and running everything through Gradle might have been slow and tedious to get working right anyway, not a fan).
A content-loss audit of the reconciled guides against their pre-pipeline versions found capabilities trimmed along with reader-owned scaffolding. Restore them: - Views: the tri-state consent-banner observation (state.consent == null), and the trackTaps=false + onTap conflict caveat plus the app-owned-click-listener alternative for a component that needs a tap handler without SDK tap analytics. - Compose: the OptimizationApiConfig field names (experienceBaseUrl / insightsBaseUrl) in the config example, and the on-leave final duration-update caveat for entry view tracking. All verified against Kotlin source. Passes pnpm guides:check. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Tim Beyer (TimBeyer)
force-pushed
the
docs/bootstrap-android-sdk-guides
branch
from
July 20, 2026 20:39
5887dc7 to
4cdc8b8
Compare
Charles Hudson (phobetron)
approved these changes
Jul 21, 2026
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
2 participants
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.
Rebuilds the Android Jetpack Compose and XML Views integration guides through the current docs pipeline — the same bootstrap just done for iOS. They previously predated it: full guides with no knowledge base and no blueprints. This runs the bootstrap path end to end: comprehend source into the KB, author the editorial blueprints, reconcile the guide prose, then the three-role review with fixes funnelled back.
What's here (commit by commit)
feat(docs): bootstrap Android SDK knowledge base— newnative/android.md, the verified fact base for the betacom.contentful.java:optimization-androidKotlin library, feeding both guides.feat(docs): add Android Compose and Views guide blueprints— one per-UI blueprint each.fix(docs): record Android eventStream emitted event type discriminator— a fact added from a review escalation (see below).feat(docs): reconcile Android Compose and Views guides to the pipeline— both guides rewritten to the current archetype + review fixes; Views additionally restructured.docs(docs): register Android blueprints and funnel back review rules— authoring index + checklist updates.Key decisions (native SDK; parallels iOS, with real divergences)
package.json/src), soknowledge:checkcan't resolve Kotlin#symbolpointers. Kotlin-only facts useextern:pointers naming the exact file+symbol; behavior that runs in the shared QuickJS bridge anchors to the resolvableoptimization-js-bridge/core-sdkkeys.initialize/resolveOptimizedEntryaresuspend; the reactive idiom isStateFlow/SharedFlow, not Combine;eventStream/blockedEventStreamare replay-64SharedFlows (late subscribers receive recent events — unlike iOS's no-replay passthrough); QuickJS engine;10.0.2.2emulator localhost.Applicationdiff plus theAndroidManifest.xmlandroid:nameregistration inline with its silent-failure mode — without itonCreatenever runs.## Required setupinventory tables with prose## Before you start; added the personalization explainer + two-milestone framing. Views got a full restructure: section reorder to the blueprint map, splitting screen tracking from custom events, and moving Identity into Core.Review outcome (three roles, per guide)
eventStreamontype == "screen" || "screenViewEvent", butscreenViewEventis never emitted by core (dead/defensive code in the reference apps); onlytype == "screen"flows. The Views guide was corrected to the single value.onTapbaseline-vs-resolved mislabel, glossselectedOptimizations/optimizationPossible/changes/ResolvedOptimizedEntry/accessibilityIdentifier,pageorphan removed from pre-consent blocked lists, consistent reader-owned binder naming.Validation
pnpm knowledge:check✓ — 1031 source pointers across 10 fact files, noESCALATEmarkers.pnpm guides:check✓ — 10 blueprints, 139 planned sections, links and structure valid.Not done: Kotlin snippets are verified against the types and the reference implementation for shape, but not compiled/run through Gradle.
🤖 Generated with Claude Code