# Build your mobile app

Every organization publishes the Open Core HR employee app under its own name. CZ App Studio does not publish an app for your installation; the app in the stores is a demo.

You generate your app's source from your CZ App Studio account. It arrives as a ready-to-build Flutter project with your name, icon, colour, server address and the add-ons on your licence. You build it, sign it with your own keys and publish it with your own developer accounts.

Prefer not to do this yourself? Every [installation plan](https://czappstudio.com/installation) includes a branded Android build; Premium and Complete also include the iOS build and store submission.

## Generate the app source

1. Sign in to your CZ App Studio account and open **Your products**.
2. Choose **Manage licence** on your Open Core HR Core licence, then **Mobile app**.
3. Fill in the app details:
   - **App name**, shown under the icon (up to 30 characters).
   - **Android application ID** and **iOS bundle ID**, based on your own domain, for example `com.yourcompany.hr`. They cannot change after you publish.
   - **Brand colour** for buttons and highlights.
   - **Server address**, for example `https://hr.yourcompany.com`. It is filled in from your activated installation.
   - **App icon**: a square PNG or JPEG of at least 1024 × 1024 pixels, without rounded corners.
   - Optionally a **Logo** for the splash and sign-in screens, and a light **Logo for dark mode**.
4. Under **Versions**, choose the installation to match. The app then contains exactly the Core and add-on versions that server runs. Choose **Newest releases my licence covers** before your server is installed.
5. Under **Included in the app**, untick any add-on whose screens you want to leave out. Add-ons attached to your Core licence are included automatically; Calls needs Chat.
6. Choose **Save and generate app source**. After about a minute the page shows **Ready**; choose **Download**. Each download stays available for 14 days.

Only the owner of the licence can generate the source, and only for the Core and add-ons that licence covers.

## What the project contains

- `apps/hr`: the app itself (Android and iOS projects). Run Flutter commands here.
- `apps/packages`: shared code and one package per included add-on.
- `apps/hr/dart_define.json`: your server address and app name. Add your real-time key here.
- `BUILD.md`: the build checklist. `AGENTS.md`: instructions for an AI coding agent.
- `app-source.json`: the versions, add-ons and app details it was generated with.
- `.github/workflows/build-app.yml`: an optional GitHub Actions workflow that builds the Android app.

## What only you can provide

| What | Where | Needed for |
|---|---|---|
| Firebase project | Run `flutterfire configure` in `apps/hr` | Push notifications and crash reports |
| Google Maps key | `MAPS_API_KEY` in `apps/hr/android/local.properties` and `apps/hr/ios/Flutter/Secrets.xcconfig` | Maps, live tracking and visit locations |
| Real-time key | `OPEN_CORE_HR_REVERB_KEY` in `dart_define.json`: the `REVERB_APP_KEY` from your server's `.env` (see [real-time services](https://czappstudio.com/docs/installation/services)) | Chat, calls and live updates |
| Signing | `apps/hr/android/key.properties` for your upload key; your team in Xcode | Publishing |
| Store accounts | Google Play Console and Apple App Store Connect | Publishing |

Calls use the Agora account set on your server under **Settings → Calls**; nothing is needed in the app.

## Build

With Flutter 3.47.7 installed:

```bash
cd apps/hr
flutter pub get
flutter build appbundle --release --dart-define-from-file=dart_define.json
flutter build ipa --release --dart-define-from-file=dart_define.json
```

The app version is your Core version. The build number goes up each time you generate the source, so every new upload is accepted by the stores.

## After an update

After you update Core or an add-on on your server, or install a new add-on, generate the app source again. The Mobile app page tells you when your server runs newer versions than your last app source. Copy your Firebase files, `key.properties`, `local.properties` and `Secrets.xcconfig` into the new folder and build again. Your current app keeps working with your server until you publish the new build; new add-on screens appear after the update.

To make staff install the new version, set the minimum app version under **Settings → Mobile app** on your server once the new build is in the stores.
