Ciblage de version

Ce guide explique comment livrer automatiquement le dernier bundle compatible aux utilisateurs selon la version de leur application native, similaire à l'approche d'Ionic AppFlowCela permet de simplifier la gestion des mises à jour et d'accélérer les déploiements progressifs tout en évitant les problèmes de compatibilité.

Vous migrez depuis Ionic AppFlow ?

Si vous utilisez Ionic AppFlow, ce guide est particulièrement important pour vous. AppFlow associait automatiquement les mises à jour aux versions natives, et Capgo offre la même fonctionnalité avec encore plus de contrôl’et de flexibilité. Consultez le Guide de migration AppFlow pour des instructions de migration étape par étape.

Aperçu

Le système de ciblage de version de Capgo vous permet de :

• Livrer automatiquement des mises à jour compatibles aux utilisateurs selon la version native de leur application
• Empêcher les breaking changes d'atteindre des versions d'application incompatibles
• Gérer plusieurs versions d'application simultanément sans logique complexe
• Déployez vos mises à jour en douceur vers des segments d'utilisateurs spécifiques

Pourquoi le ciblage de version est crucial (surtout pour les utilisateurs d'AppFlow)

Si vous connaissez déjà Ionic AppFlow, vous savez à quel point il est critique de s'assurer que les utilisateurs ne reçoivent que des mises à jour compatibles. AppFlow associait automatiquement les bundles live update aux versions natives de l'app, évitant ainsi l'envoi de JavaScript incompatible à d'anciens code natifs.

Capgo offre les mêmes garanties de sécurité, avec des fonctionnalités supplémentaires :

• Un contrôle plus granulaire de l'appariement des versions
• Plusieurs stratégies (canaux, semver, contraintes natives)
• Une meilleure visibilité sur la distribution des versions
• API et CLI sont pilotés avec la gestion du dashboard

Cette approche est particulièrement utile quand :

• Vos utilisateurs utilisent différentes versions majeures de votre app (ex: v1.x, v2.x, v3.x)
• Vous devez maintenir la compatibilité ascendante lors du déploiement de changements majeurs
• Vous voulez éviter que des bundles récents ne cassent d'anciens code natifs
• Vous migrez progressivement vos utilisateurs d'une version à une autre
• Vous migrez depuis AppFlow et souhaitez maintenir la même sécurité lors des mises à jour

Comment ça marche

Capgo utilise une approche multicouche pour associer les utilisateurs aux mises à jour compatibles :

1. Contraintes de version native: Empêcher la livraison de bundles à des versions natives incompatibles
2. Routage par canal: Diriger différentes versions de l'app vers différents canaux de Live Update
3. Contrôles de versionnage sémantique: Bloquer automatiquement les mises à jour entre versions majeures/mineures/patch
4. Overrides par appareil: Target specific devices or user groups

Flux de correspondance des versions

graph TD
    A[User Opens App] --> B{Check Device Override}
    B -->|Override Set| C[Use Override Channel]
    B -->|No Override| D{Check local plugin channel}
    D -->|setChannel value| E[Use local setChannel channel]
    D -->|No local channel| F{Check defaultChannel in App}
    F -->|Has defaultChannel| G[Use App's defaultChannel]
    F -->|No defaultChannel| H[Use Cloud Default Channel]
    C --> I{Check Version Constraints}
    E --> I
    G --> I
    H --> I
    I -->|Compatible| J[Deliver Update]
    I -->|Incompatible| K[Skip Update]

Stratégie 1 : routage des versions par canal

C'est la méthode recommandée pour gérer les breaking changes et les mises à jour de versions majeures. C'est un modèle similaire à celui d'AppFlow.

Exemple de scénario

• App v1.x (100 000 utilisateurs) → production canal
• App v2.x (50 000 utilisateurs avec breaking changes) → v2 canal
• App v3.x (10 000 utilisateurs bêta) → v3 canal

Implémentation

Étape 1 : Configurer les canaux pour chaque version majeure

// capacitor.config.ts for version 1.x builds
import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example App',
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      defaultChannel: 'production', // or omit for default
    }
  }
};

export default config;

// capacitor.config.ts for version 2.x builds
const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example App',
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      defaultChannel: 'v2', // Routes v2 users automatically
    }
  }
};

// capacitor.config.ts for version 3.x builds
const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example App',
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      defaultChannel: 'v3', // Routes v3 users automatically
    }
  }
};

Étape 2 : Créer des canaux

