README v2 and AGENTS.md: quickstart first, docs links, agent guidance

[Vlada-Q]

Summary

Files: README.md, AGENTS.md.

• Header without the landing page: one paragraph on what Qonversion is and what this repository holds; four badges (version, package manager, license, platforms), each linking to where the value can be checked.
• Quickstart in three steps within the first 50 lines: install → initialize → first call (checkEntitlements / entitlements). The mode is named out loud, with a link to Analytics Mode.
• Five links into the docs: Welcome, platform setup, Quick start, API reference, For agents.
• What this SDK does: what the package does, worded as how it works rather than as a promise.
• For agents: the docs MCP server, markdown versions of pages, llms.txt, the Qonversion MCP server with the Apple Ads access conditions, the two-step confirmation for destructive tools, and the integration prompt (the docs text, with step 3 taking the SDK version from the release tag or the package registry).
• Requirements from code: minimum versions taken from the manifests in this repository (see Facts checked).
• AGENTS.md for coding agents: how to get the current version instead of one from memory, install, init, first call, docs as markdown, MCP, and what an agent must not do without the human saying yes (keys, mode, live project configuration, destructive MCP tools, environment).

Removed on purpose: the Analytics / A/B Experiments / Integrations / Why Qonversion? sections (they duplicate the website and push the install below the fold); long platform guides → a link into the docs; all images except the header.

