Build and release
Versions, release trains aligned with the plan, the Play Console setup, tracks and staged rollouts, store assets, data-safety answers and declarations, signing, forced updates, the pilot hotfix procedure and the post-pilot iOS path.
Both apps ship to Android through Google Play; iOS comes after the pilot if HOCO decides it. This page covers store readiness (MOB-14), the go-live (LCH-01), the pilot (LCH-03B), the public release at generalisation (LCH-05) and iOS (MOB-16). Shared release rules (environments, deployment order, feature flags) are in environments and releases.
Versions
| Item | Rule |
|---|---|
| Version line | One semantic version for both apps, tagged vX.Y.Z on master of hoco-mobile (git workflow); an app that did not change is not uploaded |
versionName | From the tag (1.0.0); -dev / -stg suffixes come from the flavor |
versionCode | The CI run number (--build-number=${{ github.run_number }}) — always increasing, never typed by hand |
X-App-Version | versionName without suffix, compared by the server with AppVersionPolicy |
| MAJOR | A change that needs a new minimum API or breaks local data compatibility (rare) |
| MINOR | Features — including V2 features, which are product scope, not breaking changes |
| PATCH | Fixes and hotfixes |
Each release PR (release/x.y.z → master) bumps version: in both apps' pubspec.yaml, updates CHANGELOG.md (user-facing French release notes for the store, technical notes for the team) and records the pinned contract version.
Release trains
Aligned with the plan's milestones (dates on the timeline):
| Plan moment | Build | Flavor and environment | Distribution |
|---|---|---|---|
| Foundations and feature build (P0–P1) | Every push to dev | staging → staging API | Firebase App Distribution, group team (Imad, Anis, Akram); weekly Thursday build after the internal demo with release notes for HOCO's testers group |
| Mobile apps V1 feature-complete → Staging integration complete | Release candidates 1.0.0 from release/1.0.0 | staging; field test builds for MOB-13 | App Distribution groups team, field-test |
| Store readiness (MOB-14) | First prod AAB | prod → production API (not yet open) | Play internal testing track: proves signing, listing and review |
| Client acceptance (QA-02) | Same commit as the candidate, built twice | staging flavor with env/preprod.json → pre-production | App Distribution group hoco-acceptance |
| Production go-live (LCH-01) | v1.0.0 | prod | Play closed testing track for the pilot group (D-32) |
| Pilot (two weeks) | v1.0.x hotfixes | prod | Closed track; in-app update prompt |
| Generalisation (LCH-05) | v1.1.0 with the pilot improvements (MOB-18) | prod | Production track, staged rollout |
| After generalisation | iOS if decided; V2 features as minor versions | prod | App Store (TestFlight first); Play production |
Play Console
- Account — an organisation developer account owned by HOCO (D-25): it needs a D-U-N-S number, identity verification and the one-time registration fee paid with an internationally accepted card; start at the cadrage (PRJ-03) because verification can take weeks. Imad: admin for releases; Anis: admin. A personal account would have to run a closed test with at least 12 testers for 14 days before production access — the two-week pilot on the closed track could satisfy it, but production access then waits for Google's review.
- Two apps: HOCO Revendeur (
dz.hoco.reseller) and HOCO Délégué (dz.hoco.delegate), default language French (Algeria/France), country availability Algeria. - App access (both apps are behind sign-in): reviewer instructions with demo accounts on production — a validated reseller « Magasin Démo » and a delegate with a demo tour of three stops — flagged as test data and excluded from KPIs by Anis. Reviewers cannot receive SMS, so the demo reseller signs in with a password.
- Delegate app visibility: it is useless without an account created by HOCO. Assumption — published like the reseller app with « Réservée aux délégués commerciaux HOCO » in the listing; a private (managed Google Play) distribution would need HOCO to run an enterprise mobility setup.
Tracks and staged rollouts
| Track | Who | Use |
|---|---|---|
| Internal testing | Up to 100 named testers (team, HOCO IT) | Every prod candidate; instant availability, no review delay |
| Closed testing | Pilot delegates and resellers (Google accounts or a Google Group) | The pilot; hotfixes |
| Production | Everyone in Algeria | From generalisation; staged rollout |
Production rollouts are staged: 10 % → 25 % → 50 % → 100 %, one step per day at least, each step only if crash-free sessions stay ≥ 99.5 % in Sentry, Play vitals are normal and no severity-1 ticket is open. Halt rollout in Play Console is the first reflex when a regression appears; a fix ships as the next patch (Play has no rollback to an older versionCode).
Store listing assets
Delivered by Akram in DQA-01:
| Asset | Specification |
|---|---|
| App icon | 512 × 512 PNG (32-bit), plus the adaptive launcher icon (foreground, background and monochrome layers for themed icons) and the dev/staging ribbon variants |
| Feature graphic | 1024 × 500 PNG or JPEG |
| Phone screenshots | 4–8 per app, portrait, in French, from the release candidate on the reference phone (status bar cleaned), with short captions |
| Notification icon | White-on-transparent glyph, 24 dp, ic_stat_hoco |
| Splash | Android 12+ splash icon (flutter_native_splash), background colour from tokens |
| Short and full descriptions | French, 80 and up to 4 000 characters, written with HOCO; Arabic later (D-09) |
Declarations and data safety
Play Console → App content, completed in MOB-14 for each app:
| Declaration | Reseller app | Delegate app |
|---|---|---|
| Privacy policy URL | settings.legal.privacyUrl (https://app.hoco.dz/confidentialite), text validated by HOCO (SEC-08, Law 18-07) | Same URL; it includes the location section shown on DA-04 |
| App access | Demo reseller account | Demo delegate account with a demo tour |
| Ads | None | None |
| Content rating | Questionnaire: business app, no user-to-user public content | Same |
| Target audience | 18 and over | 18 and over |
| Financial features | None of the listed consumer financial services (B2B invoices, payment declarations and trade credit are not lending) — confirm the wording with HOCO | None |
| Account deletion | Required: users create accounts in the app, so an in-app path (« Supprimer mon compte » in RA-35) and a web URL must exist (D-11); legally required records (invoices) are kept and disclosed | Not required (accounts are created by HOCO) — the privacy policy still explains how to request deletion |
| Foreground service | — | Foreground service type location: description (tour tracking while a tour is in progress, started by the user, visible notification) and a short video of starting a tour and the notification |
| Background location | Not requested | Not requested (D-24); if HOCO chooses option 2: location permissions declaration, prominent-disclosure screenshots and a video |
| Photo and video permissions | None — the system photo picker is used | None — camera only |
The in-app account-deletion path for resellers needs an operation and a back-office handling step: to agree with Anis (it is not in the endpoint catalogue yet).
Data safety answers
Everything is encrypted in transit (HTTPS). Data is not sold and not shared with third parties for their own purposes; Firebase and Sentry act as service providers.
| Data type (Play category) | Reseller app | Delegate app | Purpose | Optional? |
|---|---|---|---|---|
| Name | Owner name | Delegate name (account) | Account management, app functionality | Required |
| Phone number | Account phone, WhatsApp number | Account phone; prospects' phones are business records entered by the delegate | Account management, app functionality | Required |
| Email address | Optional store email | — | Account management | Optional |
| Address | Store and delivery addresses | Prospects' store addresses | App functionality | Required |
| Precise location | Optional pin on the delivery address | Check-in, tour start and sampling during tours | App functionality, fraud prevention (proof of visit) | Reseller: optional · Delegate: required for field work |
| Approximate location | WhatsApp region for guests who accept | — | App functionality | Optional |
| Photos | Payment proofs, store photos, after-sales and return photos | Visit and façade photos | App functionality | Optional (reseller) · per visit type (delegate) |
| Files and docs | Store documents (RC, NIF, ID), payment proofs in PDF | Store documents uploaded for a prospect | App functionality, account management | Optional |
| Purchase history | Orders, returns, invoices, payments | Assisted orders | App functionality | Required |
| Other in-app messages | Support tickets and after-sales conversations | — | App functionality, customer support | Optional |
| App interactions | Only if analytics are enabled (assumption) | Same | Analytics | — |
| Crash logs, diagnostics | Sentry | Sentry | App functionality (stability) | Required |
| Device or other IDs | Install id (X-Device-Id), FCM token | Same | App functionality (push, sessions), fraud prevention | Required |
Android platform requirements
- Target SDK: Google Play requires targeting an API level released within the last year for new apps and updates — follow Flutter's
targetSdkVersionand check it is at least the required level before MOB-14. - 16 KB memory pages: apps targeting Android 15+ must ship native libraries aligned for 16 KB pages. Recent Flutter engines are; every plugin with native code (maps, camera, scanner, SQLite) must be too — check the release AAB in Android Studio's APK Analyzer or with
zipalign -c -P 16 -v 4on the APKs. - Edge-to-edge is enforced on recent targets: screens use
SafeAreaand the system-bar insets; check bottom sheets and the bottom navigation on gesture and three-button navigation. - Predictive back on recent Android versions: go_router pops must behave with the back gesture; dialogs with unsaved data use
PopScope. - Foreground-service types and permissions declared as on location;
POST_NOTIFICATIONSrequested at runtime.
Signing
- Play App Signing is mandatory for AAB uploads: Google holds the app-signing key; the team holds one upload key per app (repository › signing). Loss of an upload key is recoverable through Play support (days).
- Fingerprints to copy from Play Console → App integrity once each app exists:
| Fingerprint | Where it goes |
|---|---|
| App-signing key SHA-256 | assetlinks.json of the reseller web (App Links) |
| App-signing key SHA-1, upload key SHA-1, debug key SHA-1 | Google Maps API key restrictions (Android apps) per flavor |
| Upload key SHA-256 | assetlinks.json too, so internal-track builds open App Links |
- Keystores and passwords: vault (Mobile collection) and GitHub Actions secrets only.
Forced and suggested updates
AppVersionPolicy per app and platform (edited by Anis on BO-66) reaches the app through appConfig.get at cold start and on resume after an hour, and through 426 UPGRADE_REQUIRED on any call (ADM-07):
| Answer | App behaviour |
|---|---|
forceUpdate: true (or any 426) | Blocking screen RA-36 / DA-28 « Mise à jour obligatoire »; « Mettre à jour » starts Play's immediate in-app update (in_app_update) when installed from Play, otherwise opens storeUrl. The delegate app keeps its outbox and replays it after the update |
updateAvailable: true | Dismissible banner with releaseNotes, once per version; Play flexible update when available |
maintenance.enabled | Maintenance screen with message and until; the delegate app keeps working offline |
Rules for raising minVersion (owned by Anis, agreed with Imad):
- Only after the new version is available on the track the users are on (closed during the pilot, production after).
- Never during field hours: a delegate forced to update with a weak network cannot sync until the download finishes. Raise it in the evening, after a suggested-update period of at least two days when possible.
- Old versions must keep working until then: contract changes are additive (API integration › contract change).
Hotfixes during the pilot
The pilot runs on the closed track for two weeks with Imad on call (LCH-03B).
Triage — daily with Anis: Sentry issues, Play vitals, pilot feedback (WhatsApp group of the pilot, support tickets). Severity 1: an order, a visit or synced data is lost or wrong, the app crashes on a main flow, sign-in impossible — fix the same day. Severity 2: a workaround exists — next weekly patch. Severity 3: backlog for MOB-18.
Branch — hotfix/1.0.x from the v1.0.y tag on master; the fix with a regression test; PR into master with Anis's review.
Build — tag v1.0.x; release.yml builds the prod AAB, uploads symbols to Sentry and pushes to the internal track; smoke-test on the reference phone (sign-in, one order or one offline visit, sync).
Promote — internal → closed track (closed-track reviews are usually quick but not instant: ship severity-1 fixes early in the day). If the bug corrupts data, raise minVersion once the fix is live, outside field hours.
Close — merge master back into dev; note the fix in CHANGELOG.md and in the pilot log.
Server-side mitigations come first when they exist (a setting, a feature flag, an API fix by Anis) because they reach every phone at once.
iOS — after the pilot, on HOCO's decision
iOS is out of the three-month V1 frame: MOB-16 starts after the pilot improvements, only if HOCO confirms it (D-10). Keep the ios/ folders building locally so the work is a port, not a rewrite.
| Step | Detail |
|---|---|
| Accounts | Apple Developer Program as an organisation under HOCO (D-U-N-S again, annual fee); Imad as admin; App Store Connect apps dz.hoco.reseller, dz.hoco.delegate |
| Build machine | A Mac, or a hosted macOS CI (macOS minutes on GitHub cost ten times more; Codemagic is an alternative) |
| Signing | Automatic signing locally; certificates and profiles for CI (fastlane match or the hosting service's signing) |
| Flavors | Xcode schemes and build configurations per flavor; GoogleService-Info.plist per flavor |
| Permissions strings | NSLocationWhenInUseUsageDescription, NSCameraUsageDescription, NSPhotoLibraryUsageDescription in French, matching the Android rationale screens |
| Push | APNs authentication key uploaded to each Firebase project; explicit permission prompt with context |
| Delegate tours | Background location on iOS requires the location background mode and Always authorisation, with stricter App Review — decide whether iOS delegates exist at all |
| Links | Universal Links with apple-app-site-association on the reseller web; no install referrer (fallback) |
| Review | TestFlight for the team and HOCO, then App Review with the demo accounts and notes |
Quality and testing
How the Flutter apps are tested and kept healthy: the test pyramid, integration tests of the critical flows, the GitHub Actions pipeline, the review checklist, performance budgets, crash reporting and the manual device matrix.
Conventions
Code conventions of hoco-mobile: lint rules, naming, folders, commit messages and scopes, pull requests, localisation keys, assets, and how task and screen ids appear in code.