Passer à la navigation

Canaux

Un canal d'actualisation en temps réel pointe vers une version spécifique du build 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 Live Updates 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.

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

Section intitulée “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) :

  1. Cartographie de l'appareil (Tableau de bord) – Fixer manuellement un ID d'appareil spécifique à un canal. Utilisez pour des débogages urgents ou des tests contrôlés avec un seul utilisateur réel. Cela l'emporte toujours.
  2. 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 de la binary ne le supprime pas ; la suppression de l'entrée de l'appareil le supprime.
  3. Plugin setChannel() canal local – Créé lorsque l'application appelle setChannel() et le serveur back-end 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.
  1. Capacitor config defaultChannel (test build default) – Si présent dans capacitor.config.* et si aucun canal de force/prise en charge/interne 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.
  2. Canal par défaut Cloud (chemin principal ~99% des utilisateurs) – If you mark a default channel in the dashboard, all normal end‑users (no force, no Dashboard/API override, no plugin local channel, no config defaultChannel) attach here. Change it to roll out or roll back instantly—no new binary. If you have platform-specific defaults (for example, one iOS-only, one Android-only, one Electron-only), each device lands on the default matching its platform. Leaving the cloud default unset is allowed; in that case the device must match on steps 1–4 to receive updates.

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 y fluer. 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 ou des surcharges par appareil).
  • Configurez uniquement defaultChannel dans les fichiers binaires que vous envoyez explicitement aux testeurs. Laisser cela non défini garde la logique de production centralisée dans l'interface de dashboard.
  • Utilisez setChannel() rarement en production—principalement pour les tests 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 saute et continue dans la liste.

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

La définition d'un par défaut cloud 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 config Capacitor recevront des mises à jour. Lorsque vous choisissez de marquer des valeurs par défaut, gardez ces modèles à l'esprit :

  • Un seul par défaut (le plus courant) – Si un canal a iOS, Android et Electron activés, il devient le seul par défaut ; tout appareil sans survol attachera ici.
  • Par défauts spécifiques à la plateforme – 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 défaut pour sa plateforme. Les appareils iOS se dirigent vers le canal par défaut iOS, les appareils Android se dirigent vers le canal par défaut Android, et les applications Electron se dirigent vers le canal par défaut Electron. defaultChannel N'oubliez pas que le canal par défaut dans le cloud et capacitor.config.* s'occupent de la même couche de décision. Si vous définissez un canal par défaut dans le cloud, vous n'avez pas besoin de dupliquer la valeur dans votre Capacitor config—la laissez 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 le canal par défaut dans le cloud est différent. defaultChannel Vous pouvez modifier les défauts à tout moment dans le tableau de bord. Lorsque vous changez un canal par défaut, les nouveaux appareils suivent les nouvelles règles de routage immédiatement et les appareils existants suivent les règles de priorité normales la prochaine fois qu'ils se connectent.

Configuration d'un Canal

Titre de la section « Configuration d'un Canal »

Setting up a Channel

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

  1. Allez dans la section « Canaux » du tableau de bord Capgo
  2. Cliquez sur le bouton « Nouveau Canal »
  3. 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 faire correspondre les canaux à vos étapes de développement, telles que :

  • 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 diffusion 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

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

Ouvrez votre capacitor.config.ts (ou capacitor.config.json) fichier. Sous la plugins section, configurez optionnellement 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 sauf si elle est explicitement modifié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 vers vos projets iOS, Android et Electron. Si vous passez cette étape de synchronisation, vos projets natifs continueront à utiliser la chaîne de canal qu'ils étaient configurés pour.

Les chaînes 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, de l'CLI, ou de l'API Public.

  • Chaîne par défaut : Marquez facultativement la chaîne ou les canaux spécifiques au plateau qui les nouveaux appareils s'attachent. Voir “Comportement de la chaîne par défaut” pour les scénarios de routage.
  • Filtres de plateforme : Activer ou désactiver la livraison vers iOS, Android, ou 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 : Permet à l'application de passer à ce canal en temps de exécution à l'aide de setChannel. Si désactivé, setChannel échouera pour ce canal.

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

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

  • majeur : Bloc un bundle 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 : Bloc un bundle 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 se maintient 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'update 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 défini.
  • aucune : Autorise toutes les mises à jour selon la compatibilité de semver compare les stratégies du canal cible contre la base native envoyée sous forme de.