# Create channels for each major version
npx @capgo/cli channel add production
npx @capgo/cli channel add v2
npx @capgo/cli channel add v3

# Enable self-assignment so apps can switch channels
npx @capgo/cli channel set production --self-assign
npx @capgo/cli channel set v2 --self-assign
npx @capgo/cli channel set v3 --self-assign

Étape 3 : Envoyer des bundles spécifiques à la version

# For v1.x users (from v1-maintenance branch)
git checkout v1-maintenance
npm run build
npx @capgo/cli bundle upload --channel production

# For v2.x users (from v2-maintenance or main branch)
git checkout main
npm run build
npx @capgo/cli bundle upload --channel v2

# For v3.x users (from beta/v3 branch)
git checkout beta
npm run build
npx @capgo/cli bundle upload --channel v3

Routage automatique

Lorsque les utilisateurs ouvrent l'app, ils se connectent automatiquement au canal désigné selon la defaultChannel dans leur bundle d'app installé. Aucun changement de code JavaScript requis !

Avantages

• Zéro changement de code - Le routage par canal est automatique
• Séparation claire - Chaque version possède son propre pipeline de mise à jour
• Ciblage flexible - Push updates to specific version groups
• Déploiements progressifs sécurisés - Les changements incompatibles n'atteignent jamais les versions obsolètes

Stratégie 2 : contrôles du versionnage sémantique

Utilisez la fonctionnalité intégrée de Capgo le versionnage sémantique contrôle pour éviter les mises à jour entre versions incompatibles.

Désactiver l'auto-update entre les versions majeures

# Create a channel that blocks major version updates
npx @capgo/cli channel add stable
npx @capgo/cli channel set stable --disable-auto-update major

Cette configuration signifie :

• Les utilisateurs de la version d'app 1.2.3 recevront des mises à jour jusqu'à 1.9.9
• Les utilisateurs PAS recevront la version 2.0.0 automatiquement
• Empêche les breaking changes d'atteindre les anciens code natifs
• La comparaison utilise la baseline native envoyée comme version_build

Options de contrôle granulaire

# Block target bundles outside the native major.minor line (1.2.x won't get 1.3.0)
npx @capgo/cli channel set stable --disable-auto-update minor

# Block target bundles outside the exact native MAJOR.MINOR.PATCH core (1.2.3 won't get 1.2.4)
npx @capgo/cli channel set stable --disable-auto-update patch

# Allow all updates
npx @capgo/cli channel set stable --disable-auto-update none

Versionnage sémantique requis

Cette stratégie ne fonctionne que si vous respectez le versionnage sémantique (semver) pour les versions de votre app. Assurez-vous que vos numéros de version suivent le MAJOR.MINOR.PATCH format.

Stratégie 3 : contraintes de version native

Spécifiez une version minimale de l'application native (min_update_version) sur chaque bundle pour que Capgo ne l'envoie qu'aux appareils dont le binaire natif est assez récent.

Cela utilise la stratégie metadata (--disable-auto-update metadata) ainsi que --min-update-version ou --auto-min-update-version lors de l'upload. Il n'y a pas de --native-version flag CLI.

Activer le ciblage par métadonnées sur le canal

# one-time: require min_update_version metadata on uploads to this channel
npx @capgo/cli@latest channel set production --disable-auto-update metadata

Définir une version native minimale lors de l'upload

Lors de l'upload d'un bundle, indiquez la version native la plus basse susceptible de le recevoir :

# This bundle requires native version 2.0.0 or higher
npx @capgo/cli@latest bundle upload \
  --channel production \
  --min-update-version "2.0.0"

Ou laissez Capgo définir le seuil selon la compatibilité du package natif :

npx @capgo/cli@latest bundle upload \
  --channel production \
  --auto-min-update-version

Comment ça marche

Avec la stratégie de métadonnées, les appareils dont la base native (version_build) est inférieure à celle du bundle min_update_version ignorez la mise à jour. Seuls les appareils sur cette version ou une version supérieure la recevront. Voir Compatibilité pour --auto-min-update-version détails.

Cas d’usage

1. Nouveau plugin natif requis

   # Bundle needs Camera plugin added in v2.0.0
   npx @capgo/cli@latest bundle upload \
     --channel production \
     --min-update-version "2.0.0"

2. Changements incompatibles de l’API native

   # Bundle uses new Capacitor 6 APIs
   npx @capgo/cli@latest bundle upload \
     --channel production \
     --min-update-version "3.0.0"

