Canaux

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

Un canal de mise à jour 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 canal de mise à jour en direct Capgo de SDK dans votre application, tout binôme natif configuré pour ce canal vérifie les mises à jour disponibles chaque fois que l'application est lancée. Vous pouvez modifier la version du paquetage que pointe le canal à tout moment et pouvez également revenir à des versions précédentes si nécessaire. Les canaux ne fournissent pas de confidentialité

Comment 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 forcée (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. Cela l'emporte toujours.
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 le serveur backend valide que le canal cible autorise l'auto-assignation. Le canal sélectionné est stocké localement sur cet appareil, prend effet instantanément et n'est pas affiché dans l'interface de surclassement 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 le serveur backend 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 l'appareil comme defaultChannel. Cela signifie que le nouveau canal prend effet instantanément pour la prochaine mise à jour, pas d'attente pour la réplication.

Jusqu'alors, setChannel() Enregistrez la surcharge de canal dans la base de données backend (comme le tableau de bord ou les modifications de API), 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 dans le backend (pour la validation) et stocke localement, ce qui rend les changements de canal instantanés.

Parce que setChannel() est local-only, il ne crée pas d'entrée de surcharge de dispositif dans le tableau de bord Capgo. L'interface de surcharge de dispositif ne montre que les surcharges créées à partir du tableau de bord ou de Public API.

Remarque : Même si un canal devient interdit après avoir été défini localement, le backend valide toujours le canal pendant les vérifications de mise à jour, ce qui maintient la sécurité.

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 (build de test par défaut) – Si présent dans capacitor.config.* et qu'aucun canal forcé/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 config defaultChannel) s'y attachent. Changez-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 pour iOS, un seul pour Android, un seul pour Electron), chaque appareil se connecte au canal 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.

Pratique recommandée :

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 seulement configurez
seulement dans les binaires que vous envoyez explicitement aux testeurs. Laisser cela non défini conserve la logique de production centralisée dans le tableau de bord. defaultChannel – Si présent dans
Utilisez setChannel() Utilisez avec parcimonie en production—principalement pour les tests de qualité ou les diagnostics ciblés.

Si un canal est désactivé pour la plateforme (iOS/Android/Electron) lorsqu'il serait autrement choisi, le processus de sélection le passe et continue dans la liste.

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

Comportement par défaut du canal

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

Un seul par défaut (la plupart des cas) – Si un canal a iOS, Android et Electron activés, il devient le seul par défaut ; tout appareil sans survol s'y attache.
Paramètres par plateforme par défaut – Si vous divisez les canaux par plateforme (par exemple, ios-production avec uniquement iOS activé, android-production avec uniquement Android activé, et electron-production avec uniquement Electron activé), marquez chaque canal comme le canal par défaut de sa plateforme. Les appareils iOS se connectent au canal par défaut iOS, les appareils Android se connectent au canal par défaut Android, et les applications Electron se connectent au canal par défaut Electron.

Rappelez-vous que le canal par défaut cloud et defaultChannel les deux occupent le même niveau de décision. Si vous définissez un canal par défaut cloud, vous n'avez pas besoin de dupliquer la valeur dans votre __CAPGO_KEEP_0__ config—laissez capacitor.config.* both occupy the same decision layer. If you set a cloud default, you don’t need to duplicate the value in your Capacitor config—leave 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 le canal par défaut cloud est différent. defaultChannel Vous pouvez modifier les canaux par défaut à tout moment dans le tableau de bord. Lorsque vous changez un canal par défaut, de nouveaux appareils suivent les nouvelles règles de routage immédiatement et les appareils existants suivent les règles de préférence normales la prochaine fois qu'ils se connectent.

Configuration d'un Canal

Platform-specific defaults

Durant l'inscription, vous créez le premier canal (la plupart des équipes le nomment « Production »), mais rien n'est bloqué – vous 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 que vous souhaitez. Une stratégie courante est de faire 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 que votre équipe de test qualité vérifie les mises à jour avant une diffusion plus large
Staging - pour le test final dans un environnement simulant la production
Production - pour la version de votre application que les utilisateurs finaux 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 bon canal. Dans cet exemple, nous utiliserons le Development canal.

Ouvrez votre capacitor.config.ts ou capacitor.config.jsonfichier. Dans la section plugins optionnellement définissez defaultChannel pour les builds de test (intérieur / QA). Pour les builds de production, préférez l'omettre afin que les appareils utilisent la valeur par défaut de Cloud, à moins qu'elle ne soit 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 le canal pour lequel ils étaient précédemment configurés.

Options et stratégies des canaux

Les canaux disposent de 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 éléments à partir de l'application web, du CLI, ou du Public API.

