Canaux

Copiez un prompt de configuration avec les étapes d'installation et le guide Markdown complet pour ce plugin.

Un canal d'actualisation en direct pointe vers une version spécifique du paquetage JS de votre application qui sera partagée avec tous les appareils configurés pour écouter ce canal pour les mises à jour. Lorsque vous installez le Capgo canal d'actualisation en direct SDK dans votre application, tout binôme natif configuré pour ce canal vérifiera les mises à jour disponibles chaque fois que l'application est lancée. Vous pouvez modifier la version vers laquelle pointe un canal à tout moment et pouvez également revenir à des versions précédentes si nécessaire.

How un appareil choisit un canal (préférence)

Lorsqu'un appareil vérifie une mise à jour, Capgo décide quel canal utiliser dans cet ordre strict (priorité la plus élevée en premier):

Cartographie de l'appareil (Tableau de bord) – Fixer manuellement un ID d'appareil spécifique à un canal. Utilisez pour le débogage urgent ou le test contrôlé avec un seul utilisateur réel.
Surcharge de Cloud (par appareil) via Tableau de bord ou API – Créé lorsque vous modifiez le canal de l'appareil dans le tableau de bord ou via API. Utilisez pour les utilisateurs QA qui passent entre les canaux de fonctionnalité / PR ou pour reproduire un problème d'utilisateur. La suppression du fichier binaire ne le supprime pas ; la suppression de l'entrée de l'appareil le supprime.
Plugin setChannel() canal local – Créé lorsque l'application appelle setChannel() et que le serveur valide que le canal cible autorise l'assignation automatique. Le canal sélectionné est stocké localement sur cet appareil, prend effet instantanément et n'est pas affiché dans l'interface de surcharge de l'appareil.

À partir de la version de plugin 5.34.0, 6.34.0, 7.34.0 ou 8.0.0 (selon votre version majeure), setChannel() fonctionne différemment : il contacte l'arrière-plan pour valider que le canal est autorisé (en vérifiant si l'auto-assignation est activée pour ce canal), puis stocke le canal localement sur le dispositif comme defaultChannelCela signifie que le nouveau canal prend effet instantanément pour la prochaine mise à jour—pas d'attente pour la réplication.

Avant cela, setChannel() en a sauvé le canal de substitution vers la base de données backend (comme le tableau de bord ou API modifications), et les appareils devaient attendre la réplication des données (jusqu'à 2 minutes) avant que le nouveau canal soit reconnu. Le nouveau comportement ne lit que depuis le backend (pour la validation) et stocke localement, ce qui rend les changements de canal instantanés.

Parce que setChannel() est local-only, il fait pas créer une entrée de substitution de appareil dans le Capgo tableau de bord. L'interface utilisateur de la substitution de appareil ne montre que les substitutions créées à partir du tableau de bord ou le Public API.

Remarque : Même si un canal devient interdit après avoir été défini localement, le backend validera toujours le canal lors des vérifications de mise à jour, de sorte que la sécurité est maintenue.

Important : Lorsque les changements de canal sont effectués via le tableau de bord ou API, il y a toujours un retard de réplication de jusqu'à 2 minutes avant que tous les serveurs de bord réfléchissent le changement. Pour un changement de canal instantané, utilisez setChannel() à partir de votre application code—il valide avec le backend, puis définit le canal localement pour un effet immédiat.

Capacitor config defaultChannel (défaut de construction de test) – Si présent dans capacitor.config.* et qu'aucun canal de force/override/local n'existe, l'application démarre sur ce canal (par exemple, beta, qa, pr-123). Intégré pour les builds TestFlight / internes afin que les testeurs atterrissent automatiquement sur un canal de pré-version. Les builds de production laissent généralement cela non défini.
Canal par défaut Cloud (chemin principal ~99% des utilisateurs) – Si vous marquez un canal par défaut dans le tableau de bord, tous les utilisateurs normaux (sans force, sans surcharge du tableau de bord/API, sans canal local de plugin, sans configuration par défaut de canal) s'y attachent. Modifiez-le pour lancer ou annuler instantanément – sans nouvelle version binaire. Si vous avez des valeurs par défaut spécifiques aux plateformes (par exemple, un seul iOS, un seul Android, un seul Electron), chaque appareil atterrit sur la valeur par défaut correspondant à sa plateforme. Laisser le canal par défaut cloud non défini est autorisé ; dans ce cas, l'appareil doit correspondre aux étapes 1-4 pour recevoir des mises à jour.

Meilleure pratique :

Traitez 1-4 comme des couches d'exception / de test ; lorsque vous définissez un canal par défaut cloud, les utilisateurs réels devraient s'y connecter. Si vous choisissez de ne pas le définir, soyez délibéré sur la façon dont les utilisateurs s'y attachent (généralement via defaultChannel en configuration ou par des surcharges par appareil).
Configurez uniquement defaultChannel dans les versions binaires que vous envoyez explicitement aux testeurs. Laisser cela non défini conserve la logique de production centralisée dans le tableau de bord.
Utilisez setChannel() avec parcimonie en production – principalement pour les tests de qualité ou les diagnostics ciblés.

If un canal est désactivé pour la plateforme (iOS/Android/Electron), le processus de sélection le saute et continue dans la liste.

Résumé : Force > Tableau de bord/API Survol > Plugin setChannel() canal local > Config defaultChannel > Cloud par défaut.

Comportement par défaut du canal

La définition d'un canal par défaut est facultative, mais elle sert généralement de chemin par défaut pour les nouveaux appareils. Sans cela, seuls les appareils qui correspondent aux mappages forcés, aux survol, ou à un defaultChannel dans la Capacitor config recevront des mises à jour. Lorsque vous choisissez de marquer des défauts, gardez ces modèles à l'esprit :

Un seul canal par défaut (le plus courant) – Si un canal a iOS, Android et Electron activés, il devient le seul canal par défaut ; tout appareil sans survol attachera ici.
Défauts par plateforme – Si vous divisez les canaux par plateforme (par exemple, ios-production With uniquement iOS activé, android-production Avec uniquement Android activé, et electron-production Avec uniquement Electron activé), marquez chacune comme la valeur par défaut pour sa plateforme. Les appareils iOS se dirigent vers la valeur par défaut iOS, les appareils Android se dirigent vers la valeur par défaut Android, et les applications Electron se dirigent vers la valeur par défaut Electron.

Rappelez-vous que la valeur par défaut cloud et defaultChannel en capacitor.config.* les deux occupent le même niveau de décision. Si vous définissez une valeur par défaut cloud, vous n'avez pas besoin de dupliquer la valeur dans votre Capacitor config—laissez defaultChannel vide pour les builds de production. Réservez defaultChannel pour les binaires que vous envoyez intentionnellement aux testeurs ou à la QA lorsque vous voulez qu'ils commencent sur un canal non de production même si la valeur par défaut cloud est différente.

Vous pouvez modifier les valeurs par défaut à tout moment dans le tableau de bord. Lorsque vous changez une valeur par défaut, les nouveaux appareils suivent la nouvelle configuration immédiatement et les appareils existants suivent les règles de priorité normales la prochaine fois qu'ils se connectent.

Configuration d'un Canal

Lors de l'inscription, vous créez le premier canal (la plupart des équipes le nomment « Production »), mais rien n'est bloqué—you pouvez renommer ou supprimer n'importe quel canal à tout moment. Pour ajouter des canaux supplémentaires ultérieurement :

Allez dans la section « Canaux » du tableau de bord Capgo
Cliquez sur le bouton « Nouveau canal »
Entrez un nom pour le canal et cliquez sur « Créer »

Les noms de canaux peuvent être n'importe quoi. Une stratégie courante est de correspondre les canaux à vos étapes de développement, comme :

Development - pour tester les mises à jour en direct sur les appareils locaux ou les émulateurs
QA - pour votre équipe QA pour vérifier les mises à jour avant une mise en production plus large
Staging - pour les tests finals dans un environnement de production similaire
Production - pour la version de votre application que les utilisateurs finals reçoivent depuis les magasins d'applications

Configuration du Canal dans Votre Application

Une fois vos canaux créés, vous devez configurer votre application pour écouter le canal approprié. Dans cet exemple, nous utiliserons le canal. Development channel

Ouvrez votre capacitor.config.ts (ou capacitor.config.json) fichier. Sous la section plugins optionnellement définissez defaultChannel pour les constructions de test (intérieure / QA). Pour les constructions de production, préférez l'omettre afin que les appareils utilisent la valeur par défaut de Cloud sauf si elle est explicitement surchargée.

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      // For a QA/TestFlight build – testers start on the Development channel automatically.
      defaultChannel: 'Development',
      // Production builds usually omit this so users attach to the Cloud Default channel.
    },
  },
};

Ensuite, construisez votre application web et exécutez npx cap sync pour copier le fichier de configuration mis à jour dans vos projets iOS, Android et Electron. Si vous passez cette étape de synchronisation, vos projets natifs continueront à utiliser la chaîne pour laquelle ils étaient précédemment configurés.

Options et stratégies de canal

Les canaux ont plusieurs options qui contrôlent qui peut recevoir des mises à jour et comment les mises à jour sont livrées. Les plus importantes sont ci-dessous. Vous pouvez configurer ces options à partir de l'application web, du CLI, ou du Public API.

Canal par défaut : Marquez facultativement le canal ou les canaux spécifiques au plateau qui les nouveaux appareils s'attachent. Voir « Comportement du canal par défaut » pour les scénarios de routage.
Filtres de plateforme : Activer ou désactiver la livraison à iOS, Androidou Electron par canal.
Désactiver la mise à niveau automatique sous native : Empêche l'envoi d'une mise à jour lorsque la version native de l'appareil est plus récente que la version du canal (par exemple, appareil sur 1.2.3 tandis que le canal a 1.2.2).
Permettre les builds de développement : Autoriser les mises à jour des builds de développement (utile pour les tests).
Permettre les appareils émulateurs : Autoriser les mises à jour des émulateurs/simulateurs (utile pour les tests).
Permettre l'affectation automatique de l'appareil : Permet à l'app de passer à ce canal en temps de exécution à l'aide de setChannel. Si désactivé, setChannel échouera pour ce canal.

Rollouts progressifs

Un canal peut conserver une version stable du bundle tout en exposant progressivement une cible de lancement distincte à un groupe cohérent d'appareils. Vous pouvez mettre en pause, reprendre, promouvoir, annuler et configurer une réponse automatique à l'échec sans passer le canal pour tout le monde. Consultez Rollouts progressifs pour le modèle de livraison, flux de travail de tableau de bord, API champs, et CLI commandes.

Désactiver les stratégies d'actualisation automatique

Utilisez cela pour restreindre les types d'actualisations que le canal livrera automatiquement. Options :

majeur : bloque un ensemble cible dont la version majeure est supérieure à la base de ligne native du dispositif (version_build). Exemple : 1.2.3 -> 2.0.0 est bloqué ; 1.2.3 -> 1.9.0 est autorisé.
mineur : bloque un ensemble cible dont la version majeure ou mineure diffère de version_build. Exemple : 1.2.3 -> 1.3.0 est bloqué ; 1.2.3 -> 1.2.4 est autorisé.
patch: Mode le plus strict. Bloque toute modification du numéro majeur, mineur ou de patch. Seules les modifications de suffixe sont autorisées tandis que MAJOR.MINOR.PATCH stays identique. Exemples : 1.0.0-beta.1 -> 1.0.0-beta.2 est autorisé, 1.0.0+build.1 -> 1.0.0+build.2 est autorisé, 1.0.0 -> 1.0.1 est bloqué.
metadata: Exigez une version minimale d'actualisation de métadonnées sur chaque bundle. Configurez via CLI en utilisant --min-update-version ou --auto-min-update-version. Si manquant, le canal est marqué comme non configuré et les mises à jour seront rejetées jusqu'à ce qu'il soit configuré.
none: Autorise toutes les mises à jour selon la compatibilité de semver ces stratégies comparant le canal cible de bundle avec la base native envoyée sous la forme.

, et non le bundle téléchargé actuel envoyé sous la forme version_build, not the current downloaded bundle sent as version_name.

En savoir plus de détails et d'exemples dans la stratégie de désactivation des mises à jour à /docs/cli/commands/#disable-updates-strategy.

Exemple (CLI):

# Block major updates on the Production channel
npx @capgo/cli@latest channel set production com.example.app \
  --disable-auto-update major

# Allow devices to self-assign to the Beta channel
npx @capgo/cli@latest channel set beta com.example.app --self-assign

En utilisant setChannel() de Votre Application

Le setChannel() méthode permet à votre application de passer en mode canaux à l'exécution. Cela est particulièrement utile pour :

Menus de test/QA où les testeurs peuvent passer entre les canaux
Flux d'opt-in du programme bêta
Implémentations de drapeaux de fonctionnalité
Scénarios de tests A/B

import { CapacitorUpdater } from '@capgo/capacitor-updater';

// Switch to the beta channel
await CapacitorUpdater.setChannel({ channel: 'beta' });

// Optionally trigger an immediate update check after switching
await CapacitorUpdater.setChannel({
  channel: 'beta',
  triggerAutoUpdate: true
});

Quand setChannel() est appelé :

Validation backend (lecture seule): Une requête est envoyée vers le backend Capgo pour valider que le canal est autorisé (vérification des permissions d'auto-assignation)
Mise à jour du stockage local: Si la validation passe, le canal est enregistré dans le stockage local du dispositif comme defaultChannel
Effet instantané: La prochaine vérification de mise à jour utilise le nouveau canal immédiatement (pas d'attente pour la réplication)

Pourquoi cela compte : In les versions plus anciennes, setChannel() enregistrait la mise à jour du canal dans la base de données backend (même chose que les modifications de API ou de l'interface utilisateur de API). Les appareils devaient attendre la réplication backend (jusqu'à 2 minutes) avant que la mise à jour du canal prenne effet. Maintenant, setChannel() se contente de lire dans le backend (pour la validation) et stocke localement, ce qui rend les changements de canal instantanés.

Affichage du tableau de bord : Un canal défini avec le plugin n'oblige pas l'appareil à apparaître comme un appareil avec une mise à jour personnalisée dans l'interface utilisateur de Capgo. Seuls les affectations de canal créées à partir du tableau de bord ou de l'interface utilisateur publique de API sont listées là. Utilisez le tableau de bord ou API lorsque vous avez besoin d'une mise à jour visible par l'administrateur.

Avertissement de sécurité : Même si les permissions d'un canal changent après avoir été définies localement (par exemple, la mise à jour automatique est désactivée), le backend validera toujours le canal lors des vérifications d'actualisation, garantissant ainsi la sécurité.

Comparaison des méthodes de changement de canal :

Méthode	Temps d'effet	Persistance	Affichage dans l'interface utilisateur de mise à jour personnalisée	Utilisation de cas
`setChannel()` à partir de plugin	Instantané	Seulement appareil (local)	Non	Switch de canal initié par l'utilisateur en application
Survol de l'appareil sur le tableau de bord	Jusqu'à 2 min	Base de données backend	Oui	Modifications initiées par l'administrateur pour des appareils spécifiques
API affectation de canal	Jusqu'à 2 min	Base de données backend	Oui	Intégrations backend automatiques

Pour obtenir la meilleure expérience utilisateur lors de la création d'interfaces utilisateur de basculement de canal, utilisez toujours la méthode du plugin. setChannel() méthode.

Versions minimales pour le basculement de canal local uniquement : 5.34.0, 6.34.0, 7.34.0, ou 8.0.0 (selon votre version majeure). Chaque numéro de version mineur correspond au même ensemble de fonctionnalités dans toutes les versions majeures (par exemple, X.34.0 inclut les mêmes fonctionnalités que X est 5, 6, 7 ou 8). Consultez l'installation du plugin pour les balises de version.

Attribuer un Bundle à un Canal

Pour déployer une mise à jour en direct, vous devez télécharger un nouveau build de l'ensemble JS et l'attribuer à un canal. Vous pouvez effectuer cela en une étape avec le Capgo CLI :

npx @capgo/cli@latest bundle upload --channel=Development

Cela téléchargera vos actifs web construits et définira le nouveau bundle en tant que build actif pour le Development canal. Toutes les applications configurées pour écouter ce canal recevront la mise à jour la prochaine fois qu'elles rechercheront une.

Vous pouvez également attribuer des builds à des canaux à partir de la section « Ensembles » de la console Capgo. Cliquez sur l'icône de menu à côté d'un build et sélectionnez « Attribuer à un canal » pour choisir le canal pour ce build.

Versionnement des Ensembles et des Canaux

Il est important de noter que les ensembles dans Capgo sont mondiaux à votre application, et non spécifiques à des canaux individuels. Le même ensemble peut être attribué à plusieurs canaux.

Lors du versionnement de vos ensembles, nous recommandons l'utilisation de la versionnement semantique avec le Capgo's Tester Semver et les identifiants de version préalables pour les builds spécifiques au canal. Par exemple, une version bêta pourrait être versionnée comme 1.2.3-beta.1.

Cette approche présente plusieurs avantages :

Il communique clairement la relation entre les builds. 1.2.3-beta.1 est clairement une version préalable de 1.2.3.
Il permet de réutiliser les numéros de version dans les canaux, réduisant la confusion.
Il permet des chemins de rebond clairs. Si vous avez besoin de revenir à 1.2.3, vous savez 1.2.2 est la version stable précédente.

Voici un exemple de la façon dont vous pourriez aligner vos versions de bundle avec un schéma de canal typique :

Development canal : 1.2.3-dev.1, 1.2.3-dev.2, etc.
QA canal : 1.2.3-qa.1, 1.2.3-qa.2etc.
Staging canal : 1.2.3-rc.1, 1.2.3-rc.2etc.
Production canal : 1.2.3, 1.2.4Utilisation

l'utilisation de semver avec des identifiants de version préalables est une approche recommandée, mais pas strictement requise. La clé est de trouver un schéma de versionnement qui communique clairement les relations entre vos builds et s'aligne sur le processus de développement de votre équipe. Annuler une mise à jour en direct

Titre de la section « Annuler une mise à jour en direct »

Cliquez sur le nom du canal que vous souhaitez annuler

Click the name of the channel you want to roll back
Trouvez la construction que vous souhaitez annuler et cliquez sur l'icône de la couronne
Confirmer l'action

La construction sélectionnée deviendra immédiatement la construction active pour ce canal. Les applications recevront la version roulée-back la prochaine fois qu'elles vérifient les mises à jour.

Automatiser les déploiements

Pour des workflows plus avancés, vous pouvez automatiser vos déploiements de mise à jour en direct en tant que partie de votre pipeline CI/CD. En intégrant Capgo à votre processus de construction, vous pouvez télécharger automatiquement de nouvelles archives et les affecter à des canaux chaque fois que vous poussez vers certaines branches ou créez de nouvelles versions.

Consultez les Intégration CI/CD docs pour en savoir plus sur l'automatisation des mises à jour en direct Capgo.

Aperçus de PR avec privilèges minimal

Utilisez un Prévisualisation d'application API clé lorsqu'un CI nécessite une canal temporaire par demande de tirage mais ne doit pas gérer les canaux existants principaux/par défaut. La clé reste liée à l'organisation propriétaire et à l'application sélectionnée ; elle n'a simplement aucun rôle organisationnel. Chaque canal de prévisualisation non public qu'il crée reçoit sa propre autorisation de cycle de vie automatique, scoping au canal.

Ayez un administrateur d'organisation créer une clé sécurisée API limitée à l'application de prévisualisation et sélectionnez Prévisualisation d'application. Consultez Clés API.
Utilisez un canal unique, non public tel que pr-123. N'envoyez pas --default, --self-assign, options de déploiement, ou --delete-linked-bundle-on-upload.
Envoi et promotion du paquet de demande de tirage en une seule commande, puis supprimez le canal et le paquet propriétaire lorsque la demande de tirage est fermée :

APP_ID="com.example.app"
PREVIEW_CHANNEL="pr-123"
BUNDLE_VERSION="1.2.3-pr.123"

npx @capgo/cli@latest bundle upload "$APP_ID" \
  --apikey "$CAPGO_PREVIEW_KEY" \
  --path ./dist \
  --channel "$PREVIEW_CHANNEL" \
  --bundle "$BUNDLE_VERSION"

npx @capgo/cli@latest channel delete "$PREVIEW_CHANNEL" "$APP_ID" \
  --apikey "$CAPGO_PREVIEW_KEY" \
  --delete-bundle \
  --success-if-not-found

bundle upload --channel crée un canal manquant, envoie le bundle et le promeut en un flux. La suppression est atomique et vérifie la propriété : la clé peut supprimer uniquement un canal qu'elle a créé et son bundle lié, non partagé. Elle ne peut pas modifier, promouvoir ou supprimer un canal principal/par défaut existant, un canal d'un autre clé de prévisualisation ou un bundle d'une autre clé.

Si les réviseurs ont besoin d'un QR code ou d'une URL de prévisualisation, un administrateur doit activer les prévisualisations une fois pour l'application :

npx @capgo/cli@latest app set "$APP_ID" --preview
npx @capgo/cli@latest get-qr "$APP_ID" --channel "$PREVIEW_CHANNEL" --apikey "$CAPGO_PREVIEW_KEY" --url

Une clé de prévisualisation d'application ne peut pas activer les prévisualisations elle-même car elle n'a pas la permission d'applications. Dans GitHub Actions, exécutez les tâches de prévisualisation portant des secrets sur pull_request, pas pull_request_target, et restreignez-les aux PR de même-répertoire avec github.event.pull_request.head.repo.full_name == github.repository.

Déployer sur un appareil

Maintenant que vous comprenez les canaux, vous êtes prêt à commencer à déployer des mises à jour en direct sur des appareils réels. Le processus de base est :

Installez le Capgo SDK dans votre application
Configurez l'application pour écouter le canal que vous souhaitez
Téléchargez une mise à jour et affectez-la à ce canal
Lancez l'application et attendez l'actualisation !

Pour une présentation plus détaillée, consultez le Mise à jour en temps réel guide. Bonne mise à jour !

Utilisation avancée des canaux : segmentation des utilisateurs

Les canaux peuvent être utilisés pour plus que les étapes de développement. Ils constituent un outil puissant pour la segmentation des utilisateurs, permettant des fonctionnalités comme :

Drapeaux de fonctionnalité pour les différents niveaux d'utilisateurs
Tests A/B
Sorties progressives de fonctionnalités
Programmes de test bêta

Découvrez comment mettre en œuvre ces cas d'utilisation avancés dans notre guide : Comment segmenter les utilisateurs par plan et par canaux pour les drapeaux de fonctionnalité et les tests A/B.

Continuez de là

Si vous utilisez Canaux pour planifier la routage des canaux et la mise en production étalée, connectez-le avec Canaux pour les détails d'implémentation dans Canaux, Canaux pour les détails d'implémentation dans Canaux, Solution de test bêta pour le flux de produit dans Solution de test bêta, Solution de ciblage de version pour le flux de produit dans Solution de ciblage de version, et Capgo Pratiques d'environnement de production : mise en scène avec un ID d'application mobile unique pour le contexte pratique dans Capgo Pratiques d'environnement de production : mise en scène avec un ID d'application mobile unique.