Also removed in this repository: the Web2App guide (~95 lines) → three lines and a link. The Installation section from the hygiene PR (#870) is kept.

Facts checked

Minimum versions, from this repository's manifests:

• minSdkVersion 23 · compileSdk 34 — sdk/build.gradle

Init and first-call signatures: sdk/src/main/java/com/qonversion/android/sdk/QonversionConfig.kt, sdk/src/main/java/com/qonversion/android/sdk/Qonversion.kt, sdk/src/main/java/com/qonversion/android/sdk/listeners/QonversionCallback.kt, sdk/src/main/java/com/qonversion/android/sdk/dto/entitlements/QEntitlement.kt.

Versions: The install snippet pins the exact current version, 9.8.0 (latest sdk/* release on 2026-10-12), with "current at the time of writing; check Releases" — instead of 9.+. The version badge is filtered to sdk/*, otherwise it shows the nocodes/* tag.

Header image

The approved header (logo and platform list, no positioning text) ships in this PR as .github/assets/sdk-header.png, referenced by a one-line <img> tag on line 1 with a relative path, which GitHub, npm and pub.dev all resolve. The quickstart line count does not move.

Links

All 29 URLs in these files checked with curl -sI -L on 2026-10-12: 27 return 200, the rest are expected:

• 401 https://mcp.qonversion.io/mcp — OAuth endpoint of the MCP server, expected without a token
• 405 https://documentation.qonversion.io/mcp — the docs MCP endpoint does not answer GET, it speaks MCP

LICENSE exists in this repository (hygiene PRs merged 2026-10-09/10). docs/for-agents is live.

Review

Four independent reviews in the marketing hub (product, marketing, QA, brand), two iterations. Maintainer answers of 2026-10-09 applied here: Apple Ads in MCP: tools need the apple_ads account feature; campaign changes additionally need the apple_ads:write scope and campaign-management permission (mcp-server#126); exact 9.8.0 instead of 9.+; the discard_* docs-gap note removed from AGENTS.md.

Repository description (settings, not a file)

The repository description shown under the name on GitHub is a setting, so it cannot be part of this PR. Proposed text to set when merging, so the description, the README header and the docs say the same thing:

Qonversion Android SDK: in-app purchases confirmed with Google Play, entitlements, and the revenue data behind Apple Ads, A/B tests and analytics.

Current: Android SDK for cross-platform in-app purchase and subscription infrastructure, revenue analytics, engagement automation, and integrations

One command for a maintainer: gh repo edit qonversion/android-sdk --description "Qonversion Android SDK: in-app purchases confirmed with Google Play, entitlements, and the revenue data behind Apple Ads, A/B tests and analytics.".

Maintainer review rounds of 2026-10-13 and 2026-10-14 applied (see the PR comments).

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Repository: qonversion/coderabbit/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: d22a8798-4f5d-47c4-9c55-08c65bf7a893

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[SpertsyanKM]

Thanks, Vlada — snippets, minimum versions, pins, links and the MCP destructive-tool flow check out against main. Changes needed before merge:

This repo

• AGENTS.md:18 (minor) — releases/latest --jq .tag_name can return nocodes/* and returns sdk/9.8.0 with prefix. Suggest gh api repos/qonversion/android-sdk/releases --jq '[.[]|select(.tag_name|startswith("sdk/"))][0].tag_name|ltrimstr("sdk/")'.
• AGENTS.md:53-59 (minor) — first-call snippet has no imports (QonversionEntitlementsCallback, QEntitlement, QonversionError); the README version has them.
• README.md:152 / AGENTS.md:113 (nit) — "Kotlin JVM toolchain 17" is the SDK's own build setting, not a consumer minimum; reword or drop.
• Repo description: "the revenue data behind Apple Ads" is odd for Android-only. Suggest: "Qonversion Android SDK: Google Play purchases validated server-side, entitlements, and the revenue data behind A/B tests and analytics."

Shared with the other README v2 / AGENTS.md PRs

• Apple Ads availability — my earlier guidance is outdated, sorry. After 2026-10-09, mcp-server #126 (DEV-1480) removed the separate write beta: there is no apple_ads_write account gate any more (mcp-server/internal/tools/apple_ads_write.go:134). Writes need the apple_ads account feature, the apple_ads:write scope, a dashboard member with campaign-management permission and Apple org write access, and can be switched off server-side. "Closed beta — ask support to switch it on" sends agents the wrong way. Until Sam finalises the Apple Ads docs, please use neutral wording, e.g.: "Apple Ads tools need the feature on your account (404 otherwise); campaign changes additionally need the apple_ads:write scope and a team member with campaign-management permission — check get_apple_ads_connection_status."
• AGENTS.md "If the three disagree, the docs page wins". For the version the docs page lags (iOS page says 6.17.0, Flutter 11.11.0, Unity 9.10.0 and "2018.3", Android 9.+, Cordova still lists cordova-ios 6.x; Web/RN pages name no version). Make the release tag / package registry authoritative for the version, docs for API usage, and tell the agent to report a mismatch. Same for the integration prompt line "use the SDK version the docs name".

[Vlada-Q]

@SpertsyanKM thanks for the review. All points are addressed in 4333789 — could you take another look?

This repo

• AGENTS.md:18 (version command). Replaced with your command: gh api repos/qonversion/android-sdk/releases --jq '[.[]|select(.tag_name|startswith("sdk/"))][0].tag_name|ltrimstr("sdk/")' (returns 9.8.0 today). The Install note no longer repeats the releases/latest warning.
• AGENTS.md:53-59 (imports). The first-call snippet now imports QonversionError, QEntitlement and QonversionEntitlementsCallback, same as the README.
• README.md:152 / AGENTS.md:113 (toolchain). "Kotlin JVM toolchain 17" removed from both Requirements.

Shared with the other README v2 / AGENTS.md PRs

• Apple Ads availability. "Closed beta", "ask support to switch it on" and "per account on request" are gone from README (For agents) and AGENTS.md. The wording from your review is applied as is: "Apple Ads tools need the feature on your account (404 otherwise); campaign changes additionally need the apple_ads:write scope and a team member with campaign-management permission — check get_apple_ads_connection_status." AGENTS.md adds one sentence: a refused Apple Ads call means missing access, not a broken server — do not retry or work around it, tell the human. This wording is pending Sam's confirmation; it will be updated when he finalises the Apple Ads docs.
• Source of the version. "If the three disagree, the docs page wins" is replaced: the release tag and the package registry (Maven Central maven-metadata.xml) are the source for the version, the docs page for install steps and API usage; on a version mismatch the agent uses the tag/registry and tells the human. The integration prompt in the README (step 3) now says to take the version from the latest release tag or the package registry, not from the docs page, and to report a disagreement.

Repo description is left to you, as agreed. Not merging from our side.

[SpertsyanKM]

Re-reviewed 4333789 — the round-1 points are fixed (sdk/* version command, imports, JVM toolchain line, Apple Ads, version source). Verified: tag = Maven latest = 9.8.0; import paths exist; io.qonversion:no-codes is on Maven Central.

Two things I missed in round 1 (both were already fixed on iOS):

1. AGENTS.md:115 — blocker. sample/src/main/java/io/qonversion/sample/App.java is called "the reference for initialization", but it hardcodes a project key (App.java:17, contradicts AGENTS.md:51 "never reuse a key you saw in a sample"), sets QEnvironment.Sandbox (App.java:30) and a proxy URL (App.java:38-39), and it is Java while the snippets are Kotlin. Suggested:

   sample/ — a Java demo app that initializes the SDK, lists products, purchases and reads entitlements; it runs in the sandbox environment. It is not a reference for initialization: App.java hardcodes a sample project key, sets QEnvironment.Sandbox and a proxy URL. The reference is the Initialize snippet above (the same as in the README).

   And in README.md:143 add: "It runs in the sandbox environment; for your own initialization, use the Quickstart snippet above."

2. README.md:80-81. "the entitlement is already granted server-side when the link arrives" — same inaccuracy as fixed on iOS. Suggested:

   When handleRedemptionLink returns success, the entitlement has already been granted server-side, so you do not add an identify call yourself; the redemption Uri carries a single-use token — do not log or display it.

Nits:

• AGENTS.md:111 — "QONEnvironment on iOS" is Objective-C only now; suggest "(Qonversion.Environment / QONEnvironment on iOS, QEnvironment on Android, Environment in the wrappers)" — or just name this SDK's QEnvironment.
• PR body line 20 still lists "Kotlin JVM toolchain 17".

Once these are in, it's good to merge from your side — no need for another round from me unless something else changes.

---

Shared across all nine README v2 / AGENTS.md PRs

• PR body before squash-merge. The body still says reading Apple Ads "is on for all accounts" and changing campaigns "is a closed beta per account". Both are outdated (mcp-server#126). The body becomes the squash commit message, so please update that sentence, or replace the commit body when merging, e.g.: "Apple Ads in MCP: tools need the apple_ads account feature; campaign changes additionally need the apple_ads:write scope and campaign-management permission (mcp-server#126)."
• "A refused Apple Ads call means missing access … do not retry" (AGENTS.md). Slightly too absolute: get_apple_ads_connection_status can report campaign_management.state: unknown (permission snapshot not landed yet — try later), and an Apple authorization can need reauthorization. Suggested: "A refused Apple Ads call usually means missing access or an Apple authorization that needs attention, not a broken server: call get_apple_ads_connection_status, do not work around it, and tell the human what it reports." Non-blocking; can go together with Sam's final Apple Ads wording.

[Vlada-Q]

@SpertsyanKM round 2 is done in e4229e4, CI is green:

• AGENTS.md:115 (blocker). Your text, as is: sample/ is a Java demo app that runs in the sandbox; App.java hardcodes a sample project key, sets QEnvironment.Sandbox and a proxy URL, so the Initialize snippet is the reference.
• README.md:143. Added: "It runs in the sandbox environment; for your own initialization, use the Quickstart snippet above."
• README.md:80-81. "When handleRedemptionLink returns success, the entitlement has already been granted server-side, so you do not add an identify call yourself; the redemption Uri carries a single-use token — do not log or display it."
• AGENTS.md:111 (nit). "In this SDK the enum is QEnvironment (sdk/src/main/java/com/qonversion/android/sdk/dto/QEnvironment.kt); read it from the SDK, not from memory."
• PR body. "Kotlin JVM toolchain 17" removed; the Apple Ads sentence is replaced with your text (mcp-server#126).
• Apple Ads (non-blocking). AGENTS.md uses your softer sentence: call get_apple_ads_connection_status, do not work around it, tell the human what it reports.

I tried to merge as you suggested, but the branch rules block it while your review is still "changes requested". Could you approve (or merge it yourself)? I don't want to use an admin override.

[SpertsyanKM]

Re-reviewed e4229e4: all round-2 points are fixed and verified against source. Thanks! Merging.

Tiny follow-up nit (from my own suggestion, sorry): AGENTS.md:116 calls sample/ "a Java demo app", but only App.java is Java, the rest of the sample is Kotlin. Not blocking.