Canal par défaut : Marquez optionnellement les canaux ou les canaux spécifiques au plateau qui sont attachés aux nouveaux appareils. Consultez « Comportement du canal par défaut » pour les scénarios de routage.
Filtres de plateforme : Activer ou désactiver la livraison vers iOS, Androidou Electron appareils 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'auto-assignation des appareils : Permettre à l'application de passer à ce canal en temps de exécution à l'aide de setChannelSi désactivé, setChannel échouera pour ce canal.

Rollouts progressifs

A un canal peut conserver un bundle stable tout en exposant progressivement une cible de mise à jour séparée à un groupe de dispositifs collants. Vous pouvez mettre en pause, reprendre, promouvoir, annuler et configurer une réponse automatique à une erreur sans passer le canal pour tout le monde. Voir Les mises à jour progressives pour le modèle de livraison, le flux de travail de tableau de bord, les champs API et les commandes CLI.

Des stratégies de désactivation de mise à jour automatique

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

majeur : Bloc un bundle cible dont la version majeure est supérieure à la base de ligne de version native du dispositif (version_buildExemple : 1.2.3 -> 2.0.0 est bloqué; 1.2.3 -> 1.9.0 est autorisé.
mineur : Bloc un bundle cible dont la version majeure ou mineure diffère de version_buildExemple : 1.2.3 -> 1.3.0 is blocked; 1.2.3 -> 1.2.4 is 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 pendant MAJOR.MINOR.PATCH se maintient inchangé. Exemples : 1.0.0-beta.1 -> 1.0.0-beta.2 is autorisé, 1.0.0+build.1 -> 1.0.0+build.2 is autorisé, 1.0.0 -> 1.0.1 is bloqué.
metadata : Exige une version minimale d'update dans chaque bundle. Configurez via CLI à l'aide de --min-update-version ou --auto-min-update-versionSi manquant, le canal est marqué comme non configuré et les mises à jour seront rejetées jusqu'à ce qu'il soit défini.
aucune : Autorise toutes les mises à jour selon la compatibilité de ou.

Les stratégies de mise à jour de ce canal comparent la version cible du bundle contre la version native envoyée comme version_buildet non la version téléchargée actuelle envoyée comme version_name.

Découvrez 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

La setChannel() méthode permet à votre application de passer manuellement entre les canaux en temps de exécution. Cela est particulièrement utile pour :

Menus de test/QA où les testeurs peuvent passer entre les canaux
Flux d'opt-in pour les programmes bêta
Implémentations de drapeaux de fonctionnalité
Scénarios de test 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
});

Lorsque setChannel() est appelé :

