You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
protocol/ # cross-platform communication layer based on UCP
@@ -58,7 +58,7 @@ It does **not** refer to the React Native wrapper platform folders:
58
58
### What `--local` does
59
59
60
60
- For React Native iOS, `--local` wires CocoaPods to the in-repo `platforms/swift/` sources via a local path instead of a released pod version.
61
-
- For React Native Android, `--local` publishes/uses the in-repo `platforms/android/` SDK through Maven Local so Gradle resolves the local SDK artifact instead of a released Maven version.
61
+
- For React Native Android, `--local` publishes/uses the in-repo `platforms/android/` SDK through Maven Local so Gradle resolves the local `com.shopify:checkout-kit` and `com.shopify:embedded-checkout-protocol` artifacts instead of released Maven versions.
62
62
63
63
### When to use it
64
64
@@ -79,11 +79,11 @@ dev rn ios --local
79
79
dev rn android --local
80
80
81
81
# React Native Android unit tests using local platforms/android via Maven Local
82
-
# `dev rn test android` publishes platforms/android/lib to ~/.m2 first, then runs the RN module tests.
82
+
# `dev rn test android` publishes the Android SDK artifacts to ~/.m2 first, then runs the RN module tests.
83
83
dev rn test android
84
84
```
85
85
86
-
For ad-hoc Android Gradle test commands, publish the local Android SDK first and set `USE_LOCAL_SDK=1` so the React Native module resolves `com.shopify:checkout-kit:1.0.0`from Maven Local instead of the unreleased placeholder artifact:
86
+
For ad-hoc Android Gradle test commands, publish the local Android SDK first and set `USE_LOCAL_SDK=1` so the React Native sample resolves the local `com.shopify:checkout-kit` and `com.shopify:embedded-checkout-protocol` artifacts from Maven Local:
The React Native Android sample uses exclusive Maven Local resolution for those two `com.shopify` modules when `USE_LOCAL_SDK=1`. Keep that filtering in the sample Gradle build; duplicating exclusive repository filters for the same modules elsewhere can break dependency resolution.
96
+
95
97
## Sensitive configuration
96
98
97
99
Treat storefront environment and generated sample app configuration values as
Copy file name to clipboardExpand all lines: platforms/android/AGENTS.md
+35-21Lines changed: 35 additions & 21 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,22 +1,25 @@
1
-
# CLAUDE.md
1
+
# AGENTS.md
2
2
3
-
Guidance for Claude Code when working in this repository.
3
+
Guidance for AI agents when working in the Android platform.
4
4
5
5
## Project overview
6
6
7
-
Shopify Checkout Kit for Android is a published AAR library (`com.shopify:checkout-kit`) that presents Shopify checkouts as a native, dialog-hosted WebView in consumer apps. It is consumed by third-party Android apps via Maven Central, so changes to the library's public surface have real consumer impact and real reversal cost once released.
7
+
Shopify Checkout Kit for Android publishes AARs that are consumed by third-party Android apps via Maven Central, so changes to public surfaces have real consumer impact and real reversal cost once released.
8
8
9
-
Two modules matter:
9
+
The main modules are:
10
10
11
-
-**`lib/`** — the library itself. Everything here ships to consumers.
12
-
-**`samples/CheckoutKitAndroidDemo/`** — a demo app that consumes `lib/` as a source dependency. Changes here never reach consumers; this module is for internal testing and developer onboarding.
11
+
-**`lib/`** — the Checkout Kit library, published as `com.shopify:checkout-kit`. It presents Shopify checkouts as a native, dialog-hosted WebView in consumer apps.
12
+
-**`universal-commerce-protocol/`** — the Embedded Checkout Protocol artifact, published as `com.shopify:embedded-checkout-protocol`. The Gradle project path is still `:universal-commerce-protocol`, and the Kotlin package is `com.shopify.ucp.embedded.checkout`.
13
+
-**`samples/CheckoutKitAndroidDemo/`** — a demo app that consumes the Android modules as source dependencies. Changes here never reach consumers; this module is for internal testing and developer onboarding.
13
14
14
-
The sample is a separate Gradle composite (`samples/CheckoutKitAndroidDemo/settings.gradle`) that includes `:lib`from `../../lib`. The sample's `gradle.properties` and Gradle wrapper are independent of the root's.
15
+
The sample is a separate Gradle composite (`samples/CheckoutKitAndroidDemo/settings.gradle`) that includes `:lib`and `:universal-commerce-protocol` as source dependencies. The sample's `gradle.properties` and Gradle wrapper are independent of the root's.
15
16
16
17
## Where to make changes
17
18
18
-
- Library source: `lib/src/main/java/com/shopify/checkoutkit/`. Flat package at the top level, including generated protocol models.
- Library tests: `lib/src/test/java/com/shopify/checkoutkit/`. "No test, no merge" is a listed reject criterion in the repo-root `.github/CONTRIBUTING.md`.
- Java interop is a first-class concern — the library is commonly consumed from Java code. `lib/src/test/java/com/shopify/checkoutkit/InteropTest.java` exercises the public API from Java specifically; treat breakage there as a consumer-facing issue.
21
24
22
25
## Key components
@@ -25,7 +28,11 @@ The sample is a separate Gradle composite (`samples/CheckoutKitAndroidDemo/setti
25
28
-**`CheckoutDialog.kt`** — the dialog that hosts the WebView, including the progress indicator and checkout error coordination.
26
29
-**`CheckoutWebView.kt`** — primary WebView. Instruments page loads and attaches the ECP JavaScript interface.
27
30
-**`BaseWebView.kt`** — abstract base class. Any new WebView variant must extend this so shared configuration (user agent suffix, WebChromeClient hooks, navigation error handling) is consistent.
28
-
-**`EmbeddedCheckoutProtocol.kt`** — the Embedded Checkout Protocol JavaScript interface. Handles `ec.ready`, ECP notifications, and request/response delegations.
31
+
-**`CheckoutProtocol.kt`** — the curated consumer-facing Checkout Kit protocol API. This is where supported events/delegations are intentionally exposed.
32
+
-**`EmbeddedCheckoutProtocolBridge.kt`** — the internal JavaScript interface attached to the WebView. Handles `ec.ready`, ECP notifications, and request/response delegations.
33
+
-**`universal-commerce-protocol/src/main/java/com/shopify/ucp/embedded/checkout/EmbeddedCheckoutProtocol.kt`** — the generated low-level Embedded Checkout Protocol event catalog.
-**`CheckoutListener.kt`** + **`DefaultCheckoutListener`** — consumer-implemented lifecycle interface (failure, cancellation, permission prompts, file chooser). Changes here are consumer API changes.
31
38
-**`CheckoutPresentation.kt`** — Kotlin-first builder for per-presentation callbacks (`onFail`, `onCancel`, browser/system hooks, ECP `connect(...)`). Builds a `DefaultCheckoutListener` internally.
@@ -39,31 +46,38 @@ The sample is a separate Gradle composite (`samples/CheckoutKitAndroidDemo/setti
39
46
40
47
## Conventions
41
48
42
-
-**`-Xexplicit-api=strict`** is on (`lib/build.gradle`). Every public class, method, field, and property must have an explicit visibility modifier. "Accidentally public" is not a thing here. This is a consumer-protection rule — if you see a public-by-default declaration, it was deliberate.
49
+
-**`-Xexplicit-api=strict`** is on for both published Android modules. Every public class, method, field, and property must have an explicit visibility modifier. "Accidentally public" is not a thing here. This is a consumer-protection rule — if you see a public-by-default declaration, it was deliberate.
43
50
-**Max line length: 140** (detekt-enforced). Detekt config: `lib/detekt.config.yml`.
44
51
-**Library JVM target: 11.** Consumers must build with JDK 11+ to consume the AAR. Raising further is a major-version discussion.
45
-
-**Library Kotlin `apiVersion` / `languageVersion` are pinned at 2.0.** Set in `lib/build.gradle` so the AAR's bytecode stays consumable by Kotlin 2.0+ projects even though the compiler itself is on a newer 2.x. Bumping this pin is the consumer-facing breaking change, not bumping the compiler - treat it as a planned major-version event.
46
-
-**Prefer generated protocol models.** Before adding hand-written protocol DTOs, check the generated models in `lib/src/main/java/com/shopify/checkoutkit/Models.kt` and the OpenRPC schema. Use generated UCP/ECP types for wire payloads; reserve local DTOs for Android-internal transport helpers that are not represented in the schema.
52
+
-**Library Kotlin `apiVersion` / `languageVersion` are pinned at 2.0.** Set through `gradle/android-library-versions.gradle` so the AARs stay consumable by Kotlin 2.0+ projects even though the compiler itself is on a newer 2.x. Bumping this pin is the consumer-facing breaking change, not bumping the compiler - treat it as a planned major-version event.
53
+
-**SDK/toolchain compatibility values live in `gradle/android-library-versions.gradle`.** Dependency, plugin, and Android artifact versions live in `gradle/libs.versions.toml`.
54
+
-**Protocol vs kit boundary:** the protocol artifact should own generated raw wire names, generated models, thin descriptors, and encoding/decoding helpers. Checkout Kit should own curation, default behavior, WebView integration, and the higher-level consumer API.
55
+
-**Prefer generated protocol models.** Before adding hand-written protocol DTOs, check the generated models in `universal-commerce-protocol/src/main/java/com/shopify/ucp/embedded/checkout/Models.kt` and the OpenRPC schema. Use generated UCP/ECP types for wire payloads; reserve local DTOs for Android-internal transport helpers that are not represented in the schema.
47
56
48
57
## Public API surface
49
58
50
-
The library's public API is captured in `lib/api/lib.api` (managed by the [binary-compatibility-validator](https://github.com/Kotlin/binary-compatibility-validator) Gradle plugin). Every PR is gated by `./gradlew :lib:apiCheck` in CI — the build fails if the compiled public API diverges from the committed baseline.
59
+
The Android public APIs are captured by the [binary-compatibility-validator](https://github.com/Kotlin/binary-compatibility-validator) Gradle plugin:
60
+
61
+
-`lib/api/lib.api` for `com.shopify:checkout-kit`.
62
+
-`universal-commerce-protocol/api/universal-commerce-protocol.api` for `com.shopify:embedded-checkout-protocol`.
63
+
64
+
Every PR is gated by `./gradlew apiCheck` in CI — the build fails if the compiled public API diverges from the committed baselines.
51
65
52
66
If a change intentionally modifies public API (adding, removing, or changing any public class, method, field, or property):
53
67
54
-
1. Run `./gradlew :lib:apiDump` (or `dev android api dump`) to regenerate the baseline.
55
-
2. Review the diff in `lib/api/lib.api`— it's the single best indicator of consumer impact, and reviewers will focus on it.
68
+
1. Run `./gradlew apiDump` (or `dev android api dump`) to regenerate the baselines.
69
+
2. Review the `.api`diffs — they are the single best indicator of consumer impact, and reviewers will focus on them.
56
70
3. Commit the updated `.api` file in the same PR as the code change.
57
71
58
72
If `apiCheck` fails and you did *not* intend to change public API, the diff tells you what inadvertently leaked out. Fix the leak rather than updating the baseline — you've accidentally shifted the consumer contract.
**Transitive `androidx` bumps can silently raise the `compileSdk` floor** — review dependabot PRs with this in mind, and run `./gradlew :lib:apiCheck` and check `aarMetadata` output when bumping any `androidx.*` dependency.
92
+
**Transitive `androidx` bumps can silently raise the `compileSdk` floor** — review dependabot PRs with this in mind, and run `./gradlew apiCheck` and check `aarMetadata` output when bumping any `androidx.*` dependency.
79
93
80
94
## Release process
81
95
82
-
Versions are bumped via:
96
+
Published Android artifact versions are bumped via:
83
97
84
-
1.The `versionName` literal in `lib/build.gradle`.
98
+
1.`gradle/libs.versions.toml` (`checkoutKitAndroid` and `embeddedCheckoutProtocolAndroid`).
85
99
2. The install snippets in `README.md` (Gradle and Maven).
86
100
87
101
Android releases are tagged `android/X.Y.Z` (Swift releases use bare `X.Y.Z`). The publish workflow filters on the `android/` prefix — without it, nothing publishes on the Android side.
0 commit comments