diff --git a/README.md b/README.md index 5b969f66..71916fff 100644 --- a/README.md +++ b/README.md @@ -37,13 +37,68 @@ Checkout Kit is a monorepo containing all the platforms Checkout Kit supports to | [`com.shopify:checkout-kit`](platforms/android/) | [![Maven Central](https://img.shields.io/maven-central/v/com.shopify/checkout-kit.svg?label=Maven%20Central)](https://central.sonatype.com/artifact/com.shopify/checkout-kit) | Maven Central | Android checkout presentation and accelerated checkout support. | [Readme](platforms/android/README.md) | | [`@shopify/checkout-kit`](platforms/react-native/) | [![npm latest](https://img.shields.io/npm/v/@shopify/checkout-kit/latest.svg?label=npm)](https://www.npmjs.com/package/@shopify/checkout-kit) | npm | React Native wrapper for Checkout Kit. | [Readme](platforms/react-native/README.md) | +## AI Quick Start + +### Install Checkout Skills + +Install the Checkout Kit skills: + +```bash +npx skills add Shopify/checkout-kit +``` + +Checkout Kit skills: + +| Skill | Use when | +| --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | +| [Migrate from Checkout Sheet Kit to Checkout Kit](skills/checkout-sheet-kit-to-checkout-kit-migration/SKILL.md) | Moving from legacy package names to Checkout Kit v1, including version reset and lifecycle changes. | +| [Present, preload, and invalidate checkout](skills/checkout-kit-present-preload-invalidate/SKILL.md) | Applying shared checkout lifecycle guidance across platforms. | +| [Lifecycle events](skills/checkout-kit-lifecycle-events/SKILL.md) | Handling completion, cancellation, failure, external links, and protocol notifications. | + +### Local Clone + +Checkout Kit works best with AI tools when they can inspect this repository locally instead of relying only on web search. + +1. Clone a shallow local copy of Checkout Kit: + + ```bash + git clone --depth 1 https://github.com/Shopify/checkout-kit.git ~/.local/share/checkout-kit/checkout-kit + ``` + +2. Add a reference to your app's agent instructions file. Replace `~/some-repo/CLAUDE.md` with your app's `CLAUDE.md`, `AGENTS.md`, or equivalent file: + + ```bash + cat >> ~/some-repo/CLAUDE.md <<'EOF' + ## Local Checkout Kit Source + + The Checkout Kit repository is cloned to + `~/.local/share/checkout-kit/checkout-kit` for reference. Use this local + source to explore APIs, find usage examples, inspect protocol schemas, and + understand implementation details when the documentation is not enough. + + Prefer local source over memory. Use Shopify docs only to confirm current + public guidance: https://shopify.dev/docs/storefronts/mobile + EOF + ``` + +3. Ask your AI assistant to read the relevant skill before suggesting code: + + ```text + Launch a Checkout Kit research agent to understand the library on the `.local/share/checkout-kit/checkout-kit` clone. + Read README.md, relevant library source code (swift/, /android, /react-native), + protocol/schemas/, the relevant skill, and the skill's references/guide.md before suggesting code. + ``` + ## Versioning -Checkout Kit is the new name for the Checkout Sheet Kit SDKs. It resets the version line to Checkout Kit v1, and all future development will be under Checkout Kit. +Checkout Kit is the new name for the Checkout Sheet Kit SDKs. It is a renamed and reset release line: all future development moves to the new Checkout Kit package names, with `Sheet` removed from the package name, and all three platforms start again at Checkout Kit `v1`. + +### Legacy Checkout Sheet Kit -### Legacy v3 +The legacy Checkout Sheet Kit lines are deprecated and remain available for apps maintaining older integrations. Checkout Sheet Kit for Swift and Checkout Sheet Kit for Android end on their `v3` major-version lines. Checkout Sheet Kit for React Native ends on its `v4` New Architecture release line. These versions do not roll forward into Checkout Kit; Checkout Kit starts at `v1` for Swift, Android, and React Native. -The legacy Checkout Sheet Kit lines are deprecated and remain available for apps maintaining older integrations. +> [!TIP] +> Use the [Migrate from Checkout Sheet Kit to Checkout Kit](skills/checkout-sheet-kit-to-checkout-kit-migration/SKILL.md) skill when upgrading. | Platform | Status | Package | Final release | Readme | | ------------ | ----------------------------------------------------------------------- | ----------------------------------- | ------------- | --------------------------------------------------------------------------- | diff --git a/skills/checkout-kit-lifecycle-events/AGENTS.md b/skills/checkout-kit-lifecycle-events/AGENTS.md new file mode 100644 index 00000000..56063c32 --- /dev/null +++ b/skills/checkout-kit-lifecycle-events/AGENTS.md @@ -0,0 +1,3 @@ +# Checkout Kit Lifecycle Events + +Use `SKILL.md` as the entrypoint for this skill. Read `references/guide.md` for shared lifecycle event guidance, then read the target platform file: `references/swift.md`, `references/android.md`, or `references/react-native.md`. diff --git a/skills/checkout-kit-lifecycle-events/SKILL.md b/skills/checkout-kit-lifecycle-events/SKILL.md new file mode 100644 index 00000000..4f502e3e --- /dev/null +++ b/skills/checkout-kit-lifecycle-events/SKILL.md @@ -0,0 +1,21 @@ +--- +name: checkout-kit-lifecycle-events +description: Use when implementing, migrating, or reviewing Checkout Kit lifecycle event handling, including completion, cancellation, failure, external links, and UCP-backed Checkout Protocol notifications. +--- + +# Checkout Kit Lifecycle Events + +Use this skill when the user needs to handle checkout lifecycle events, migrate callback/event-processor code, or wire protocol notifications into app state. + +## Start with local truth + +Read these local files before suggesting code: + +- `README.md` for current package and docs links. +- The target platform README: `swift/README.md`, `android/README.md`, or `react-native/README.md`. +- `protocol/services/shopping/embedded.openrpc.json` for protocol notifications and request methods. +- `protocol/schemas/` for UCP payload shape. +- `references/guide.md` for shared lifecycle event guidance. +- The platform sample for the target app: `references/swift.md`, `references/android.md`, or `references/react-native.md`. + +Prefer local source over memory. Use Shopify docs only to confirm current public guidance: https://shopify.dev/docs/storefronts/mobile diff --git a/skills/checkout-kit-lifecycle-events/references/android.md b/skills/checkout-kit-lifecycle-events/references/android.md new file mode 100644 index 00000000..e58dfed7 --- /dev/null +++ b/skills/checkout-kit-lifecycle-events/references/android.md @@ -0,0 +1,48 @@ +# Android + +```kotlin +import com.shopify.checkoutkit.CheckoutProtocol +import com.shopify.checkoutkit.DefaultCheckoutEventProcessor +import com.shopify.checkoutkit.ShopifyCheckoutKit +import com.shopify.checkoutkit.lifecycleevents.CheckoutCompletedEvent + +val protocolClient = CheckoutProtocol.Client() + .on(CheckoutProtocol.ready) { payload -> + recordDelegations(payload.delegations) + } + .on(CheckoutProtocol.start) { checkout -> + hideLoadingShell(checkout) + } + .on(CheckoutProtocol.complete) { checkout -> + navigateToConfirmation(checkout) + } + .on(CheckoutProtocol.messagesChange) { checkout -> + renderCheckoutMessages(checkout.messages) + } + .on(CheckoutProtocol.lineItemsChange) { checkout -> + syncCartSummary(checkout.lineItems) + } + .on(CheckoutProtocol.buyerChange) { checkout -> + syncBuyerState(checkout.buyer) + } + .on(CheckoutProtocol.paymentChange) { checkout -> + syncPaymentState(checkout.payment) + } + .onOpenExternalUrl { uri -> + openExternalUrl(uri) + true + } + +val processor = object : DefaultCheckoutEventProcessor(activity) { + override fun onCheckoutCompleted(event: CheckoutCompletedEvent) { + // Keep only if the app still needs legacy completion handling. + } +} + +ShopifyCheckoutKit.present( + checkoutUrl = checkoutUrl, + context = activity, + checkoutEventProcessor = processor, + communicationClient = protocolClient, +) +``` diff --git a/skills/checkout-kit-lifecycle-events/references/guide.md b/skills/checkout-kit-lifecycle-events/references/guide.md new file mode 100644 index 00000000..cbda0d76 --- /dev/null +++ b/skills/checkout-kit-lifecycle-events/references/guide.md @@ -0,0 +1,39 @@ +# Lifecycle Events Guide + +## Core Model + +Lifecycle handling should connect checkout state changes to app-owned side effects: navigation, confirmation screens, loading UI, cart refreshes, external URL handling, and error UI. + +Prefer protocol notifications where the platform exposes them. Keep legacy callbacks only when the platform still requires them or when the protocol does not expose the event needed by the app. + +## Protocol Events + +Use protocol events as the source of truth when available: + +- `ec.ready`: handshake and delegated capability discovery. +- `ec.start`: checkout is visible and interactive enough for host UI transitions. +- `ec.complete`: checkout completed; navigate or refresh order state. +- `ec.messages.change`: checkout warnings, errors, and informational messages changed. +- `ec.line_items.change`: line items changed. +- `ec.buyer.change`: buyer details changed. +- `ec.payment.change`: payment state changed. +- `ec.window.open_request`: checkout requests that the host open an external URL. + +Do not assume every legacy callback has a one-to-one replacement. If a callback mixed several concerns, split it into protocol handlers and app-owned state transitions. + +## Platform Samples + +Read the platform file for the target app: + +- `references/swift.md` +- `references/android.md` +- `references/react-native.md` + +## Review Checklist + +- Completion handling navigates or refreshes state exactly once. +- Cancellation and failure paths restore the host UI and preserve cart state. +- External links are handled intentionally. +- Protocol handlers update app state without duplicating legacy callback side effects. +- Web pixel events are not relayed to the native layer. +- Event payload handling does not assume personally identifiable information is present. diff --git a/skills/checkout-kit-lifecycle-events/references/react-native.md b/skills/checkout-kit-lifecycle-events/references/react-native.md new file mode 100644 index 00000000..bb0b05f1 --- /dev/null +++ b/skills/checkout-kit-lifecycle-events/references/react-native.md @@ -0,0 +1,44 @@ +# React Native + +Use this as the intended wrapper shape. Check the installed React Native package before copying names directly. + +```tsx +import {Linking} from 'react-native'; +import { + createCheckoutProtocolClient, + useShopifyCheckoutSheet, +} from '@shopify/checkout-kit'; + +const shopifyCheckout = useShopifyCheckoutSheet(); + +const checkoutClient = createCheckoutProtocolClient() + .on('ec.ready', ({delegate}) => { + recordDelegations(delegate); + }) + .on('ec.start', ({checkout}) => { + hideLoadingShell(checkout); + }) + .on('ec.complete', ({checkout}) => { + navigateToConfirmation(checkout); + }) + .on('ec.messages.change', ({checkout}) => { + renderCheckoutMessages(checkout.messages); + }) + .on('ec.line_items.change', ({checkout}) => { + syncCartSummary(checkout.line_items); + }) + .on('ec.buyer.change', ({checkout}) => { + syncBuyerState(checkout.buyer); + }) + .on('ec.payment.change', ({checkout}) => { + syncPaymentState(checkout.payment); + }) + .onOpenExternalUrl((url) => { + Linking.openURL(url); + return true; + }); + +shopifyCheckout.present(checkoutUrl, { + protocolClient: checkoutClient, +}); +``` diff --git a/skills/checkout-kit-lifecycle-events/references/swift.md b/skills/checkout-kit-lifecycle-events/references/swift.md new file mode 100644 index 00000000..203e80b8 --- /dev/null +++ b/skills/checkout-kit-lifecycle-events/references/swift.md @@ -0,0 +1,46 @@ +# Swift + +```swift +import ShopifyCheckoutKit +import UIKit + +let checkout = ShopifyCheckoutKit.present(checkout: checkoutURL, from: viewController) + .onComplete { event in + navigateToConfirmation(event) + } + .onCancel { + handleCheckoutCancel() + } + .onFail { error in + renderCheckoutError(error) + } + .onLinkClick { url in + openExternalURL(url) + } +``` + +```swift +final class AppCheckoutDelegate: CheckoutDelegate { + func checkoutDidComplete(event: CheckoutCompletedEvent) { + navigateToConfirmation(event) + } + + func checkoutDidCancel() { + handleCheckoutCancel() + } + + func checkoutDidFail(error: CheckoutError) { + renderCheckoutError(error) + } + + func checkoutDidClickLink(url: URL) { + openExternalURL(url) + } +} + +ShopifyCheckoutKit.present( + checkout: checkoutURL, + from: viewController, + delegate: AppCheckoutDelegate() +) +``` diff --git a/skills/checkout-kit-present-preload-invalidate/AGENTS.md b/skills/checkout-kit-present-preload-invalidate/AGENTS.md new file mode 100644 index 00000000..5bd7ff1b --- /dev/null +++ b/skills/checkout-kit-present-preload-invalidate/AGENTS.md @@ -0,0 +1,3 @@ +# Present, Preload, and Invalidate Checkout + +Use `SKILL.md` as the entrypoint for this skill. Read `references/guide.md` for shared lifecycle rules, then read the target platform file: `references/swift.md`, `references/android.md`, or `references/react-native.md`. diff --git a/skills/checkout-kit-present-preload-invalidate/SKILL.md b/skills/checkout-kit-present-preload-invalidate/SKILL.md new file mode 100644 index 00000000..431cffb7 --- /dev/null +++ b/skills/checkout-kit-present-preload-invalidate/SKILL.md @@ -0,0 +1,21 @@ +--- +name: checkout-kit-present-preload-invalidate +description: Use when implementing or reviewing Checkout Kit present, preload, and invalidate behavior across platforms, especially when deciding when to preload after cart changes and when to clear cached checkout state. +--- + +# Present, Preload, and Invalidate Checkout + +Use this skill when the user is wiring Checkout Kit into a cart or checkout flow, improving checkout performance, or debugging stale checkout state. + +## Start with local truth + +Read these local files before suggesting code: + +- `README.md` for current package and docs links. +- The target platform README: `swift/README.md`, `android/README.md`, or `react-native/README.md`. +- Sample apps for realistic cart and checkout wiring. +- The platform source for exact function names and configuration shape. +- `references/guide.md` for lifecycle rules, platform-neutral flow, and review checklist. +- The platform sample for the target app: `references/swift.md`, `references/android.md`, or `references/react-native.md`. + +Prefer local source over memory. Use Shopify docs only to confirm current public guidance: https://shopify.dev/docs/storefronts/mobile diff --git a/skills/checkout-kit-present-preload-invalidate/references/android.md b/skills/checkout-kit-present-preload-invalidate/references/android.md new file mode 100644 index 00000000..40ad4f01 --- /dev/null +++ b/skills/checkout-kit-present-preload-invalidate/references/android.md @@ -0,0 +1,45 @@ +# Android + +```kotlin +import androidx.lifecycle.lifecycleScope +import com.shopify.checkoutkit.ShopifyCheckoutKit +import kotlinx.coroutines.Job +import kotlinx.coroutines.delay +import kotlinx.coroutines.launch + +private var preloadJob: Job? = null +private var preloadedCheckoutUrl: String? = null + +fun onCartStateSettled(checkoutUrl: String) { + preloadJob?.cancel() + preloadJob = lifecycleScope.launch { + delay(300) + ShopifyCheckoutKit.preload(checkoutUrl, activity) + preloadedCheckoutUrl = checkoutUrl + } +} + +fun onCheckoutTapped(checkoutUrl: String) { + ShopifyCheckoutKit.present( + checkoutUrl = checkoutUrl, + context = activity, + checkoutEventProcessor = checkoutEventProcessor, + ) +} + +fun onCheckoutAffectingStateChanged(freshCheckoutUrl: String, cartOrBuyerChanged: Boolean) { + val preloadedCheckoutIsStale = preloadedCheckoutUrl != null && preloadedCheckoutUrl != freshCheckoutUrl + + if (cartOrBuyerChanged && preloadedCheckoutIsStale) { + ShopifyCheckoutKit.invalidate() + preloadedCheckoutUrl = null + } + + onCartStateSettled(freshCheckoutUrl) +} + +fun onSessionBoundaryChanged() { + ShopifyCheckoutKit.invalidate() + preloadedCheckoutUrl = null +} +``` diff --git a/skills/checkout-kit-present-preload-invalidate/references/guide.md b/skills/checkout-kit-present-preload-invalidate/references/guide.md new file mode 100644 index 00000000..38b736e8 --- /dev/null +++ b/skills/checkout-kit-present-preload-invalidate/references/guide.md @@ -0,0 +1,59 @@ +# Present, Preload, and Invalidate Guide + +## Core Model + +`present` is the required buyer-facing action. `preload` is an optimization hint. `invalidate` clears preloaded checkout state when the app knows that cached checkout is stale or should no longer be reused. + +Checkout presentation must still work when preload was skipped, ignored, rejected, interrupted, or not finished. + +## When to Preload + +Preload only when there is a strong signal that the buyer is likely to check out soon, such as: + +- Cart screen appears with a valid checkout URL. +- Buyer taps or focuses near a checkout call to action. +- Cart totals, buyer identity, or delivery/payment context have settled after a change. + +Avoid preloading on every add-to-cart event. That can waste device resources, create stale checkout state, and put unnecessary load on Shopify systems. + +Do not call preload after the buyer has already pressed checkout as a step before presenting. At that point, present checkout directly. A late preload can consume extra resources without improving buyer experience, and during flash sales it may be discarded before it can be used. + +## When to Preload Again + +Call preload again when the checkout URL or checkout-affecting context changes: + +- Cart line item, quantity, discount, buyer identity, delivery preference, or selling plan changes. +- Checkout configuration changes, such as theme, title, locale, or feature flags. +- The app regenerated the cart or checkout URL. + +Prefer debounce/coalescing around rapid cart edits so only the settled state is preloaded. + +## When to Invalidate + +Invalidate when the app should stop reusing the current preloaded checkout: + +- The preloaded checkout URL no longer represents the current cart. +- Buyer changes carts, accounts, shops, region, or currency. +- Cart contents are cleared or replaced. +- Checkout configuration changes and immediate re-preload is not appropriate. +- The app returns from checkout and wants the next checkout attempt to start from fresh cart state. +- The buyer signs out or privacy-sensitive state should be cleared. + +Do not rely on checkout dismissal alone to clear preloaded state unless the platform README explicitly says it does. + +## Platform Samples + +Read the platform file for the target app: + +- `references/swift.md` +- `references/android.md` +- `references/react-native.md` + +## Review Checklist + +- Presentation obtains or validates the latest checkout URL before opening checkout. +- Preload is triggered from buyer intent or settled cart state, not every low-level cart mutation. +- Preload is repeated after checkout-affecting changes. +- Invalidate is called on session/cart boundaries and stale-state risks. +- UI and navigation do not assume preload completed. +- Errors, queueing, cancellation, and completion paths remain correct without preload. diff --git a/skills/checkout-kit-present-preload-invalidate/references/react-native.md b/skills/checkout-kit-present-preload-invalidate/references/react-native.md new file mode 100644 index 00000000..5a86b981 --- /dev/null +++ b/skills/checkout-kit-present-preload-invalidate/references/react-native.md @@ -0,0 +1,66 @@ +# React Native + +Use this as the intended wrapper shape. Check the installed React Native package before copying names directly. + +```tsx +import { useEffect, useRef } from "react"; +import { + ShopifyCheckoutSheetProvider, + useShopifyCheckoutSheet, +} from "@shopify/checkout-kit"; +import { useDebounce } from "./useDebounce"; + +function AppWithCheckoutProvider() { + return ( + + + + ); +} + +function CartScreen({ + checkoutUrl, + buyerLikelyToCheckoutSoon, + cartOrBuyerChanged, + shopId, + customerId, + currencyCode, +}) { + const shopifyCheckout = useShopifyCheckoutSheet(); + const preloadedCheckoutUrlRef = useRef(null); + + useDebounce( + () => { + if (checkoutUrl && buyerLikelyToCheckoutSoon) { + shopifyCheckout.preload(checkoutUrl); + preloadedCheckoutUrlRef.current = checkoutUrl; + } + }, + [checkoutUrl, buyerLikelyToCheckoutSoon], + 300, + ); + + const onCheckoutTapped = () => { + if (!checkoutUrl) return; + shopifyCheckout.present(checkoutUrl); + }; + + useEffect(() => { + const preloadedCheckoutIsStale = + preloadedCheckoutUrlRef.current != null && + preloadedCheckoutUrlRef.current !== checkoutUrl; + + if (cartOrBuyerChanged && preloadedCheckoutIsStale) { + shopifyCheckout.invalidate(); + preloadedCheckoutUrlRef.current = null; + } + }, [cartOrBuyerChanged, checkoutUrl, shopifyCheckout]); + + useEffect(() => { + return () => { + shopifyCheckout.invalidate(); + preloadedCheckoutUrlRef.current = null; + }; + }, [shopId, customerId, currencyCode, shopifyCheckout]); +} +``` diff --git a/skills/checkout-kit-present-preload-invalidate/references/swift.md b/skills/checkout-kit-present-preload-invalidate/references/swift.md new file mode 100644 index 00000000..15451f15 --- /dev/null +++ b/skills/checkout-kit-present-preload-invalidate/references/swift.md @@ -0,0 +1,38 @@ +# Swift + +```swift +import ShopifyCheckoutKit +import UIKit + +private var preloadTask: Task? +private var preloadedCheckoutURL: URL? + +func onCartStateSettled(checkoutURL: URL) { + preloadTask?.cancel() + preloadTask = Task { @MainActor in + try? await Task.sleep(nanoseconds: 300_000_000) + ShopifyCheckoutKit.preload(checkout: checkoutURL) + preloadedCheckoutURL = checkoutURL + } +} + +func onCheckoutTapped(checkoutURL: URL, from viewController: UIViewController) { + ShopifyCheckoutKit.present(checkout: checkoutURL, from: viewController, delegate: checkoutDelegate) +} + +func onCheckoutAffectingStateChanged(freshCheckoutURL: URL, cartOrBuyerChanged: Bool) { + let preloadedCheckoutIsStale = preloadedCheckoutURL != nil && preloadedCheckoutURL != freshCheckoutURL + + if cartOrBuyerChanged && preloadedCheckoutIsStale { + ShopifyCheckoutKit.invalidate() + preloadedCheckoutURL = nil + } + + onCartStateSettled(checkoutURL: freshCheckoutURL) +} + +func onSessionBoundaryChanged() { + ShopifyCheckoutKit.invalidate() + preloadedCheckoutURL = nil +} +``` diff --git a/skills/checkout-sheet-kit-to-checkout-kit-migration/AGENTS.md b/skills/checkout-sheet-kit-to-checkout-kit-migration/AGENTS.md new file mode 100644 index 00000000..ae723875 --- /dev/null +++ b/skills/checkout-sheet-kit-to-checkout-kit-migration/AGENTS.md @@ -0,0 +1,3 @@ +# Checkout Sheet Kit to Checkout Kit Migration + +Use `SKILL.md` as the entrypoint for this skill. Read `references/guide.md` for the shared migration workflow. For lifecycle event rewrites, use `../checkout-kit-lifecycle-events/SKILL.md` and its target platform reference. diff --git a/skills/checkout-sheet-kit-to-checkout-kit-migration/SKILL.md b/skills/checkout-sheet-kit-to-checkout-kit-migration/SKILL.md new file mode 100644 index 00000000..e0b73a9b --- /dev/null +++ b/skills/checkout-sheet-kit-to-checkout-kit-migration/SKILL.md @@ -0,0 +1,22 @@ +--- +name: checkout-sheet-kit-to-checkout-kit-migration +description: Use when migrating an app from legacy Checkout Sheet Kit packages to Checkout Kit v1, including package renames, version reset, removed native web pixel relay, PII removal, and lifecycle/protocol changes. +--- + +# Checkout Sheet Kit to Checkout Kit Migration + +Use this skill when the user is upgrading from Checkout Sheet Kit to Checkout Kit, renaming packages/imports, or moving lifecycle handling from callback/event-processor code toward the protocol client. + +## Start with local truth + +Read these local files before suggesting code: + +- `README.md` for current package names, legacy version notes, and repo layout. +- The platform README for the app being migrated: `swift/README.md`, `android/README.md`, or `react-native/README.md`. +- `protocol/services/shopping/embedded.openrpc.json` and `protocol/schemas/` if lifecycle event migration is in scope. +- Existing protocol client implementations when available. +- `references/guide.md` for the migration workflow, related skills, and guardrails. +- The platform rename sample for the target app: `references/swift.md`, `references/android.md`, or `references/react-native.md`. +- `../checkout-kit-lifecycle-events/SKILL.md` when migrating lifecycle event handlers or protocol notifications. + +Prefer local source over memory. Use Shopify docs only to confirm current public guidance: https://shopify.dev/docs/storefronts/mobile diff --git a/skills/checkout-sheet-kit-to-checkout-kit-migration/references/android.md b/skills/checkout-sheet-kit-to-checkout-kit-migration/references/android.md new file mode 100644 index 00000000..e9fccc81 --- /dev/null +++ b/skills/checkout-sheet-kit-to-checkout-kit-migration/references/android.md @@ -0,0 +1,8 @@ +# Android + +```kotlin +// Rename dependency coordinates from: +// implementation("com.shopify:checkout-sheet-kit:3.5.x") + +implementation("com.shopify:checkout-kit:") +``` diff --git a/skills/checkout-sheet-kit-to-checkout-kit-migration/references/guide.md b/skills/checkout-sheet-kit-to-checkout-kit-migration/references/guide.md new file mode 100644 index 00000000..7ec34896 --- /dev/null +++ b/skills/checkout-sheet-kit-to-checkout-kit-migration/references/guide.md @@ -0,0 +1,46 @@ +# Migration Guide + +## Version Reset + +Checkout Kit is a renamed and reset release line, not the next major version of Checkout Sheet Kit. The legacy Checkout Sheet Kit packages stop on their existing major-version lines: + +- Checkout Sheet Kit for Swift ends at `v3`. +- Checkout Sheet Kit for Android ends at `v3`. +- Checkout Sheet Kit for React Native ends at `v4`, the New Architecture release line. + +From that point forward, all three platforms move to the new Checkout Kit package names and reset to `v1`. The package names remove `Sheet`, and the first Checkout Kit release should be treated as Checkout Kit `v1`, not Checkout Sheet Kit `v4` or `v5`. + +## Migration Workflow + +1. Identify the current integration: + - Package coordinate or module import. + - Checkout presentation path. + - Preload and invalidate usage. + - Event handlers for completion, lifecycle, external links, buyer/payment/line-item changes, and app-owned analytics. +2. Rename legacy dependencies and imports to Checkout Kit package names. +3. Keep presentation behavior functionally equivalent before changing lifecycle handling. +4. Use the `checkout-kit-lifecycle-events` skill to replace broad event-handler logic with protocol notification handlers where the new protocol exposes a typed equivalent. +5. Preserve app-owned side effects: navigation, confirmation screens, app-owned analytics, error UI, external URL handling, and cart refreshes. +6. Re-test checkout completion, cancellation, external links, buyer identity, payment changes, and cart changes. + +## Feature Changes + +- Checkout Kit moves from `MobileCheckoutSdkProtocol` to the UCP-backed Embedded Checkout Protocol. +- Web pixel events are no longer relayed to the native layer. +- Event payloads should not expose personally identifiable information. +- Authenticated checkout capabilities require the documented access scope where supported. +- Universal checkout and web iframe support are separate capabilities; do not assume they are available from the legacy mobile SDK behavior. + +## Related Skills + +- `../checkout-kit-lifecycle-events/SKILL.md` for lifecycle event and protocol notification handling. +- `../checkout-kit-present-preload-invalidate/SKILL.md` for preload, present, and invalidate behavior. + +## Guardrails + +- Treat the protocol schema as the contract and generated platform types as convenience wrappers. +- Keep old event handlers only when the platform still requires them for compatibility or for behavior not yet covered by protocol notifications. +- Do not keep references to Checkout Sheet Kit package names unless documenting legacy support. +- Do not migrate web pixel or analytics event collection to native lifecycle events. Web pixel relay to the native layer was removed. +- Do not preserve assumptions that event payloads contain PII. +- Keep preload/invalidate changes separate from callback-to-protocol migration unless the user asked for both. diff --git a/skills/checkout-sheet-kit-to-checkout-kit-migration/references/react-native.md b/skills/checkout-sheet-kit-to-checkout-kit-migration/references/react-native.md new file mode 100644 index 00000000..90e2957b --- /dev/null +++ b/skills/checkout-sheet-kit-to-checkout-kit-migration/references/react-native.md @@ -0,0 +1,16 @@ +# React Native + +```tsx +// Rename package imports from: +// import {useShopifyCheckoutSheet} from '@shopify/checkout-sheet-kit'; + +import {useShopifyCheckoutSheet} from '@shopify/checkout-kit'; +``` + +```json +{ + "dependencies": { + "@shopify/checkout-kit": "" + } +} +``` diff --git a/skills/checkout-sheet-kit-to-checkout-kit-migration/references/swift.md b/skills/checkout-sheet-kit-to-checkout-kit-migration/references/swift.md new file mode 100644 index 00000000..0068eef3 --- /dev/null +++ b/skills/checkout-sheet-kit-to-checkout-kit-migration/references/swift.md @@ -0,0 +1,15 @@ +# Swift + +```swift +// Rename imports from: +// import ShopifyCheckoutSheetKit + +import ShopifyCheckoutKit +``` + +```swift +// Rename package product references from: +// .product(name: "ShopifyCheckoutSheetKit", package: "checkout-sheet-kit-swift") + +.product(name: "ShopifyCheckoutKit", package: "checkout-kit") +```