<!-- Stacklift documentation: "Store releases". Source: https://stacklift.joynul.com/docs/store-releases · All pages for LLMs: https://stacklift.joynul.com/llms-full.txt -->

> About Stacklift: Stacklift is a hosted platform with source-available SDKs for shipping app releases and over-the-air updates. It works for mobile (React Native, Expo, Flutter, native iOS and Android, Kotlin Multiplatform, .NET MAUI, Unity), web, desktop (Electron, .NET, Java) and backend apps. Developers create releases with the `stacklift` CLI or the dashboard; the server verifies and signs every artifact (SHA-256 + Ed25519), deploys releases to channels with staged rollouts and rollback, and app SDKs check, download and verify updates. Native apps can change screens over the air with server-driven UI layouts and logic with sandboxed scripts, within App Store and Google Play rules. Apps never depend on Stacklift to keep working: everything has a built-in fallback and an exit path.
>
> This page: Track App Store and Google Play builds next to your over-the-air releases.

# Store releases (App Store, Google Play and friends)

When your app ships through a store, **the store hosts the binary** — Stacklift doesn't, and you don't upload anything to Stacklift. The CLI records the build; you submit it to the store with whatever you already use.

## The flow

```bash
# 1. Build as usual
flutter build appbundle && flutter build ipa

# 2. Record the build in Stacklift. Version, build number and app id are read from the built files.
stacklift release create \
  --native android:build/app/outputs/bundle/release/app-release.aab \
  --native ios:build/ios/ipa/Runner.ipa

# 3. Upload to Google Play / App Store Connect with your usual tool (Fastlane, Xcode, Play Console …)

# 4. Tell Stacklift where it is. Optional, but it's what the dashboard shows.
stacklift store status 1.4.2 ios in-review
stacklift store status 1.4.2 ios released
```

Nothing is uploaded in step 2: the CLI hashes the file locally and sends the name, size, checksum, version, build number, git commit and CI link. The release is `READY` immediately.

## What is read from the built binary

For an `.ipa` or `.aab` the CLI opens the finished file and reads the numbers the store will actually see: `Info.plist` inside the IPA (binary or XML), and the compiled `AndroidManifest.xml` inside the AAB (`package`, `versionName`, `versionCode`). Only that one small entry is read — never the whole archive — and nothing in it is executed. This wins over the project files, because the project can change between the build and the release. If the two disagree you get a warning ("The built binary is 1.4.2 but the project files say 9.9.9"); if `--version` contradicts the binary you are told the store will show the binary's version.

If both an IPA and an AAB are given and their versions differ, you get a warning and the most common one is used. Build numbers stay per platform.

`.apk` and other formats (MSIX, DMG, EXE …) are not opened; for those the project files below are used.

## What is read from your project

When there is no readable binary (or for hosted artifacts), the CLI reads the version from the files your build already uses, and says where each came from:

| Stack | Version / build number | App id |
| --- | --- | --- |
| Flutter | `pubspec.yaml` (`version: 1.4.2+37`) | `applicationId` in Gradle, `PRODUCT_BUNDLE_IDENTIFIER` in Xcode |
| React Native, Capacitor, NativeScript, KMP | Native files win: Gradle `versionName`/`versionCode`, Xcode `MARKETING_VERSION`/`CURRENT_PROJECT_VERSION`; `package.json` is the fallback | same |
| Native Android / iOS / macOS | Gradle / Xcode project | same |
| Expo | `app.json` (`expo.version`, `ios.buildNumber`, `android.versionCode`) | `bundleIdentifier`, `package` |
| .NET MAUI / WPF / WinUI | `.csproj` (`ApplicationDisplayVersion`, `ApplicationVersion`), `Package.appxmanifest` | `ApplicationId`, MSIX identity |
| Unity | `ProjectSettings.asset` | per-platform identifier |
| Electron / Tauri / Compose Desktop | `package.json` / `tauri.conf.json` / `packageVersion` | `build.appId` / `identifier` |

