Configuration complète de `shorebird.yaml`

Le fichier shorebird.yaml, placé à la racine du projet Flutter et embarqué dans les assets (flutter_assets/shorebird.yaml), est lu par deux composants complémentaires :

Le moteur natif Rust embarqué (updater/library/src/yaml.rs et config.rs) au démarrage de l'application mobile.
La CLI de déploiement Dart (FlutterProject dans tk_ota_push/lib/src/cli/project.dart) lors des commandes release, patch, promote et symbols.

Règle de parsing du moteur Rust

Le parseur embarqué dans le moteur Rust (YamlConfig::from_yaml dans updater/library/src/yaml.rs) est un parseur clé-valeur ligne par ligne (key: value) pour les clés runtime de premier niveau (app_id, channel, base_url, auto_update, patch_public_key, patch_verification), et ignore silencieusement toutes les clés additionnelles ou imbriquées destinées à la CLI (tenant_id, web_console_url, flavors, environments, geo, rollout).

Tableau récapitulatif de toutes les clés supportées

Clé	Type	Consommateur	Défaut	Obligatoire	Description
`app_id`	`String`	Rust + CLI	Auto-détecté par la CLI	Oui (au runtime Rust)	Identifiant unique de l'application. Si omis dans le fichier source, `FlutterProject.ensureShorebirdYamlAppId()` l'injecte automatiquement avant le build.
`base_url`	`String`	Rust + CLI	`https://api.shorebird.dev` (Rust) / `http://localhost:8080` (CLI)	Recommandé	URL racine du serveur OTA souverain (sans slash final requis). Le moteur Rust appelle `{base_url}/api/v1/patches/check` et `{base_url}/api/v1/patches/events`.
`channel`	`String`	Rust + CLI	`stable`	Non	Canal de distribution par défaut (`stable`, `staging`, `beta` ou canal personnalisé).
`auto_update`	`bool`	Rust	`true`	Non	Si `true`, le moteur C++/Rust déclenche un thread de mise à jour automatique à chaque démarrage natif. Si `false`, le SDK Dart `TkOtaPush` pilote les appels via le Gatekeeper.
`patch_public_key`	`String`	Rust + CLI	`null`	Oui (en mode strict)	Clé publique RSA encodée en Base64 (Base64) utilisée par le moteur Rust pour vérifier la signature cryptographique de chaque patch.
`patch_verification`	`String`	Rust	`strict`	Non	Moment de la vérification cryptographique de la signature : `strict` ou `install_only`.
`tenant_id`	`String`	CLI	`session.tenantId` ou `default`	Non	Identifiant de l'organisation multi-tenant envoyé dans les requêtes d'administration de la CLI.
`web_console_url`	`String`	CLI	`http://localhost:3000`	Non	URL de la console Web utilisée par `tk-ota-push login` lorsque le flag `--web-url` n'est pas fourni.
`environments`	`Map<String, String>`	CLI	`null`	Non	Dictionnaire associant un nom d'environnement (`dev`, `staging`, `prod`, `uat`) à un `app_id` spécifique. Prioritaire sur `flavors`.
`flavors`	`Map<String, String>`	CLI	`null`	Non	Dictionnaire associant un flavor Flutter (`dev`, `staging`, `prod`) à un `app_id` spécifique.
`geo.default_countries`	`List<String>` ou `String`	CLI	`null` (Mondial)	Non	Liste de codes pays ISO-2 par défaut pour le déploiement géographique (ex: `["CI", "SN", "CM"]` ou `"CI,SN,CM"`). Alias supportés : `geo.countries`, `rollout.default_countries`, `rollout.countries`.

Détail des clés du moteur runtime (Rust)

`app_id`

Identifie de manière unique le triplet (app_id, channel, release_version) lors des appels à POST /api/v1/patches/check.

Dans le moteur Rust : la présence de la ligne app_id: ... est obligatoire (missing required field: app_id sinon).
Dans la CLI tk-ota-push : vous n'êtes pas obligé de l'écrire manuellement. Si app_id est absent de shorebird.yaml, la CLI résout l'identifiant (via --app-id, --dart-define, environments, flavors ou extraction native build.gradle / project.pbxproj), puis appelle ensureShorebirdYamlAppId(effectiveAppId) pour écrire app_id: "<effectiveAppId>" en tête de shorebird.yaml avant la compilation Flutter.

`base_url`

URL de votre serveur TkushPatch On-Premise.

