Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 87 additions & 0 deletions .claude/skills/ios-storekit-purchase/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
---
name: ios-storekit-purchase
description: Use when a run on the iOS simulator has to get through a StoreKit purchase — the local StoreKit configuration, the purchase sheet and the alerts after it, which log line means which window is up and where its button is — for any app; the SDK harness is the usual one
---

# StoreKit purchases on the iOS simulator

A purchase on the simulator is local only while Xcode's StoreKit configuration is active for the
app: Xcode syncs the `.storekit` file selected in the scheme's Run options into the simulator when
it launches the app, and `storekitd` then serves the products itself. Nothing else performs that
sync — `xcodebuild` ignores the scheme option, and an `SKTestSession` opened from the app is
refused as not entitled — so the app has to be launched by Xcode. Without the configuration every
purchase goes to the App Store sandbox and asks for an Apple Account. (`Assets/SdkHarness/AGENTS.md`
is how this repository's harness gets the configuration and the launch.)

With it active, every purchase goes through three system windows, each needing a tap. They always
sit at the same place, and each one writes a line to the simulator's log, so nothing has to be
looked at: start the purchase, wait for the line, tap, repeat. The taps come from the simulator
control tool; the waits are shell.

## The three windows and their log lines

Everything is read with `xcrun simctl spawn <udid> log show --start <t0> --predicate …`. One
`t0` per purchase, taken before the purchase is sent: a wait that takes its own start time after a
tap misses the line the tap produced a second earlier.

| window | log line that means it is on screen | tap |
|---|---|---|
| purchase sheet "Xcode · <product> · Subscribe" | `process == "PassbookUIService" AND subsystem == "com.apple.passkit" AND category == "Analytics" AND eventMessage CONTAINS "inApp"` — the sheet is hosted by `PassbookUIService`, and this line is written once the product is rendered | Subscribe |
| alert "You’re all set." | `process == "SpringBoard" AND category == "AlertItems" AND eventMessage CONTAINS "Received request to activate alertItem"`, `title:` in the same line | OK (full width) |
| alert "You’re currently subscribed to this." | same line, different title — the product is already active, no sheet is shown | OK (right of Manage) |
| alert closed | same category, `eventMessage CONTAINS "Deactivated alertItem"` | — |

The purchase completes only after the alert's OK: `storekitd` logs `AMSPurchaseTask … ===
Finished ===` at that tap, not at Subscribe. So whatever started the purchase has to keep waiting
with a long budget, and its result is read after the third window.

## Where the buttons are

All three windows are system UI, laid out by iOS from the screen size in points (W×H) and the
safe area, so the taps follow from the size rather than from a table. W and H are the screenshot's
pixel size over 3 (every iPhone simulator is 3×); C = (H + 25) / 2 is the middle of the safe area
on a Dynamic Island phone (59 pt above, 34 below):

| button | x | y | why |
|---|---|---|---|
| Subscribe | W / 2 | H − 55 | pinned to the bottom of the sheet |
| OK on "You’re all set." | W / 2 | C + 57 | the alert is centred in the safe area, its text never changes, its width is fixed |
| OK on "You’re currently subscribed to this." | W / 2 + 74 | C + 99 | longer text, two buttons side by side; Manage is at W / 2 − 74 |

Verified on iPhone 17 Pro (402×874: 201×819, 201×506, 275×548) and iPhone 17 Pro Max (440×956:
220×901, 220×547, 294×589) — every measured button within 1 pt of the formula. On iPhone 17e
(390×844) only Subscribe (195×789) was measured; its alerts were not, so the 25 in C is a
Dynamic-Island figure that the 17e has not confirmed. iPad is out: the sheet and the alerts are
laid out differently.

## Running it

```bash
UDID=<the simulator Xcode launched the app on>
T0=$(date '+%Y-%m-%d %H:%M:%S') # one t0 for the whole purchase
# start the purchase in the background with a long budget — on the harness:
# unity command harness_call --runtime-path "$APP" --method MakePurchase --args '{"product":"$GetPaywallProducts[0]"}' --timeout_ms 90000 --timeout 120 > /tmp/purchase.json &
# wait for a window: the first line after T0 matching the sheet or an alert (title in the line if it is an alert)
until L=$(xcrun simctl spawn $UDID log show --start "$T0" --predicate '(process == "PassbookUIService" AND subsystem == "com.apple.passkit" AND category == "Analytics" AND eventMessage CONTAINS "inApp") OR (process == "SpringBoard" AND category == "AlertItems" AND eventMessage CONTAINS "Received request to activate alertItem")' --style compact | grep -v '^Timestamp' | head -1) && [[ -n "$L" ]]; do sleep 1; done; echo "$L" | grep -o 'title: [^;]*' || echo sheet
# tap Subscribe (or the button the title calls for), then wait the same way for the alert line, tap its OK,
# then wait for `eventMessage CONTAINS "Deactivated alertItem"`; only after that does the purchase return.
```

A whole purchase is about 25 s wall-clock, nearly all of it the turns between commands and taps;
the sheet itself is logged in the same second the purchase is sent.

## What the store remembers

Transactions live in the simulator's `storekitd`, not in the app: reinstalling the app keeps
them, so a second purchase of an active subscription gets the "currently subscribed" alert (and
still returns success), and a different product in the same group is queued to start when the
current one expires — the profile keeps showing the old product, which is StoreKit doing its job.
Clearing them takes Xcode's Debug ▸ StoreKit ▸ Manage Transactions, or erasing the simulator.

## When a sign-in window appears

"Sign in to Apple Account" (fields, Cancel/OK) is also an `SBUserNotificationAlert`, so the wait
reports it by title. Tap Cancel (W / 2 − 74, above the keyboard) and stop: never type anything
into it. It means the purchase went to the App Store sandbox, i.e. the local configuration is not
active — the app was launched by something other than Xcode (`xcodebuild`, `simctl launch`), or
the scheme lost its `StoreKitConfigurationFileReference`. Fix the launch; do not press on.
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -147,3 +147,4 @@ tests/**/*.received.txt
# iOS player output of the demo build scripts
ios-sim-build/
ios-stripped-build/
ios-harness-build/
6 changes: 4 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,16 +11,18 @@ Adapty Unity SDK — a C# wrapper around native [Adapty iOS SDK](https://github.

This is a **Unity project** (Unity 6000.x) — the player is built and tested through the Unity Editor. The JSON layer is the exception: `tests/` links the SDK sources into a plain .NET project, so it needs neither the Editor nor a licence.

The package declares **Unity 2022.3 and newer** as `unity` in `package.json`, and that floor is what Editor-facing code may assume: `AdaptyDependencies` uses `Client.AddAndRemove` and `PackageInfo.FindForAssembly`, neither of which exists all the way back (`AddAndRemove` arrived after 2020.3).
The package declares **Unity 6.0 (6000.0) and newer** as `unity` in `package.json` — raised from 2022.3 on 2026-09-01 so the package may use UI Toolkit runtime bindings (2023.2+) for the Editor mock UI — and that floor is what all package code may assume. Demo-only code under `Assets/` may go further (the project itself runs 6.6).

The install path is verified on the floor — `.unitypackage` import into a clean project, then `Adapty SDK > Install Dependencies`, then a compile, all on 2022.3.62f3. Everything else runs on Unity 6. Keep the changelog and `MIGRATION-v3.17-to-v4.1.md` wording matching that split; do not widen it to claim device or build coverage on 2022.3. One trap when re-verifying: recent 2022.3 builds are Extended LTS and refuse to launch without an Industry or Enterprise licence, so pick a build below that cutoff (62f3 works).
The floor raise is unreleased: 4.1.x shipped on 2022.3, and its install path — `.unitypackage` import into a clean project, then `Adapty SDK > Install Dependencies`, then a compile — was verified on 2022.3.62f3. Before the release that carries the raise, verify that path on a 6000.0.x build and say so in the changelog entry (there is one under Unreleased); do not widen it to claim device or build coverage on 6000.0. `MIGRATION-v3.17-to-v4.1.md` describes 4.1 as it shipped and is not edited for later floors.

**Run the JSON layer tests:**
```bash
dotnet test tests/AdaptySDK.NextTests/AdaptySDK.NextTests.csproj
```
The layer branches on `UNITY_IOS` / `UNITY_ANDROID` and each platform has its own approved snapshots, so a change to it has to pass all four legs: add `-p:AdaptyPlatform=UNITY_IOS` or `-p:AdaptyPlatform=UNITY_ANDROID` for two of the others. Asking for no platform means `UNITY_EDITOR`, which the projects default to — the Editor is a configuration of its own and has to say so, since it is what selects the no-op bridge; an empty define set is a state Unity never produces. The fourth is `-p:AdaptyPlatform="UNITY_IOS%3BADAPTY_KIDS_MODE"` — `%3B` escapes the `;` inside the MSBuild property value. Kids Mode is the only shipped define that changes the wire format rather than which sources compile, and its whole visible effect here is the forced `apple_idfa_collection_disabled`: three configuration requests have a second approved form under `-kids`, and `RequestParityTests.Configured` is what picks it. Nothing else in the layer moves with the define — if a fourth snapshot ever needs a `-kids` form, that is a change in blast radius worth understanding before approving it. `ADAPTY_UPDATE_SNAPSHOTS=1` rewrites the approved files instead of failing. CI runs the same matrix in `.github/workflows/json-layer-tests.yml`.

**Drive the real SDK on the iOS simulator:** `Assets/SdkHarness/` is a player the agent runs from the command line against the native SDK — build, launch, StoreKit and the command set are in [Assets/SdkHarness/AGENTS.md](Assets/SdkHarness/AGENTS.md); a purchase's system windows are handled by the `ios-storekit-purchase` skill.

**Build .unitypackage for distribution:**
```bash
cd deploy && ./build_unitypackage.sh # export into deploy/output/
Expand Down
8 changes: 8 additions & 0 deletions Assets/SdkHarness.meta

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

30 changes: 30 additions & 0 deletions Assets/SdkHarness/AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# The SDK harness

`Assets/SdkHarness/` is a scene with nothing in it but a `RuntimePipelineManager` (port pinned to 7900) and `AdaptySdkHarness`, which registers four `[CliCommand]`s in the player: `harness_activate`, `harness_call` (any public static `Adapty` or `AdaptyUI` method by name, arguments as a JSON object keyed by parameter name, the overload chosen by exactly that key set — an argument written as `"$GetFlow"` or `"$GetPaywallProducts[0]"` is the object the last successful call of that method handed back, which is how a flow reaches `GetPaywallProducts` and a product reaches `MakePurchase`; do not paste a returned model's JSON back instead, the SDK never reads a response model from JSON — a product goes out as `AdaptyPaywallProductRequest`, its own shape — so the dump has no reader and fails on the subscription offer while proving nothing), `harness_events` (what the listeners received, decoded), `harness_status`. It exists because the desktop suite feeds the SDK fixtures, and only a player can say whether the C# layer decodes what the *native* SDK actually returns, on IL2CPP, after stripping — which is why the harness build adds a link.xml of its own (`SdkHarnessBuild`, not a file under `Assets/`, which would go into the demo's and `StrippingBuild`'s players too) that keeps only what the harness reaches by reflection — `Adapty`'s and `AdaptyUI`'s methods, `AdaptyJson`, the request-side types it builds from JSON or by member name — and leaves the response models and converters to the linker; a new request-side parameter type goes on that list. A callback with a value-type payload (`bool`, an enum) needs no AOT hint: IL2CPP's full generic sharing runs the `Capture<T>` the harness makes at run time. Commands run on the request thread and post the call to the main one, because the SDK delivers callbacks through `SynchronizationContext.Post` and a main-thread wait would deadlock every call; the wait budget (`--timeout_ms`, 20 s by default) stays under the scene's 120 s request timeout; the first calls after an activation with a customer id have taken 8–20 s while the backend merged the profile, so give those more. It does not expose the raw bridge JSON — the request/response bytes live inside `AdaptyRequest` — only what the SDK decoded. It activates once per process: relaunch the app for another activation. The scenario is data, not code, so a new test is a new payload and needs no rebuild. The screen is not empty for the person watching: a UI Toolkit ledger built in code (the only asset is `SdkHarnessPanel.asset` with its `unity-theme://default` theme) lists every request (→), reply (←), failure (×), late reply (← or × with "late" — the command already returned as timed out; the object still becomes the handle) and delivered event («) with its timestamp, so a run can be followed on the simulator and read back when the agent is stuck.

## Build and run

Build it with its own `harness_build` command (`Assets/SdkHarness/Editor/`), not `unity command build`: the CLI sends a single `--scenes` value as a string, the server binds that to an empty array and silently builds `EditorBuildSettings` instead, and `dry_run` reports a nonexistent scene as valid. A player build holds the main thread for minutes, so submit it detached and wait on the job:
```bash
unity command harness_build --detach # scenes = Assets/SdkHarness/SdkHarness.unity, iOS, Development, SimulatorSDK
unity job wait <job-id> --timeout 1500
xcrun simctl uninstall <udid> com.adapty.adaptydemoapp # or the previous install's descriptor passes for readiness
osascript -e 'tell application "Xcode"
set ws to open "'"$PWD"'/ios-harness-build/Unity-iPhone.xcworkspace"
repeat until loaded of ws
delay 1
end repeat
set active scheme of ws to (first scheme of ws whose name is "Unity-iPhone")
set active run destination of ws to (first run destination of ws whose name is "iPhone 17 Pro (26.5)")
run ws
end tell'
APP=$(xcrun simctl get_app_container <udid> com.adapty.adaptydemoapp app) # --runtime-path takes this DIRECTORY, not the descriptor file inside it
unity command harness_activate --runtime-path "$APP"
unity command harness_call --runtime-path "$APP" --method GetFlow --args '{"placementId":"rt.RegTestPaywall1","fetchPolicy":"Default","loadTimeout":10}'
```

Open the **workspace**: External Dependency Manager writes a Podfile, and the bare `.xcodeproj` fails at link with `framework 'Pods_UnityFramework' not found`. Xcode runs it, not `xcodebuild`, because of purchases: `harness_build` files `Assets/SdkHarness/AdaptyDemo.storekit` in the project (as `text`, with no target membership — Xcode offers nothing else as a configuration) and selects it in the scheme's Run options, and Xcode syncs that configuration into the simulator through its Instruments service when it launches the app, so `storekitd` serves the products locally and `MakePurchase` raises Xcode's confirmation sheet instead of the Apple Account sign-in. Nothing else performs that sync: `xcodebuild` (build or test) ignores the scheme option, and an `SKTestSession` opened from the app, or from an `xcodebuild test` host, is refused by `storekitd` as not entitled. Xcode names its destination by device and runtime (`iPhone 17 Pro (26.5)`) and boots that simulator even when another one is up, so address the device by UDID (`xcrun simctl list devices`) rather than `booted`. The sheet and the "You're all set" alert after it take a tap each; the `ios-storekit-purchase` skill (`.claude/skills/ios-storekit-purchase/`) says which log line means which window is up and where its button is, so a purchase needs no screenshot. On the harness that is: `harness_activate`, `GetFlow` and `GetPaywallProducts` first, then `harness_call --method MakePurchase --args '{"product":"$GetPaywallProducts[0]"}' --timeout_ms 90000` in the background — it returns only after the alert's OK — and `GetProfile` to see the access level. The descriptor with the port and token appears next to the app's `Data/` once the server is up, which makes its existence the readiness signal.

## What the commands can and cannot take

Some argument shapes have no JSON reader in the SDK and get one in the harness: a type whose instances are public static members (`AdaptyPlacementFetchPolicy`, `AdaptyExternalAttributionProvider`) is addressed by member name, and a string for a type with a one-string constructor becomes that instance (a provider by identifier); a `TimeSpan` parameter is taken as seconds (inside an object it is Newtonsoft's `"00:00:10"`); enums go through the SDK's own converter as strings; a request-only model with a nested `Builder` (`AdaptyProfileParameters`, `AdaptyConfiguration`) is built from a JSON object — constructor arguments by parameter name, every other key a `Set<Key>` call, `customAttributes` an object of string or number values — so `UpdateProfile` takes `{"param":{"firstName":"A","customAttributes":{"plan":"pro","score":3}}}`. Models with public fields and a parameterless constructor (`AdaptyUICreateFlowViewParameters`, `AdaptyUIDialogConfiguration`, `AdaptyPurchaseParameters`) read as plain JSON. Not reachable this way: `AdaptyCustomAsset` values (factory methods, no members), custom tags and timers on `CreateFlowView` (setters, not fields), `SetFallback` (needs a file in the app), and the legacy onboarding events (`IAdaptyOnboardingsEventsListener` is obsolete; the harness does not register it). `Activate` is refused by `harness_call` because activation is once per process — `harness_activate` builds the configuration, with `--configuration` for the Builder keys it has no flag for. Only iOS: `harness_build` targets the simulator SDK, an Android build is not written. The player's own command set adds `console`, `runtime_status`, `simulate_pointer`; `eval` is registered there but compiled out on anything that is not the Editor or a standalone development build, which is why the harness's commands are compiled ones. Nothing here runs on a real device without a package change: the runtime server writes its descriptor into the app bundle and stops itself when that write fails.
7 changes: 7 additions & 0 deletions Assets/SdkHarness/AGENTS.md.meta

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

File renamed without changes.
7 changes: 7 additions & 0 deletions Assets/SdkHarness/AdaptyDemo.storekit.meta

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading