Canaux

Nouveau avec les canaux ? Regardez trois courtes vidéos de démonstration pour voir le routage par défaut, l'auto-assignation d'appareil et les overrides de console en action.

Le @capgo/capacitor-updater méthodes setChannel() et unsetChannel() dans ce guide ne sont supportés que sur Android et iOS. Ils ne modifient pas le routage du canal dans les aperçus navigateur.

Comment Capgo choisit un canal (priorité)

Lorsqu'un appareil demande une mise à jour à Capgo, le canal utilisé est déterminé selon l'ordre suivant (priorité la plus haute en premier) :

1. Mapping d'appareil forcé: Si l'ID de l'appareil est explicitement forcé vers un canal (le Appareils onglet de la page du canal), ce canal l'emporte toujours. Les mappings forcés sont des overrides console/API. Capgo les supprime 90 jours après la dernière écriture d'override. Voir Les overrides de la console et API expirent.
2. Override cloud (dashboard ou API public): Changer le canal d'un appareil dans le dashboard ou via l’API public crée un override lié à cet ID d'appareil. Réinstaller l'app ne pas l'efface pas ; supprimer l'override, si. La même rétention de 90 jours s'applique.
3. Plugin setChannel() (local): Sur les versions actuelles du plugin, setChannel() stocke le canal sur l'appareil après validation côté backend. Ce n'est pas un override du dashboard. Sur Android et iOS avec l'updater 8.51.0 et versions ultérieures, persistDefaultChannelOnReinstall par défaut sur true, ce choix ne survit à une réinstallation que si le système d'exploitation restaure les données de l'application et persistDefaultChannelOnReinstall reste true. Appelez unsetChannel() pour effacer explicitement le choix local.
4. Configuration Capacitor defaultChannel (build de test par défaut): Pour les builds internes / bêta / de test, vous pouvez définir defaultChannel (clé héritée channel) dans capacitor.config.* pour que les appareils de test démarrent sur un canal de pré-release (ex. beta, pr-123). Si absent, l'appareil utilisera le canal par défaut du cloud. Les builds de production laissent généralement ce champ vide.
5. Canal cloud par défaut (stratégie principale pour ~99 % des utilisateurs): Le canal de production principal sur lequel arrivent pratiquement tous les utilisateurs réels. Tout nouvel appareil sans forçage, sans override, sans choix local setChannel(), et sans configuration defaultChannel utilise ceci. Le modifier permet un déploiement progressif (ou un rollback) pour tout le monde en quelques secondes, sans nouveau binaire.

Pourquoi le défaut cloud est la voie principale :