metadata: Require a minimum update version metadata on each bundle. Configure via __CAPGO_KEEP_0__ using version_buildpas le bundle téléchargé actuellement envoyé comme 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-stratégie.

Exemple (CLI):

Fenêtre de terminal
# 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() à partir de Votre Application

Section intitulée “En utilisant setChannel() à partir de Votre Application”

Le setChannel() La 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 du programme bêta
  • Mise en œuvre des 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
});

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 effectuer cela en une étape avec le Capgo CLI:

Fenêtre de terminal
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 mise à jour.

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 à un Canal » pour choisir le canal pour ce build.

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.

Lorsque vous versionnez vos bundles, nous vous recommandons de utiliser la gestion de version avec Capgo’s Semver Tester et des identificateurs 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.

Cet approche présente plusieurs avantages :

  • Elle communique clairement la relation entre les builds. 1.2.3-beta.1 est clairement une version préalable de 1.2.3.
  • Cela permet de réutiliser les numéros de version dans différents canaux, réduisant la confusion.
  • Cela permet des chemins de rebond clairs. Si vous avez besoin de revenir à 1.2.3, vous 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 un setup 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.4etc.

Utilisation 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.

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

  1. Cliquez sur le nom du canal que vous souhaitez remonter
  2. Trouvez la build que vous souhaitez rétablir et cliquez sur l'icône de couronne Remontage de build
  3. Confirmer l'action

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

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 build, vous pouvez télécharger automatiquement de nouvelles archives et les affecter à des canaux chaque fois que vous poussez sur 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 Capgo en direct.

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

  1. Ayez un administrateur d'organisation créer une clé API sécurisée limitée à l'application de prévisualisation et sélectionnez Prévisualisation d'application. Voir Clés API.
  2. Utilisez un canal unique et non public tel que pr-123. N'envoyez pas --default, --self-assign, options de déploiement, ou --delete-linked-bundle-on-upload.
  3. 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 :
Onglet de terminal
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 changer, promouvoir ou supprimer un canal existant par défaut ou un canal d'un autre clé de visionnage, ou un bundle d'une autre clé.

Si les réviseurs ont besoin d'un QR code ou d'une URL de visionnage, un administrateur doit activer les aperçus une fois pour l'application :

Onglet de terminal
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 visionnage d'application ne peut pas activer les aperçus elle-même car elle n'a pas la permission d'application-settings. Dans GitHub Actions, exécutez les tâches de visionnage secrètes sur pull_requestpas pull_request_targetet restreignez-les aux PR de même-répertoire avec github.event.pull_request.head.repo.full_name == github.repository.

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 :

  1. Installez le Capgo SDK dans votre application
  2. Configurez l'application pour écouter votre canal souhaité
  3. Envoyez une mise à jour et affectez-la à ce canal
  4. Lancez l'application et attendez l'actualisation !

Pour une présentation détaillée, consultez le Déploiement des mises à jour en temps réel guide. Bonne mise à jour !

Utilisation avancée des canaux : segmentation des utilisateurs

Sous-section intitulée “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 différents niveaux d'utilisateurs
  • Tests A/B
  • Déploiements de fonctionnalités progressives
  • 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és et les tests A/B.

Continuez de la section « Continuez de la section Canaux »

Si vous utilisez

Canaux pour planifier la routage des canaux et le déploiement étalé, connectez-le avec Canaux pour les détails d'implémentation dans Canaux, Canaux Si vous utilisez Canaux pour les détails d'implémentation dans les canaux, Solution de test bêta pour le flux de travail du produit dans la Solution de test bêta, Solution de ciblage de version pour le flux de travail du produit dans la Solution de ciblage de version, et Capgo Pratiques de l'environnement : Étapes avec un seul ID d'application mobile pour le contexte pratique dans Capgo Pratiques de l'environnement : Étapes avec un seul ID d'application mobile.