Installation

First run after you unzip the Field package: confirm Flutter, restore Dart packages, then launch against your Veldriq origin. Do not edit auth, the router, or the sync engine to reskin V1.

The archive root is not the Flutter project. There is no demo seed. There is no Laravel in this SKU — do not look for artisan. This is not the Field PWA included with Veldriq Web.

Unzip

veldriq-field-1.0.0/
  START-HERE.txt
  documentation/
  mobile/          ← Flutter project (pubspec.yaml is here)
  LICENSE
  VERSION

cd veldriq-field-1.0.0/mobile

If you cloned the author repository, the folder is still mobile/ at the repo root. Keep the tree out of cloud-sync folders that mangle .jks or google-services.json.

Toolchain

flutter doctor
flutter --version
flutter pub get

You want Flutter 3.44+ / Dart 3.12.2+. You do not need dart run build_runner for a first run — generated Drift code is already in the tree. Flutter generates l10n itself (generate: true). There is no Freezed step.

If it fails: Dart older than 3.12.2 → upgrade Flutter to 3.44+ stable. pub.dev blocked → fix proxy then retry pub get. Accidental pod install on first run → stop; this tree does not ship a Podfile as a first-run step.

pubspec.yaml starts at version: 1.0.0+1 (versionName / CFBundleShortVersionString + versionCode / CFBundleVersion). Bump before each store upload. Protocol compatibility stays at API version 1 / sync protocol 1 — do not bump the protocol as part of a reskin.

Identity files (not required for first flutter run)

Copy from	To	Purpose
android/buyer.properties.example	android/buyer.properties	applicationId and launcher app_name
android/keystore.properties.example	android/keystore.properties	Upload keystore path and passwords (not key.properties)

Filled copies are gitignored. iOS identity is set in Xcode: PRODUCT_BUNDLE_IDENTIFIER and CFBundleDisplayName. Template bundle is com.cnonetech.veldriq.field. Android Gradle namespace is com.cnonetech.veldriq.field; fallback applicationId is the same if buyer.properties is absent.

APP_DISPLAY_NAME is Dart-only (in-app title). It does not change the home-screen label. Set Android app_name and iOS CFBundleDisplayName as well. See Branding.

Firebase JSON/plist is optional. Leave it out for first compile and login.

First development run

Those three dart-defines are the only buyer dart-defines in V1. Changing the URL later requires a rebuild. There is no runtime server picker.

flutter run --flavor development \
  --dart-define=APP_ENV=development \
  --dart-define=API_BASE_URL=http://127.0.0.1:8000 \
  --dart-define=APP_DISPLAY_NAME=Field\ Dev

Android emulator → host Laravel is http://10.0.2.2:8000 — you must pass that; the default 127.0.0.1 is the emulator itself. iOS Simulator has no --flavor matrix — use the same dart-defines without --flavor.

What you should see

Screen	Meaning
Welcome back — “Enter your work email and password to continue.”	Configuration is valid. Sign in with the technician’s work email and password — not a Profile API token.
Invalid configuration — “The API base URL is missing or invalid. Production requires HTTPS.”	Rebuild. Technicians cannot fix this in the app.
Unable to reach your company’s server	Origin is parseable but the device cannot talk to it.

First-login journey (no demo data)

1. Veldriq web is installed, on HTTPS for production, with cron running.
2. Platform Admin → Settings → License & Products → activate Field with the Field purchase code. Web product status Active is not enough.
3. Staff User, then Workforce → Technicians: Active profile linked to that user, role that includes field.workspace.view. A User is not a Technician. Do not tell technicians to create Profile → API tokens.
4. Office schedules a non-Draft appointment assigned to that technician.
5. Build/run with the three dart-defines pointing at that origin.
6. On Welcome back, tap Sign in. After workspace selection (if more than one), land on Today.

If login shows Access denied. the Field product is not activated, or the account lacks Field permission. See Licence.

Continue: Requirements · API base URL · Eligibility · Licence.