• Déploiement progressif ou rollback instantané sans recompiler ni republier de binaires natifs.
• Un seul endroit pour gérer le comportement sur iOS, Android et Electron.
• Plus sûr : vous pouvez confirmer l'existence des bundles et l'exactitude des paramètres avant de changer la valeur par défaut.
• Modifications auditables (les membres de l'équipe peuvent voir qui a modifié quoi dans l'UI / les logs).\nPrincipe de conception : les couches supérieures (force / override / config) sont exceptions (débogage d'un utilisateur, switch QA, test des défauts de build). Les utilisateurs normaux suivent le défaut cloud.

Changer le cloud par défaut le canal affecte nouveau appareils normaux qui :

• Ne sont pas forcés
• N'ont pas déjà de cloud override
• N'ont pas de niveau application defaultChannel défini

Si un build de test est déployé avec defaultChannel: 'beta' et que vous changez plus tard le cloud default en production, les appareils ayant commencé sur beta via la config y restent jusqu'à l'application d'un assignation prioritaire, ou jusqu'au déploiement d'un binaire sans defaultChannel. La suppression d'un forçage, d'un override cloud ou d'une setChannel() affectation locale ne supprime pas la valeur de config ; ce fallback subsiste jusqu'au nouveau binaire.

Les appareils restent sur leur canal actuel, sauf si vous :

• Forcez-les sur un autre canal (console ou API publique).
• Modifiez l'override cloud dans le dashboard ou via l'API publique.
• Appelez setChannel() (affectation locale sur les versions actuelles du plugin).
• Supprimez / archivez le canal sur lequel ils sont (ils repasseront alors par l'ordre de priorité à la prochaine vérification).
• Attendez qu'un override console/API expire au bout de 90 jours.
• Appelez unsetChannel() pour effacer une setChannel() affectation. Cela ne supprime pas un override console/API ou une configuration d'application defaultChannel; la priorité normale s'applique à nouveau.
• Réinstallez l'application, ce qui peut effacer une affectation locale sur les anciennes versions de l'updater ou lorsque les données de l'application ne sont pas restaurées. Sur Android et iOS avec l'updater 8.51.0 et versions ultérieures, persistDefaultChannelOnReinstall par défaut sur true, ainsi les données restaurées de l'application peuvent préserver le choix local tant que cette option est active true. Les overrides Console/API ne sont pas affectés.

Si un canal est désactivé pour une plateforme (voir les commutateurs iOS / Android / Electron) et qu'il aurait dû être sélectionné, la sélection l'ignore et passe à la règle suivante.

Note : Définir defaultChannel signifie qu'un changement nécessite un nouveau binaire ; utilisez-l’intentionnellement pour le test/QA, pas pour le contrôle de production général.

Exemple de configuration Capacitor

capacitor.config.ts

// Example: a TestFlight or internal QA build defaults to the beta channel.
const config = {
  plugins: {
    CapacitorUpdater: {
      defaultChannel: 'beta', // Test build default. Omit in production so users attach to cloud default.
      // legacy key: channel
    },
  },
};
export default config;

Si vous changez plus tard la valeur par défaut du dashboard pour production, les appareils déjà sur un autre canal (via config, override ou force) ne seront PAS déplacés automatiquement ; seuls les nouveaux appareils (ou ceux dont l'override/force est effacé) en bénéficieront.

---

Gérer les canaux

Commençons par regarder la page des canaux. Vous pouvez y accéder en cliquant sur votre application puis en cliquant sur l'onglet channels.

Créer un canal

Comme vous pouvez le voir, un bouton plus est disponible en bas à droite. (1 (comme sur l'image) Cliquez dessus pour ouvrir une modale et créer un nouveau canal.

Ensuite, après avoir cliqué sur Add un nouveau canal devrait apparaître dans la liste.

Que signifie « mal configuré » ?

Il arrive que la configuration d'un canal ne soit pas valide. Dans ce cas, un avertissement important s'affichera et le Misconfigured colonne indiquera Yes pour un ou plusieurs canaux. Vous pouvez en savoir plus ici

Supprimer un canal

Pour supprimer un canal depuis la web app, ouvrez l'onglet Canaux de votre application et trouvez la ligne du canal. Dans la colonne column, click the trash icon, then click Supprimer dans la boîte de dialogue de confirmation.

Si l'icône de la corbeille n'est pas visible, votre compte n'a pas les channel.delete permissions pour cette application. Demandez à un admin d'organisation ou d'application de vous attribuer un rôle permettant de supprimer des canaux, ou supprimez le canal avec une clé API disposant des permissions :

npx @capgo/cli@latest channel delete <channel-name> <app-id>

Lié à l'organisation et à l'application Aperçu de l'app peut supprimer de manière atomique uniquement le canal de preview non public et le bundle qu'elle a créé avec channel delete <preview-channel> <app-id> --delete-bundleIl ne peut ni modifier ni supprimer un canal par défaut/principal existant, le canal d'une autre clé de preview, ou le bundle d'une autre clé. Voir Clés API pour la configuration de moindre privilège.

Gérer un canal

Cliquez sur le nom du canal pour ouvrir la page du canal. Il s'agit d'une page complète avec des onglets, pas d'une modale.

Onglets du canal

• Dashboard : Adoption du bundle actuel et statistiques d'installation pour ce canal.
• InformationsParamètres du canal ci-dessous, incluant le déploiement progressif et le Test Update API.
• Appareils : Uniquement les mappings forcés créés depuis la console ou via API public. Cette liste ne recense pas tous les appareils actuellement sur le canal, ni les appareils ayant utilisé setChannel(). Voir Les overrides de la console et API expirent.
• Historique : Modifications de paramètres et de bundle pour ce canal.
• Aperçu: Aperçu natif et dans le navigateur du bundle lié. Activez l'aperçu du bundle dans Informations sur l'application d'abord.

Paramètres d'information

Restez sur l'onglet Informations . Les paramètres apparaissent dans cet ordre :

Premièrement, Canal de téléchargement par défaut est un badge de statut, pas un bouton de bascule. Actif signifie que ce canal est le canal cloud par défaut pour les nouveaux appareils. Cliquez Gérer dans les paramètres de l'application pour modifier la valeur par défaut sur Informations sur l'application. Pour les valeurs par défaut propres à une plateforme (une pour iOS, une pour Android et une pour Electron), consultez cette même section.

Deuxième IOS . Si celui-ci est à false, les appareils iOS ne pourront pas télécharger de mises à jour depuis ce canal.

Troisièmement, le paramètre Android . Si celui-ci est à false, les appareils Android ne pourront pas télécharger de mises à jour depuis ce canal.

Quatrièmement, le paramètre Electron . Si celui-ci est à false, les applications Electron ne pourront pas télécharger de mises à jour depuis ce canal.

Cinquièmement, le paramètre Disable auto downgrade under native paramètre. Si cette option est activée, il sera impossible de revenir à une version native. Cela signifie que si vous avez envoyé une 1.2.0 version sur l'App Store ou le Play Store et que vous tentez de définir la version du canal sur 1.1.0 alors la mise à jour (rollback) échouera.

Sixièmement, le Disable auto update. Ce paramètre est assez complexe, et vous pouvez en apprendre davantage sur ici

Septièmement, le paramètre Download format . Il détermine si les appareils téléchargent un zip complet, uniquement les fichiers delta modifiés, ou le meilleur des deux. Voir Format de téléchargement.

Huitièmement, le Allow development build. Si cette option est activée, les builds de développement pourront télécharger des mises à jour depuis ce canal. Sinon, toute demande de mise à jour ayant prod réglé sur false sera rejetée. C'est principalement utile pour vos tests.

Le neuvième est Allow production build. Si cette option est désactivée, les builds de production (stores) ne recevront pas de mises à jour de ce canal. Laissez-l’activée pour les canaux destinés aux utilisateurs réels.

Le dixième est Allow Emulators. Si cette option est désactivée, Capgo refusera toute requête de mise à jour provenant d'un émulateur. C'est principalement utile pour vos tests.

L’onzième est Allow physical devices. Si cette option est désactivée, Capgo rejettera les requêtes de mise à jour provenant de téléphones et tablettes réels. Laissez-l’activée pour les canaux de production.

Le douzième est Allow devices to self dissociate/associate. Si cette option est activée, la méthode setChannel sera disponible sur Android et iOS. Si elle est réglée sur false et que vous tentez d'appeler méthode setChannel avec ce canal, l'appel échouera.

Tester la mise à jour API

At the bottom of the Informations onglet, développez Tester la mise à jour API. Capgo affiche une commande curl pour /updates un appareil d'exemple sur ce canal.

Les modifications peuvent mettre jusqu'à 60 secondes à apparaître dans API à cause du cache. Si le canal ne peut pas être testé, la console vous avertit : le canal doit avoir au moins une plateforme (iOS ou Android), des builds de production, des appareils physiques, et être soit le canal de téléchargement par défaut, soit autoriser l'auto-affectation des appareils.

Envoyer une notification de mise à jour

Après avoir modifié le bundle lié, la console peut vous demander de Envoyer une notification de mise à jour. Cela met en file d'attente une notification push silencieuse pour que les appareils du canal vérifient le nouveau bundle immédiatement. Configurez d'abord les identifiants push Android et iOS dans l'onglet Notifications de l'app.

Les overrides de la console et API expirent

Les mappings forcés et les API channel overrides (Dashboard/Public) sont supprimés 90 jours après la dernière écriture d'override. Le dernier check-in d'un appareil ne réinitialise pas ce délai. Pour une affectation qui survit à ce nettoyage, définissez defaultChannel dans votre config Capacitor (survit à la réinstallation, nécessite un nouveau binaire pour changer) ou appelez setChannel() depuis une app Android ou iOS en utilisant @capgo/capacitor-updater 5.34.0+, 6.34.0+, 7.34.0+, ou 8.0.0+ pour la version majeure de votre plugin. Ces versions stockent l'affectation localement, ce qui évite le nettoyage des 90 jours. Les versions antérieures écrivent un override backend soumis au même nettoyage. Sur Android et iOS avec l'updater 8.51.0 et versions ultérieures, persistDefaultChannelOnReinstall par défaut sur true, ainsi qu'une sélection locale peut survivre à une réinstallation uniquement si le système d'exploitation restaure les données de l'application et persistDefaultChannelOnReinstall reste true. Une réinstallation avec persistDefaultChannelOnReinstall: false peut effacer cette sélection locale même si les données de l'app sont restaurées. Utilisez unsetChannel() pour effacer explicitement cette sélection locale.

Modifiez la rétention sur l'onglet Devices du canal. La même notification apparaît lorsque vous forcez un ID d'appareil sur le canal.

Ceci est distinct de conservation de l'inventaire des appareils. L'inventaire supprime les appareils qui ne se sont pas connectés à Capgo depuis 90 jours. L'annulation du nettoyage supprime le mapping même si l'appareil est toujours actif. Détails complets : les overrides Console et API expirent après 90 jours.

Format de téléchargement

Ouvrez un canal et restez sur le Informations . Format de téléchargement se trouve dans la liste des paramètres, sous Disable auto update.

Format de téléchargement dans l'onglet Information du canal. Les nouveaux canaux utilisent par défaut Zip + delta.

Ce paramètre définit ce que Capgo envoie lorsqu'un appareil sur ce canal cherche une mise à jour. Laissez Zip + delta sauf si vous devez forcer un type spécifique.

Libellé dans la console	Valeur CLI / API	Ce que les appareils téléchargent
Zip + delta (par défaut)	all	Chaque appareil reçoit le meilleur package compatible. Les appareils dont la version du plugin prend en charge Delta ne téléchargent que les fichiers delta modifiés lorsque le bundle les contient. Seuls les appareils sur une ancienne version du plugin sans prise en charge de Delta, ou les bundles envoyés sans fichiers delta, basculent sur le zip complet.
Zip complet uniquement	zip	Chaque appareil télécharge l'intégralité du zip du bundle, même si des fichiers delta existent.
Delta uniquement	delta	Seulement les fichiers delta modifiés. Les appareils utilisant une ancienne version du plugin sans support Delta recevront le zip complet si le bundle en contient un.
Zip complet uniquement depuis le build du store	zip_from_builtin	Zip complet uniquement tant que l'appareil est sur le build du store. Après la première live update, Capgo renvoie à nouveau zip + delta.
Delta uniquement depuis le build du store	delta_from_builtin	Delta uniquement tant que l'appareil est sur le build du store. Après la première live update, Capgo renvoie à nouveau zip + delta.

Avec Zip + delta, il est normal de voir certains téléchargements de zip complets. Ils proviennent d'appareils utilisant encore un build natif plus ancien avec une version de plugin sans support Delta (inférieure à 5.10.0, 6.25.0, ou 7.0.35 pour leur version majeure). Voir Mises à jour delta.

Le build du store sont les assets web inclus dans le binaire de l'App Store ou du Play Store, avant toute mise à jour Capgo. Utilisez un from store build only mode définissant si la première mise à jour après le build du store doit être un zip complet ou uniquement un delta, les mises à jour suivantes pouvant utiliser les deux.

Capgo ne couplera pas un canal uniquement zip avec un bundle uniquement delta, ou inversement. La console, CLI, et Canaux API refuse l'enregistrement et vous demande d'envoyer le package manquant ou de changer de mode.

Vous pouvez définir la même valeur depuis CLI. Le canal doit déjà exister :

npx @capgo/cli@latest channel set production com.example.app --update-package zip

Valeurs valides : all, zip, delta, zip_from_builtin, delta_from_builtin.

Déploiements progressifs

Le canal Informations onglet inclut un Déploiement progressif section avec Cible du déploiement et Fallback stable, Modifier la cible de déploiement, Appliquer le pourcentage, et les actions Terminer le déploiement, Rollback du déploiement, Activer le déploiement progressif, Désactiver le déploiement progressif, Suspendre le déploiement progressif, et Reprendre le déploiement.

Les contrôles de déploiement progressif apparaissent en haut de l'onglet Information du canal.

Lecture Déploiements progressifs avant d'en activer un. Ce guide couvre le routage de l'upload (Auto (recommandé) / Cible du déploiement / Remplacer la version stable; CLI --stable / API target: "stable" pour l'écraser), le Ce canal utilise un déploiement progressif la boîte de dialogue bundle-link, et un workflow sécurisé avec Observe et Analyse des logs.

Continuer depuis les canaux

Si vous utilisez Canaux pour planifier le routage des canaux et le déploiement progressif, connectez-l’avec Canaux pour les détails d'implémentation des canaux, Canaux pour les détails d'implémentation des canaux, Solution de bêta-test pour le workflow produit de la solution Beta Testing, Solution de ciblage de version pour le workflow produit de la solution Version Targeting, et Bonnes pratiques pour l'environnement Capgo : staging avec un seul ID d'app mobile pour le contexte pratique dans Capgo Environment Best Practices : Staging avec un seul ID d'application mobile.