3. Migration progressive

   # one-time: enable metadata gating on beta
   npx @capgo/cli@latest channel set beta --disable-auto-update metadata
   
   # Test bundle only on latest native version
   npx @capgo/cli@latest bundle upload \
     --channel beta \
     --min-update-version "2.5.0"

Stratégie 4 : prévenir le downgrade automatique

Empêchez les utilisateurs de recevoir des bundles plus anciens que leur version native actuelle.

Activer dans les paramètres du canal

Dans le dashboard Capgo :

1. Accéder à Canaux → Sélectionnez votre canal
2. Activer « Désactiver le downgrade auto en natif »
3. Enregistrer les modifications

Ou via CLI :

npx @capgo/cli@latest channel set production --no-downgrade

Exemple

• Appareil de l'utilisateur : version native 1.2.5
• Bundle du canal : version 1.2.3
• Résultat: La mise à jour est bloquée (ce serait un downgrade)

C'est utile quand :

• Les utilisateurs ont installé manuellement une version plus récente depuis le store
• Vous devez garantir que les utilisateurs ont toujours les derniers correctifs de sécurité
• Vous voulez éviter les bugs de régression

Stratégie 5 : Ciblage au niveau de l'appareil

Remplacez l'assignation du canal pour des appareils ou des groupes d'utilisateurs spécifiques.

Forcer une version spécifique pour les tests

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

// Force beta testers to use v3 channel
async function assignBetaTesters() {
  const deviceId = await CapacitorUpdater.getDeviceId()

  // Check if user is beta tester
  if (isBetaTester(userId)) {
    await CapacitorUpdater.setChannel({ channel: 'v3' })
  }
}

Override d'appareil depuis le dashboard

Dans le dashboard Capgo :

1. Accéder à Appareils → Rechercher un appareil
2. Cliquez Définir le canal ou Définir la version
3. Forcer un canal ou une version de bundle spécifique
4. L'appareil recevra les mises à jour depuis la source définie

Tester les mises à jour

Utilisez les overrides d'appareil pour tester les mises à jour sur votre propre appareil avant de déployer à tous les utilisateurs.

Workflow complet de type AppFlow

Voici un exemple complet combinant toutes les stratégies :

1. Configuration initiale (App v1.0.0)

# Create production channel, then enable metadata min-version gating
npx @capgo/cli@latest channel add production
npx @capgo/cli@latest channel set production \
  --disable-auto-update metadata \
  --no-downgrade

capacitor.config.ts

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      defaultChannel: 'production',
    }
  }
};

2. Publier un breaking change (App v2.0.0)

# Create v2 channel for new version
npx @capgo/cli@latest channel add v2
npx @capgo/cli@latest channel set v2 \
  --disable-auto-update metadata \
  --no-downgrade \
  --self-assign

# Create git branch for v1 maintenance
git checkout -b v1-maintenance
git push origin v1-maintenance

// capacitor.config.ts for v2.0.0
const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      defaultChannel: 'v2', // New users get v2 channel
    }
  }
};

3. Envoyer des mises à jour aux deux versions

# Update v1.x users (bug fix)
git checkout v1-maintenance
# Make changes
npx @capgo/cli@latest bundle upload \
  --channel production \
  --min-update-version "1.0.0"

# Update v2.x users (new feature)
git checkout main
# Make changes
npx @capgo/cli@latest bundle upload \
  --channel v2 \
  --min-update-version "2.0.0"

4. Surveiller la distribution des versions

Utilisez le dashboard Capgo pour suivre :

• Nombre d'utilisateurs sur la v1 vs v2
• Taux d'adoption des bundles par version
• Erreurs ou crashs par version

5. Déprécier l'ancienne version

Une fois que l'usage de la v1 passe sous le seuil :

# Stop uploading to production channel
# Optional: Delete v1 maintenance branch
git branch -d v1-maintenance

# Move all remaining users to default
# (They'll need to update via app store)

Priorité des canaux

Lorsque plusieurs configurations de canaux existent, Capgo utilise cet ordre de priorité :

1. Surcharge de l'appareil (Dashboard ou API) - Priorité maximale, visible dans l'UI Device Override
2. Canal du plugin local via setChannel() - Stocké uniquement sur l'appareil et non affiché dans l'UI Device Override
3. defaultChannel dans capacitor.config.ts
4. Canal par défaut (Paramètre cloud) - Priorité la plus basse

Exemple de priorité

Si l'application d'un utilisateur a defaultChannel: 'v2' mais que vous forcez son appareil vers 'beta' dans le dashboard, ils recevront les mises à jour du 'beta' canal.

