Aller au contenu principal

Rollout progressif et ciblage géographique

La CLI tk-ota-push et le serveur OTA prennent en charge trois leviers complémentaires de maîtrise du déploiement d'un patch : le déploiement progressif par pourcentage (Canary Rollout), le ciblage géographique par pays ISO-3166-1 alpha-2 (Geo-Fencing) et les stratégies d'application réseau/urgence (Wi-Fi requis vs mise à jour critique forcée).

1. Déploiement progressif en pourcentage (--rollout)​

Sur la commande tk-ota-push patch, l'option --rollout définit le pourcentage initial d'appareils éligibles au patch :

# Déployer initialement sur 10 % de la flotte
tk-ota-push patch 1.0.0+3 -p android --rollout 10 -m "Canary 10 % nouveau parcours"

Règles de validation dans runner.dart​

  • Valeur par défaut : '100' (100 %).
  • Valeurs acceptées : tout entier compris entre 0 et 100 inclus.
  • Si la valeur n'est pas un entier ou est hors de 0..100, la CLI s'arrête immédiatement avec le code de sortie 64 : 
    --rollout doit être compris entre 0 et 100.
  • Un rollout à 0 (--rollout 0) permet de publier et signer le patch sur le serveur sans le distribuer au public, tout en permettant aux appareils inscrits en Whitelist Canary QA (allowed_client_ids) de le recevoir.

Ajustement dynamique sans recompilation​

Après publication, vous pouvez augmenter ou réduire le pourcentage (10 % -> 50 % -> 100 %) depuis la Console Web ou via l'endpoint REST d'administration :

curl -X POST "$OTA_SERVER_URL/api/admin/v1/patches/$PATCH_ID/rollout?rollout_percentage=50" \
  -H "Authorization: Bearer $OTA_API_KEY"

2. Ciblage géographique par pays (--countries)​

L'option --countries de tk-ota-push patch restreint la diffusion du patch à une liste de codes pays ISO-3166-1 alpha-2 (2 lettres) :

# Cibler uniquement la Côte d'Ivoire, le Sénégal et le Cameroun
tk-ota-push patch 1.0.0+3 -p android --countries "CI,SN,CM" -m "Activation moyen de paiement régional"

# Forcer un déploiement mondial (écrase tout défaut configuré dans shorebird.yaml)
tk-ota-push patch 1.0.0+3 -p android --countries "all" -m "Correctif global"

Logique exacte de résolution (Publisher.parseCountries & FlutterProject.defaultCountries)​

Ordre de priorité pour le ciblage géographique
  1. Flag CLI explicite : Valeur fournie via --countries (priorité maximale).
  2. Configuration locale : Valeur définie dans shorebird.yaml (geo.default_countries).
  3. Par défaut : Diffusion mondiale (null = aucun filtrage géographique).

Vous pouvez définir une liste de pays par défaut dans shorebird.yaml sous deux syntaxes supportées par FlutterProject.defaultCountries :

# Syntaxe 1 : liste YAML dans geo.default_countries
geo:
  default_countries:
    - CI
    - SN
    - CM

# Syntaxe 2 : chaîne CSV dans rollout.countries
rollout:
  countries: "BJ, TG, FR"

Lors de l'exécution de patch, la CLI affiche explicitement la portée retenue :

  • Ciblage géographique : 🌍 Mondial (Tous pays)
  • Ciblage géographique : 🎯 Pays cibles : CI, SN, CM

Pour modifier les pays autorisés d'un patch existant sans recompiler :

curl -X POST "$OTA_SERVER_URL/api/admin/v1/patches/$PATCH_ID/countries" \
  -H "Authorization: Bearer $OTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"countries": ["CI", "SN", "CM", "BF"]}'

3. Stratégies de mise à jour : Silencieuse (Wi-Fi) vs Critique Forcée​

La stratégie d'application côté terminal mobile combine les réglages du serveur OTA, le payload du RemoteConfigGatekeeper et l'initialisation du SDK TkOtaPush.init :

Mode / ParamètreCôté Serveur (/patches/{id}/strategy)Côté Payload Remote ConfigCôté SDK Flutter (TkOtaPush.init)Comportement sur le téléphone
Silencieux Éco-Data (défaut)forceCriticalUpdate: false"force_update": falserequireWifiForSilentUpdate: false, minBatteryPercentageForSilentUpdate: 20Télécharge en arrière-plan (silentBackgroundUpdate) si batterie >= 20 % (ou en charge). Appliqué au prochain démarrage à froid.
Silencieux Wi-Fi uniquementrequireWifi: true"force_update": falserequireWifiForSilentUpdate: trueSi l'appareil est sur réseau mobile (3G/4G/5G), diffère le téléchargement via workmanager (deferredToBackgroundTask) jusqu'au retour sur un Wi-Fi non limité.
Critique Forcé (Urgence)forceCriticalUpdate: true"force_update": trueCallback onCriticalUpdateRequiredIgnore la restriction Wi-Fi, déclenche immédiatement la modale bloquante UI (criticalForcedUpdate), télécharge le patch et requiert le redémarrage (restartRequired: true).

Mise à jour de la stratégie d'un patch via l'API Control Plane​

Lors de la soumission initiale (POST /api/admin/v1/patches), le serveur accepte le champ multipart force_critical_update (false par défaut). Après publication, vous pouvez basculer la stratégie Wi-Fi et l'urgence critique depuis la Console Web ou en appelant POST /api/admin/v1/patches/{patchId}/strategy :

curl -X POST "$OTA_SERVER_URL/api/admin/v1/patches/$PATCH_ID/strategy" \
  -H "Authorization: Bearer $OTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "forceCriticalUpdate": true,
    "requireWifi": false
  }'
Verrouillage des patchs révoqués

Si un patch est à l'état ROLLED_BACK, toute tentative de modification de sa stratégie (/strategy) ou de son ciblage géographique (/countries) est refusée par le serveur avec HTTP 409 Conflict (VERROUILLAGE DE SÉCURITÉ).