nkbmusic/docs/app-store-release.md

# Releasing Nanga Kathai to Google Play and the App Store

| | Android | iOS |
|---|---|---|
| App ID | `com.metatroncubesolutions.nanga_kathai` | `com.metatroncubesolutions.nangaKathai` |
| Built by | Codemagic (`android-release`) or locally | Codemagic (`ios-release`) |
| First stop | Play Console, Internal testing | TestFlight |

The version comes from `pubspec.yaml` (`version: 1.0.0+1`). Raise the first part (1.0.1, 1.1.0…) for
each store release. Build numbers are set automatically by Codemagic.

## 1. Accounts (one-time)

- **Apple Developer Program** (US$99 a year), enrolled as an organisation. This needs a D-U-N-S
  number for Metatroncube Software Solutions.
- **Google Play Console** (US$25 once), as an organisation account. A *personal* account must run
  a closed test with at least 12 testers for 14 days before it can publish, so use an organisation account.
- **Codemagic**, signed in with GitHub, with the `metatroncubeswdev/nkbmusic_app` repo added.

## 2. Codemagic setup (one-time)

1. **Variables.** Open App settings > Environment variables and create the group **`nk_app`** with:
   - `SUPABASE_URL` = `https://app.nkbmusic.com`
   - `SUPABASE_PUBLISHABLE_KEY` = the value from your local `env.json`
   - `MEDIA_BASE_URL` = `https://app.nkbmusic.com/storage/v1/object/public/audio`
2. **App Store Connect API key.**
   - In App Store Connect, open Users and Access > Integrations > App Store Connect API and generate a key with the **App Manager** role.
   - In Codemagic, open Team settings > Team integrations > Developer Portal and add the key with the name **`clickstocart-app`** (already added; it works for every app in the Apple team).
3. **iOS signing (automatic).** The build creates the Apple Distribution certificate and the App
   Store profile itself through the API key, so no profiles are made by hand.
   - Create a variable group **`nk_ios_signing`** with `CERTIFICATE_PRIVATE_KEY_BASE64` (secure).
   - Its value is the one line in `C:\Users\manes\nk-keys\ios_distribution_private_key.base64.txt`.
   - The API key needs the **Admin** role, or App Manager with access to Certificates, Identifiers & Profiles.
   - Apple allows only a few distribution certificates per team. If the limit is reached, revoke an unused one on developer.apple.com.
4. **Android signing.** On the same page, under Android keystores, upload
   `C:\Users\manes\nk-keys\nk-upload.jks` with the reference name **`nk_upload_keystore`**,
   alias `upload`. The password is in `C:\Users\manes\nk-keys\key.properties.backup`.
5. **Google Play publishing (optional).**
   - Create a Google Cloud service account, invite it in Play Console > Users and permissions with release rights, and download its JSON key.
   - Store the key as `GCLOUD_SERVICE_ACCOUNT_CREDENTIALS` (secure) in a variable group **`nk_google_play`**.

## 3. iOS: first release

1. On developer.apple.com, open Identifiers and register the App ID
   `com.metatroncubesolutions.nangaKathai`. In-App Purchase is on by default. Background audio
   needs nothing extra.
2. In App Store Connect, create the app with the name **Nanga Kathai**, that bundle ID, and primary language English (India or UK).
3. In Codemagic, start the **iOS release (TestFlight)** workflow, or push a tag:
   `git tag v1.0.0 && git push github v1.0.0`.
   The build is uploaded to TestFlight automatically after about 20–30 minutes plus Apple processing.
4. Test it from the TestFlight app on an iPhone.
5. Fill in the listing (section 5) and submit for review.

## 4. Android: first release

1. In Play Console, create the app: Nanga Kathai, App, Free.
2. Build the first bundle locally and upload it manually. Google requires the very first upload to be done by hand.
   ```
   flutter build appbundle --release --dart-define-from-file=env.json
   ```
   The file is `build/app/outputs/bundle/release/app-release.aab`. Upload it under Testing >
   Internal testing > Create release. Accept **Play App Signing**: Google keeps the app signing key,
   and you sign uploads with `nk-upload.jks`.
3. Later builds come from the Codemagic **Android release** workflow, which uploads a draft to Internal testing.
4. Promote it from Internal testing, to Closed testing (optional), to Production.

## 5. Store listing checklist

**Links (publish the files from `site/` on nkbmusic.com first)**
- Privacy Policy: `https://nkbmusic.com/privacy`
- Terms: `https://nkbmusic.com/terms`
- Account deletion (required by Play): `https://nkbmusic.com/delete-account`
- Support: `support@nkbmusic.com`

**Graphics** (in `assets/brand/`: `app_icon_1024.png` and `play_store_icon_512.png`)
- Play: a 512×512 icon, a 1024×500 feature graphic, and 2–8 phone screenshots.
- App Store: 6.9-inch iPhone screenshots (1320×2868). The app is iPhone-only, so no iPad screenshots are needed.

**Questionnaires**
- **Data collected** (Play Data safety and Apple App Privacy):
  - email, name, optional phone and photo;
  - app interactions (plays) and crash/diagnostics data if crash reporting is added;
  - not used for tracking or ads, data encrypted in transit, users can request deletion.
- **Content rating:** music app, no violence and no user chat. Expect *Everyone* / *4+*.
- **Ads:** none. **In-app purchases:** yes (the Support products in `docs/support-payments.md`).

**App Review notes (important)**
- Create a reviewer account (for example `review@nkbmusic.com`) with a password, and enter it as the sign-in details. Apple and Google can't receive the email code.
- **Music rights** are the most likely reason for a rejection (Apple guideline 5.2.3 and Google's IP
  policy). Explain it in the notes: *"Nanga Kathai preserves Badaga community music from a family
  collection. Every song has an in-app 'Is this your song?' claim or removal option, and we act on
  requests promptly. New songs will come only from verified creators who confirm their rights."*
  Keep written permission from any singers you can reach, in case review asks.

## 6. Keys: back these up now

`C:\Users\manes\nk-keys\` holds the Android upload key and its password. Copy that folder to
two safe places, such as a password manager and an offline drive. If it is lost, Google can reset
the upload key, but that takes a support request and several days. Never commit it to git.