L'interface Device Override liste uniquement les overrides configurés via le dashboard ou l’API public. L'appel setChannel() depuis l'app valide le canal auprès du backend, puis le stocke localement sur l'appareil.

Bonnes pratiques

1. Toujours définir defaultChannel pour les versions majeures

// ✅ Good: Each major version has explicit channel
// v1.x → production
// v2.x → v2
// v3.x → v3

// ❌ Bad: Relying on dynamic channel switching
// All versions → production, switch manually

2. Utiliser le versionnage sémantique

# ✅ Good
1.0.0 → 1.0.1 → 1.1.0 → 2.0.0

# ❌ Bad
1.0 → 1.1 → 2 → 2.5

3. Maintenir des branches séparées

# ✅ Good: Separate branches per major version
main (v3.x)
v2-maintenance (v2.x)
v1-maintenance (v1.x)

# ❌ Bad: Single branch for all versions

4. Tester avant le déploiement progressif

# one-time: create beta and enable metadata gating
# (production is set up in the complete workflow above)
npx @capgo/cli@latest channel add beta
npx @capgo/cli@latest channel set beta --disable-auto-update metadata

# Test on beta channel first
npx @capgo/cli@latest bundle upload \
  --channel beta \
  --auto-min-update-version

# Monitor for issues, then promote to production
npx @capgo/cli@latest bundle upload \
  --channel production \
  --auto-min-update-version

5. Surveiller la distribution des versions

Consultez régulièrement votre dashboard :

• Les utilisateurs passent-ils aux nouvelles versions natives ?
• Les anciennes versions reçoivent-elles encore beaucoup de trafic ?
• Devriez-vous supprimer les anciens canaux ?

Comparaison avec Ionic AppFlow

Pour les équipes migrant de Ionic AppFlowvoici comment se compare le ciblage de version de Capgo :

Fonctionnalité	Ionic AppFlow	Capgo
Routage basé sur la version	Automatique selon la version native	Automatique via defaultChannel + plusieurs stratégies
Versionnage sémantique	Support de base	Avancé avec --disable-auto-update (majeur/mineur/patch)
Contraintes de version native	Configuration manuelle dans le dashboard AppFlow	Intégré --min-update-version / --auto-min-update-version avec des canaux de métadonnées
Gestion des canaux	Interface Web + CLI	Interface Web + CLI + API
Overrides par appareil	Contrôle limité par appareil	Contrôle total via le Dashboard/API
Prévention du downgrade automatique	Oui	Oui via --no-downgrade
Maintenance multi-versions	Gestion manuelle des branches/canaux	Automatisée avec priorité des canaux
Auto-hébergement	Non	Oui (contrôle total)
Analyses des versions	Basique	Métriques détaillées par version

Équivalent AppFlow et plus encore

Capgo offre toutes les capacités de ciblage de version proposées par AppFlow, avec des mécanismes de contrôle supplémentaires. Si vous utilisiez le matching automatique d'AppFlow, vous trouverez Capgo tout aussi fiable, avec plus de flexibilité.

Troubleshooting

Les utilisateurs ne reçoivent pas les mises à jour

Vérifiez les points suivants :

1. Assignation du canal: Vérifiez que l'appareil est sur le bon canal

   const channel = await CapacitorUpdater.getChannel()
   console.log('Current channel:', channel)

2. Contraintes de version: Vérifiez si le bundle a des exigences de version native

   • Dashboard → Bundles → Vérifiez la colonne « Native Version »

3. Paramètres Semver: Vérifiez les paramètres du canal disable-auto-update paramètre

   npx @capgo/cli channel list

4. Override de l'appareil: Vérifier si l'appareil possède un override manuel

   • Dashboard → Devices → Rechercher l'appareil → Vérifier le canal/la version

Bundle livré à la mauvaise version

1. Réviser le defaultChannel: S'assurer que le bon canal est configuré capacitor.config.ts
2. Vérifier l'upload du bundle: Vérifier que le bundle a été envoyé au bon canal
3. Inspecter la version minimale de mise à jour: Confirmer --min-update-version (ou --auto-min-update-version) a été défini et le canal utilise --disable-auto-update metadata

Changements majeurs sur les anciennes versions

1. Correction immédiate: Forcer les appareils concernés vers un bundle sûr
   • Dashboard → Appareils → Sélection groupée → Définir la version
2. Correction à long terme: Créer des canaux versionnés et maintenir des branches séparées
3. Prévention: Always test updates on representative devices before rollout