Validation back-end (lecture seule): Une requête est envoyée vers le backend Capgo pour valider que le canal est autorisé (vérification des permissions d'autorisation auto)
Mise à jour de la mémoire de stockage locale: Si la validation passe, le canal est enregistré dans la mémoire de stockage locale du dispositif sous la forme de 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 : Dans les versions plus anciennes, setChannel() enregistrait la surcharge de canal dans la base de données backend (même chose que les modifications du tableau de bord ou API). Les appareils devaient attendre la réplication backend (jusqu'à 2 minutes) avant que le changement de 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 l'extension ne fait pas apparaître l'appareil comme une surcharge de dispositif dans l'interface utilisateur Capgo. Seuls les affectations de canal créées à partir du tableau de bord ou de l'instance publique API sont listées là. Utilisez le tableau de bord ou API lorsque vous avez besoin d'une surcharge visible par l'administrateur.

Note de sécurité : Même si les permissions d'un canal changent après avoir été définies localement (par exemple, la self-assignment est désactivée), le backend validera toujours le canal lors des vérifications de mise à jour, ce qui garantit la sécurité.

Comparaison des méthodes de changement de canal :

Méthode	Temps d'effet	Persistance où	Affiché dans l'interface de surclassement de l'appareil	Utilisation
`setChannel()` from plugin	Instantané	Seulement sur appareil (local)	Non	Switchement de canal initié par l'utilisateur en application
Tableau de bord de surclassement de l'appareil	Jusqu'à 2 min	Base de données backend	Oui	Mises à jour effectuées par l'administrateur pour des appareils spécifiques
API affectation du 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 de UIs de changement de canal, utilisez toujours la méthode du plugin. setChannel() Versions minimales pour le changement de canal local uniquement :

ou 5.34.0, 6.34.0, 7.34.0(selon votre version majeure). Chaque numéro de version mineure 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 8.0.0 plugin installation plugin installation pour les étiquettes de version.

Attribuer un Bundle à un Canal

Pour déployer une mise à jour en direct, vous devez télécharger un nouveau build de bundle JS et l'attribuer à un canal. Vous pouvez faire cela en une seule é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. Tous les applications configurées pour écouter ce canal recevront la mise à jour la prochaine fois qu'elles vérifieront une.

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

Numérotation des versions de Bundle et des Canaux

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

When vous gérez les versions de vos ensembles, nous vous recommandons d'utiliser la versionnement semantique avec Capgo’s Tester Semver et les identifiants de pré-version pour les builds spécifiques au canal. Par exemple, une version bêta pourrait être versionnée comme 1.2.3-beta.1.

En CI, si la version locale était déjà téléchargée, utilisez npx @capgo/cli@latest bundle upload --auto-bump (facultatif) major, minor, patch/fix, metadata, ou ai) afin que CLI augmente de la version du canal liée à l'ensemble jusqu'à trouver un nom gratuit. Avec ai, Workers AI infère le niveau à partir du delta local par rapport au manifeste précédent (retourne à patch avec aucune version précédente Capgo). Vous ne pouvez pas le combiner avec --bundle. Consultez et le CI/CD Integration CLI référence.

Cette approche présente plusieurs avantages :

Cela communique clairement la relation entre les builds. 1.2.3-beta.1 est manifestement une préversion de 1.2.3.
Cela permet de réutiliser les numéros de version dans plusieurs canaux, réduisant la confusion.
Cela permet des chemins de reversion clairs. Si vous avez besoin de revenir à 1.2.3Vous savez que 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 une configuration de canal typique :

Development canal : 1.2.3-dev.1, 1.2.3-dev.2etc.
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.4etc.

Utilisation de semver avec des identifiants de pré-version 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

Si vous déployez une mise à jour en direct qui introduit une erreur ou doit être annulée, vous pouvez facilement revenir à une version précédente. Dans la section « Canaux » de la console :

Cliquez sur le nom du canal que vous souhaitez annuler
Trouvez la version de construction que vous souhaitez annuler et cliquez sur l'icône de couronne
Confirmer l'action

La version de construction sélectionnée deviendra immédiatement la version 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.

Découvrez les Intégration CI/CD docs to learn more about automating Capgo live updates.

docs pour en savoir plus sur l'automatisation des mises à jour __CAPGO_KEEP_0__ en direct.

Utilisez une 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 principaux/existants. La clé reste liée à l'organisation propriétaire et à l'application sélectionnée ; elle n'a tout simplement pas de rôl’organisationnel. Chaque canal de prévisualisation non public qu'elle crée reçoit ses propres autorisations de cycle de vie automatiques, scoping le canal.

Disposez d'un administrateur d'organisation pour créer une clé sécurisée API limitée à l'application de prévisualisation et sélectionnez Prévisualisation d'application. Consultez API Clés.
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.
Téléchargez et promouvez le bundle de la demande de tirage en une seule commande, puis supprimez le canal et le bundle propriétés 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, télécharge le bundle et le promeut en une seule opération. La suppression est atomique et vérifie l'appartenance : 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/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'application-settings. 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 live sur des appareils réels. Le processus de base est :

Installez le Capgo SDK dans votre application
Configurez l'application pour écouter votre canal souhaité
Chargement d'une build et affectation à ce canal
Lancez l'application et attendez l'actualisation !

Pour une présentation plus détaillée, consultez le guide « Déploiement des mises à jour en direct ». guide. Bonne mise à jour ! Utilisation avancée des canaux : segmentation des utilisateurs

Sous-titre « Utilisation avancée des canaux : segmentation des utilisateurs »

Drapeaux de fonctionnalité pour les différents niveaux d'utilisateurs

Tests A/B
Rollout progressif de fonctionnalités
Deploying Live Updates
Programmes de test bêta

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

Continuez de la section Canaux

Si vous utilisez Canaux context : nom de fonctionnalité de canaux de mise à jour de Capgo. Page/zone : page de marketing de solutions de Capgo. Rôle : étiquette de navigation ou élément de navigation court. Vu dans : page solutions/white-label.astro. Clé de message `solutions_white_label_visual_cell2_value` (Valeur de cellule visuelle de Solutions White Label) Connectez-l’à Canaux context : nom de fonctionnalité de canaux de mise à jour de Capgo. Page/zone : page de marketing de solutions de Capgo. Rôle : étiquette de navigation ou élément de navigation court. Vu dans : page solutions/white-label.astro. Clé de message `solutions_white_label_visual_cell2_value` (Valeur de cellule visuelle de Solutions White Label) détails d'implémentation dans Canaux, : « Canal », Solution de Test Beta pour le flux de workflow du produit dans Solution de Test Beta Solution de Ciblage de Version pour le flux de workflow du produit dans Solution de Ciblage de Version, et Capgo Pratiques d'Environnement : Étapes de Staging avec Un ID d'Application Mobile pour le contexte pratique dans Capgo Pratiques d'Environnement : Étapes de Staging avec Un ID d'Application Mobile.