Exemple en développement local sur émulateur ou Wi-Fi : http://192.168.0.199:8080
Exemple en production : https://ota.banque.internal
Le serveur Serveur TkushPatch (ShorebirdUpdaterController.resolveClientReachableUrl) réécrit dynamiquement les URLs de téléchargement d'artefacts si base_url pointe sur une adresse locale ou derrière un reverse-proxy (X-Forwarded-Host / X-Forwarded-Proto).

`auto_update`

Accepte uniquement les booléens true ou false (toute autre valeur génère l'erreur invalid value for auto_update).

auto_update: false (Recommandé avec TkOtaPush) : désactive l'appel réseau systématique du moteur C++/Rust au démarrage de l'application. Vous déléguez ainsi la décision à TkOtaPush.instance.syncWithRemoteConfig(...) et son RemoteConfigGatekeeper en 3 étapes (zéro appel réseau inutile).
auto_update: true : le moteur natif interroge automatiquement POST /api/v1/patches/check en arrière-plan à chaque lancement de l'application, sans passer par le Gatekeeper Dart.

`patch_public_key`

Clé publique RSA encodée en Base64 utilisée pour vérifier le champ hash_signature renvoyé par le serveur.

Lors de l'exécution de tk-ota-push release ou tk-ota-push patch, la méthode Publisher.prepare() appelle automatiquement GET /api/admin/v1/public-key sur le serveur et met à jour la ligne patch_public_key: dans shorebird.yaml via project.writePublicKey(key).
Si le serveur ne renvoie aucune clé publique valide, la CLI interrompt immédiatement la compilation avec une CliException de sécurité stricte.

`patch_verification`

Contrôle la politique de vérification de signature cryptographique dans le moteur Rust (PatchVerificationMode dans updater/library/src/yaml.rs) :

strict (Valeur par défaut) : vérifie la signature RSA du patch à l'installation et à chaque démarrage (boot time) de l'application, protégeant contre toute altération du fichier de patch sur le stockage flash après installation.
install_only : vérifie la signature RSA uniquement au moment du téléchargement et de l'installation initiale du patch. Accélère légèrement le démarrage à froid mais offre moins de protection contre une altération locale post-installation.
Toute autre valeur que strict ou install_only est rejetée avec invalid value for patch_verification.

Détail des clés avancées de la CLI (`tk-ota-push`)

`environments` et `flavors`

Lorsque vous compilez plusieurs variantes de votre application, FlutterProject.appIdForEnvironment(env) inspecte d'abord la section environments, puis flavors, puis se replie sur le app_id racine :

tenant_id: groupe-bancaire
app_id: com.banque.mobile.prod
base_url: https://ota.banque.internal
channel: stable
auto_update: false
patch_verification: strict

environments:
  dev: com.banque.mobile.dev
  staging: com.banque.mobile.staging
  prod: com.banque.mobile.prod

flavors:
  dev: com.banque.mobile.dev
  staging: com.banque.mobile.staging
  prod: com.banque.mobile.prod

`geo` / `rollout` (Ciblage géographique par défaut)

La méthode FlutterProject.defaultCountries lit les codes pays ISO-2 par défaut dans geo.default_countries, geo.countries, rollout.default_countries ou rollout.countries (sous forme de liste YAML ou de chaîne séparée par des virgules) :

geo:
  default_countries:
    - CM
    - CI
    - SN

Ou en syntaxe compacte :

rollout:
  countries: "CM,CI,SN"

Si le flag CLI --countries est passé lors de tk-ota-push patch (ex: --countries "CI,SN" ou --countries all), il surcharge cette configuration.

Combinaisons types de `shorebird.yaml`

Configuration Production Souveraine avec Gatekeeper (Recommandée)

tenant_id: sara-money
app_id: com.saramoney.retail
base_url: https://ota.saramoney.internal
web_console_url: https://console-ota.saramoney.internal
channel: stable
auto_update: false
patch_verification: strict
patch_public_key: MIIBCgKCAQEA...

Configuration Développement Local / Démo autonome

tenant_id: sos
app_id: com.ota_demo_app.d
base_url: http://192.168.0.199:8080
channel: stable
auto_update: true
patch_verification: strict
patch_public_key: MIIBCgKCAQEA...

Tableau récapitulatif de toutes les clés supportées​

Détail des clés du moteur runtime (Rust)​

app_id​

base_url​

auto_update​

patch_public_key​

patch_verification​

Détail des clés avancées de la CLI (tk-ota-push)​

environments et flavors​

geo / rollout (Ciblage géographique par défaut)​

Combinaisons types de shorebird.yaml​

Configuration Production Souveraine avec Gatekeeper (Recommandée)​

Configuration Développement Local / Démo autonome​