Migration depuis Ionic AppFlow

Si vous migrez depuis Ionic AppFlow, le ciblage par version fonctionne de façon très similaire dans Capgo, avec une flexibilité accrue :

Correspondance des concepts

Concept AppFlow	Équivalent Capgo	Notes
Canal de déploiement	Canal Capgo	Même concept, plus puissant
Verrouillage de version native	--min-update-version / --auto-min-update-version	Contrôle plus granulaire
Priorité des canaux	Précédence des canaux (surcharge → cloud → par défaut)	Précédence plus transparente
Cible de déploiement	Contrôles par canal + semver	Plusieurs stratégies disponibles
Canal de production	production canal (ou n'importe quel nom)	Nommage flexible
Déploiement basé sur Git	Upload du bundle CLI depuis une branche	Même workflow
Correspondance automatique des versions	defaultChannel + contraintes de version	Optimisé avec plusieurs stratégies

Différences clés pour les utilisateurs d'AppFlow

1. Plus de contrôleCapgo vous offre plusieurs stratégies (canaux, semver, version native) qui peuvent être combinées
2. Meilleure visibilitéLe dashboard affiche la répartition des versions et les problèmes de compatibilité
3. Accès API: Contrôle programmatique total du ciblage de version
4. Auto-hébergement: Option pour héberger votre propre serveur de mise à jour avec la même logique de version

Étapes de migration

1. Mappez vos canaux AppFlow vers les canaux Capgo (généralement 1:1)
2. Définissez defaultChannel dans capacitor.config.ts pour chaque version majeure
3. Configurez les règles semver si vous souhaitez un blocage automatique aux limites de version
4. Envoyer des bundles spécifiques à une version en utilisant --min-update-version (le canal doit utiliser une stratégie de métadonnées)
5. Surveiller la distribution des versions dans le dashboard Capgo

Guide de migration complet

Pour des instructions de migration complètes, incluant le remplacement de SDK et le mapping de API, consultez le Guide de migration d'AppFlow vers Capgo.

Patterns avancés

Déploiement progressif par version

// Gradually migrate v1 users to v2
async function migrateUsers() {
  const deviceId = await CapacitorUpdater.getDeviceId()
  const rolloutPercentage = 10 // Start with 10%

  // Hash device ID to get deterministic percentage
  const hash = hashCode(deviceId) % 100

  if (hash < rolloutPercentage) {
    // User is in rollout group - migrate to v2
    await CapacitorUpdater.setChannel({ channel: 'v2' })
  }
}

Feature flags par version

// Enable features based on native version
async function checkFeatureAvailability() {
  const info = await CapacitorUpdater.getDeviceId()
  const nativeVersion = info.nativeVersion

  if (compareVersions(nativeVersion, '2.0.0') >= 0) {
    // Enable features requiring v2.0.0+
    enableNewCameraFeature()
  }
}

A/B testing entre les versions

// Run A/B tests within same native version
async function assignABTest() {
  const nativeVersion = await getNativeVersion()

  if (nativeVersion.startsWith('2.')) {
    // Only A/B test on v2 users
    const variant = Math.random() < 0.5 ? 'v2-test-a' : 'v2-test-b'
    await CapacitorUpdater.setChannel({ channel: variant })
  }
}

Résumé

Capgo propose plusieurs stratégies pour diffuser des mises à jour par version :

1. Routage par canal: Séparation automatique des versions via defaultChannel
2. Versionnage sémantique: Empêcher les mises à jour entre versions majeures/mineures/patch
3. Contraintes de version native: Exiger une version native minimale pour les bundles
4. Prévention du downgrade automatique: Ne jamais livrer de bundles plus anciens à des versions natives plus récentes
5. Overrides par appareil: Contrôle manuel pour les tests et le ciblage

En combinant ces stratégies, vous pouvez obtenir une livraison automatique de mises à jour de type AppFlow avec encore plus de flexibilité et de contrôle. Choisissez l'approche qui correspond le mieux au versioning et au workflow de déploiement de votre app.

For more details on specific features:

• Guide des breaking changes - Stratégie détaillée de versioning par canal
• Gestion des canaux - Référence complète de configuration des canaux
• Comportement de mise à jour - Délais et conditions des versions natives

Continuer avec le ciblage par version

Si vous utilisez Ciblage de version 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, Canaux pour les détails d'implémentation des canaux, Solution de bêta-test pour le workflow produit de la Solution de bêta-test, et Solution de ciblage de version pour le workflow produit de la Solution de ciblage de version.