Only **literal** values are used. A Gradle property or an Xcode `$(MARKETING_VERSION)` is a build-time indirection, so it's reported ("not a literal, so it was not read") instead of guessed. If your iOS and Android versions disagree, you get a warning and the most common one is used; pass `--version` to choose. Build numbers stay per platform, so a Play `versionCode` of 30 and an App Store build of 31 are both kept.

Override anything with `--version`, `--build-number` or `--runtime-version`. For a store-only release `runtimeVersion` defaults to the version, since nothing is delivered to a runtime.

## Store links

Set them once; they show on the project and on every release.

```bash
stacklift store link ios https://apps.apple.com/us/app/glyph/id6740000000
```

or in `stacklift.yaml` (synced on `release create`, best effort: a CI token without `project:update` just skips it):

```yaml
stores:
  ios: https://apps.apple.com/us/app/glyph/id6740000000
  android: https://play.google.com/store/apps/details?id=com.shokal.glyphwidget
```

The **Google Play** link is derived from your package name when you don't set one, and is shown as *derived*: it's where the listing will live, not proof it exists yet. The **App Store** link can't be derived (it needs Apple's numeric id), so add it once.

Links must be `https` and on the store's own host (`apps.apple.com`, `play.google.com`, `apps.microsoft.com`, …). Anything else — `javascript:`, `http:`, look-alike hosts, URLs with credentials — is rejected, because these render as hyperlinks.

## Store status

`built → submitted → in_review → released` (or `rejected`, `removed`). Stacklift has **no access to the stores**, so this is what you tell it, with `stacklift store status`, the dashboard's selector, or `--store-status` on `release create`. `release create` sets `built` for you and never overwrites a status someone already recorded.

## Devices and installs

If your app embeds a Stacklift SDK and calls `check` with its `currentVersion`, Stacklift knows which devices run which build — whatever delivered it:

```swift
let manifest = try await client.check(CheckRequest(channel: "production", runtimeVersion: "1.4.2", currentVersion: "1.4.2", deviceId: DeviceIdentity.getOrCreate()))
// no OTA deployed? you get { updateAvailable: false, reason: "nothing_deployed" } and the check-in is still counted
```

The release page then shows **active devices on this version in the last 30 days**, per platform: a device counts toward the newest version it last reported, so it leaves the old release's count when it updates. Device ids are random, per install and hashed with the project id; Stacklift keeps no hardware or advertising ids.

## What Stacklift can't do

- **Upload to the stores.** Use Fastlane, Xcode, `bundletool`, the Play Console API.
- **See store download counts, ratings or review state.** Those need the App Store Connect and Google Play Developer APIs. Integrations for them are **planned, not built**. Until then "downloads" means OTA downloads, and "devices" means devices that checked in through the SDK — a fraction of your store installs if the SDK isn't in every build.
- **Verify the store build.** The checksum is whatever your CLI declared; Stacklift never sees the bytes, and labels it that way.
- **Deploy a store build to a channel.** Store builds are never delivered to devices, so a release made only of them can't be deployed (the CLI skips `--channel`, the API refuses with an explanation).

## Mixed releases

A React Native, Expo or Capacitor release can carry an OTA bundle *and* its store build. The bundle is hosted, verified, signed and deployable; the store build is recorded:

```bash
stacklift release create --runtime-version 2.3.0 \
  --artifact ios:js-bundle:dist/ios.zip --artifact android:js-bundle:dist/android.zip \
  --native ios:build/App.ipa --native android:build/app-release.aab \
  --channel staging
```

## In CI

```yaml
- run: flutter build appbundle && flutter build ipa
- run: |
    stacklift release create \
      --native android:build/app/outputs/bundle/release/app-release.aab \
      --native ios:build/ios/ipa/Runner.ipa
  env: { STACKLIFT_TOKEN: ${{ secrets.STACKLIFT_TOKEN }} }
```

On GitHub Actions, GitLab CI, CircleCI and Bitrise the release links back to its pipeline run. Only those well-known variables are read — never the rest of the environment.
