Ciblage de version

Cette guide explique comment livrer automatiquement la dernière version compatible du bundle aux utilisateurs en fonction de leur version d'application native, de manière similaire à l'approche d'Ionic AppFlow. Cela garantit une gestion simplifiée des mises à jour et des déploiements rapides tout en évitant les problèmes de compatibilité.

Migrer depuis Ionic AppFlow?

Si vous venez de Ionic AppFlow, ce guide est particulièrement important pour vous. AppFlow a automatiquement mis en correspondance les mises à jour avec les versions natives, et Capgo offre la même capacité avec encore plus de contrôle et de flexibilité. Consultez le Guide de migration vers AppFlow pour des instructions de migration étape par étape.

Vue d'ensemble

Capgo’s version targeting system allows you to:

• aux utilisateurs en fonction de leur version d'application native Prévenir les modifications de rupture
• Section intitulée “Vue d'ensemble” pour éviter les versions d'applications incompatibles
• Gérer plusieurs versions d'applications sans logique complexe
• Mettre en œuvre des mises à jour sans heurt à des segments d'utilisateurs spécifiques

Pourquoi la ciblage de version est important (Surtout pour les utilisateurs d'AppFlow)

Si vous êtes familier avec Ionic AppFlow, vous savez à quel point il est crucial de s'assurer que les utilisateurs reçoivent uniquement des mises à jour compatibles. AppFlow a automatiquement associé des lots de mise à jour en direct aux versions natives d'applications, empêchant ainsi que du JavaScript incompatibles soient livrés aux versions natives code plus anciennes.

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

• Un contrôle plus granulaire sur la correspondance de versions
• Plusieurs stratégies (canaux, semver, contraintes natives)
• Une meilleure visibilité sur la distribution des versions
• API et CLI contrôlent en parallèle de la gestion du tableau de bord

Cette approche est particulièrement utile lorsque :

• Vous avez des utilisateurs sur différentes versions majeures de votre application (par exemple, v1.x, v2.x, v3.x)
• Vous devez maintenir la compatibilité inverseur tout en mettant en œuvre des modifications de rupture
• Vous voulez empêcher les nouvelles archives de casser les code natives plus anciens
• Vous êtes en train de migrer les utilisateurs progressivement d'une version à l'autre
• Vous êtes en train de migrer de AppFlow et vous voulez maintenir la même sécurité de mise à jour

Comment ça marche

Capgo utilise une approche multi-niveaux pour correspondre les utilisateurs avec des mises à jour compatibles :

1. Contraintes de version native: Empêcher les bundles d'être livrés à des versions natives incompatibles
2. Affichage de canal basé sur le canal: Diriger différentes versions d'applications vers différents canaux de mise à jour
3. Contrôles de version sémantique: Bloquer automatiquement les mises à jour à travers les limites de version majeure/minor/patch
4. Survol de niveau de dispositif: Cibler des appareils spécifiques ou des groupes d'utilisateurs

Flux de correspondance de version

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

Stratégie 1 : Routage de version basé sur le canal

C'est l' approche recommandée pour gérer les changements majeurs et les mises à jour de version. C'est similaire au modèle de livraison d'AppFlow.

Scénario d'exemple

• App v1.x (100 000 utilisateurs) → production canal
• App v2.x (50 000 utilisateurs avec des modifications de rupture) → v2 canal
• App v3.x (10 000 utilisateurs bêta) → v3 canal

Mise en œuvre

É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: true,
      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: true,
      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: true,
      defaultChannel: 'v3', // Routes v3 users automatically
    }
  }
};

Étape 2 : Créer des canaux

# Create channels for each major version
npx @capgo/cli channel create production
npx @capgo/cli channel create v2
npx @capgo/cli channel create 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 : Télécharger les ensembles de fichiers par 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'application, ils se connectent automatiquement à leur canal dédié en fonction de defaultChannel in their installed app bundle. No JavaScript code changes required!

Avantages

• Aucune modification code - La routage des canaux se produit automatiquement
• Séparation claire - Chaque version a son propre pipeline d'actualisation
• Ciblage flexible - Mettre à jour les versions spécifiques en groupe
• Déploiements sûrs - Les modifications de rupture ne parviennent jamais aux versions incompatibles

Stratégie 2 : Contrôle de la versionnement sémantique

Utilisez les contrôles de versionnement semantique intégrés à Capgo pour empêcher les mises à jour au-delà des limites de version.

Désactiver les mises à jour automatiques entre versions majeures

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

Cette configuration signifie :

• Les utilisateurs de la version de l'application 1.2.3 recevront des mises à jour jusqu'à 1.9.9
• Les utilisateurs recevront pas de version 2.0.0 automatiquement
• Empêche les modifications de rupture de parvenir aux anciens code natifs

Options de contrôle granulaire

# Block minor version updates (1.2.x won't get 1.3.0)
npx @capgo/cli channel set stable --disable-auto-update minor

# Block patch updates (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

Versionnement Sémantique Obligatoire

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

Stratégie 3 : Contraintes de version native

Spécifiez les exigences de version native minimales pour les lots pour empêcher la livraison à des appareils incompatibles.

Utilisation de nativeVersion Delay Condition

Lors de l'upload d'un bundle, vous pouvez spécifier une version native minimale :

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

Comment ça marche

Les appareils sur native version 1.x NE recevront PAS ce bundle. Seuls les appareils sur 2.0.0+ le recevront. C'est parfait pour les mises à jour qui nécessitent de nouvelles API natives ou plugins.

Utilisations

1. Nouveau plugin natif requis

   # Bundle needs Camera plugin added in v2.0.0
   npx @capgo/cli bundle upload --native-version "2.0.0"

2. Mise à jour native API : changements

   # Bundle uses new Capacitor 6 APIs
   npx @capgo/cli bundle upload --native-version "3.0.0"

3. Migration progressive

   # Test bundle only on latest native version
   npx @capgo/cli bundle upload \
     --channel beta \
     --native-version "2.5.0"

Stratégie 4 : Prévention de la dégradation automatique

Activer dans les paramètres du canal

Stratégie 4 : Prévenir aux utilisateurs de recevoir des paquets plus anciens que leur version native actuelle.

Dans l'interface de gestion de Capgo :

1. Allez à Canaux → Sélectionnez votre canal
2. Activer “Désactiver la mise à niveau automatique native”
3. Sauvegarder les modifications

Ou via CLI :

npx @capgo/cli channel set production --disable-downgrade

Exemple

• Appareil de l'utilisateur : Version native 1.2.5
• Bundle de canal : Version 1.2.3
• RésultatMise à jour bloquée (serait une mise à niveau en arrière)

Cela est utile lorsque :

• Les utilisateurs ont installé manuellement une version plus récente depuis l'app store
• Vous avez besoin de vous assurer que les utilisateurs ont toujours les dernières mises à jour de sécurité
• Vous voulez prévenir les bugs de régression

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

Surcharger l'affectation de canal pour des appareils ou 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' })
  }
}

Tableau de bord Désactiver le dispositif

Dans le tableau de bord Capgo :

1. Allez à Dispositifs → Trouvez le dispositif
2. Cliquez Définir le canal ou Définir la version
3. Remplacez par une chaîne de canal ou une version de paquet spécifique
4. Le dispositif recevra des mises à jour à partir de la source remplacée

Mise à jour de test

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

Tout le workflow AppFlow-Style

1. Configuration initiale (App v1.0.0)

Voici un exemple complet qui combine toutes les stratégies :

# Create production channel with semver controls
npx @capgo/cli channel create production \
  --disable-auto-update major \
  --disable-downgrade

capacitor.config.ts

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

2. Mise à jour de rupture (App v2.0.0)

# Create v2 channel for new version
npx @capgo/cli channel create v2 \
  --disable-auto-update major \
  --disable-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: true,
      defaultChannel: 'v2', // New users get v2 channel
    }
  }
};

3. Envoyer les mises à jour vers les deux versions

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

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

4. Surveiller la distribution des versions

Utilisez le tableau de bord Capgo pour suivre :

• Combien d'utilisateurs sont sur v1 par rapport à v2
• Taux d'adoption des bundles par version
• Erreurs ou plantages par version

5. Dépréciation de la version ancienne

Une fois l'utilisation de v1 tombe en dessous du 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)

Préférence de canal

Lorsqu'il existe plusieurs configurations de canal, Capgo utilise l'ordre de priorité suivant :

1. Surcharge de Dispositif (Tableau de bord ou API) - Priorité la plus élevée
2. Surcharge de Cloud via setChannel() appel
3. canal par défaut dans capacitor.config.ts
4. Canal par Défaut (Paramètres de Cloud) - Priorité la plus basse

Exemple de Prééminence

Si l'application d'un utilisateur a defaultChannel: 'v2' mais vous surplombez leur appareil à 'beta' dans le tableau de bord, ils recevront des mises à jour du 'beta' canal.

Meilleures Pratiques

1. Définissez toujours 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. Utilisez la versionnement sémantique

# ✅ Good
1.0.0 → 1.0.1 → 1.1.0 → 2.0.0

# ❌ Bad
1.0 → 1.1 → 2 → 2.5

3. Maintenez 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 lancement

# Test on beta channel first
npx @capgo/cli bundle upload --channel beta

# Monitor for issues, then promote to production
npx @capgo/cli bundle upload --channel production

5. Surveiller la distribution des versions

Copier dans le presse-papier

• Les utilisateurs se mettent-ils à jour vers les versions natives plus récentes ?
• Les anciennes versions reçoivent-elles encore un trafic élevé ?
• Faut-il déprécier les anciens canaux ?

Comparaison avec Ionic AppFlow

Pour les équipes en train de migrer de Ionic AppFlow, voici comment la ciblage de version de Capgo se compare :

Fonctionnalité	Ionic AppFlow	Capgo
Navigation basée sur la version	Basé sur la version native	via + defaultChannel plusieurs stratégies
Versionnement semantique	Support de base	Avancé avec --disable-auto-update (majeur/minor/patch)
Contraintes de version native	Configuration manuelle dans le tableau de bord AppFlow	Intégré --native-version drapeau dans CLI
Gestion de canal	Interface Web + CLI	Interface Web + CLI + API
Surmonte des appareils	Contrôle limité au niveau des appareils	Contrôle total via le tableau de bord/API
Prévention de la dégradation automatique	Oui	Oui via --disable-downgrade
Maintenance de plusieurs versions	Gestion manuelle de branchement/canal	Automatisé avec priorité au canal
Hébergement autonome	Non	Oui (contrôle complet)
Analyse de version	Basique	Informations détaillées par version

AppFlow Parité et au-delà

Capgo fournit toutes les capacités de ciblage de version que proposait AppFlow, plus des mécanismes de contrôle supplémentaires. Si vous vous êtes appuyé sur la correspondance automatique de version d'AppFlow, vous trouverez Capgo tout aussi sûr avec plus de flexibilité.

Dépannage

Utilisateurs ne reçoivent pas les mises à jour

Vérifiez les éléments suivants :

1. Affectation de la chaîne: Vérifiez que le dispositif est sur la chaîne correcte

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

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

   • Tableau de bord → Bundles → Vérifiez la colonne « Version native »

3. Paramètres Semver: Vérifiez les paramètres de la chaîne disable-auto-update Copy to clipboard

   npx @capgo/cli channel list

4. Surcharge de périphériqueVérifiez si le périphérique a une surcharge manuelle

   • Tableau de bord → Périphériques → Recherche de périphérique → Vérifiez le canal/la version

Bundle livré à la mauvaise version

1. Réviser la valeur par défaut de la chaîne de canalVérifiez que le canal est correct dans capacitor.config.ts
2. Vérifiez l'envoi du bundleVérifiez que le bundle a été envoyé au canal prévu
3. Inspectez la version native: Confirmer --native-version le drapeau a été utilisé correctement

Changements Importants Affectant les Anciennes Versions

1. Solution Immédiate: Surcharger les appareils affectés vers un bundle sécurisé
   • Tableau de bord → Appareils → Sélection multiple → Définir la version
2. Solution à Long Terme: Créer des canaux versionnés et maintenir des branches séparées
3. Prévention: Tester toujours les mises à jour sur des appareils représentatifs avant le lancement

Migration depuis Ionic AppFlow

Si vous migrez depuis Ionic AppFlow, la cible de version fonctionne de manière très similaire dans Capgo, avec une flexibilité améliorée :

Cartographie de concepts

Concept AppFlow	Capgo Équivalent	Remarques
Canal de déploiement	Capgo Canal	Même concept, plus puissant
Verrouillage de la version native	--native-version flag	Un contrôle plus granulaire
Priorité de la chaîne	Prééminence de la chaîne (remplacement → cloud → par défaut)	Prééminence plus transparente
Cible de déploiement	Chaîne + contrôle semver	Plusieurs stratégies disponibles
Chaîne de production	production chaîne (ou n'importe quel nom)	Nommage flexible
Déploiement basé sur Git	CLI téléchargement du bundle depuis la branche	Même workflow
Compatibilité automatique	defaultChannel Contraintes de version +	Amélioré avec plusieurs stratégies

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

1. Plus de contrôle: Capgo vous donne plusieurs stratégies (canaux, semver, version native) qui peuvent être combinées
2. Une meilleure visibilité: Le tableau de bord montre la distribution des versions et les problèmes de compatibilité
3. API AccèsContrôle complet sur la cible de versionnement
4. Hébergement protégéOption pour exécuter votre propre serveur d'actualisation avec la même logique de version

Étapes de migration

1. Cartographiez vos canaux AppFlow aux canaux Capgo (généralement 1:1)
2. Définir defaultChannel dans capacitor.config.ts pour chaque version majeure
3. Configurer les règles de semver si vous souhaitez un blocage automatique aux limites de version
4. Télécharger des bundles spécifiques à la version en utilisant --native-version flag
5. Surveiller la distribution des versions dans le tableau de bord Capgo

Guide de migration complet

Pour obtenir des instructions de migration complètes, y compris la remplacement de SDK et la mise en correspondance de API, consultez le Guide de migration d'AppFlow vers Capgo.

Modèles 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' })
  }
}

Drapeaux de fonctionnalité 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()
  }
}

Test A/B entre 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 la livraison d'actualisations spécifiques à la version :

1. Gestion de Canal de Routage: Séparation automatique de version via defaultChannel
2. Numérotation de Version Sémantique: Empêcher les mises à jour à travers les limites de version majeure/minor/patch
3. Contraintes de Version Native: Exiger une version native minimale pour les ensembles
4. Prévention de la Dégradation Automatique: Jamais livrer des ensembles plus anciens à des versions natives plus récentes
5. Surcharge de Dispositif: Contrôle manuel pour la test et la ciblage

En combinant ces stratégies, vous pouvez atteindre le style de mise à jour automatique AppFlow avec encore plus de flexibilité et de contrôle. Choisissez l'approche qui convient le mieux à votre flux de travail de versionnement et de déploiement d'application.

Pour plus de détails sur les fonctionnalités spécifiques :

• Guide des Changements de Sécurité - Stratégie de versionnement détaillée des canaux
• Gestion des Canaux - Référence complète de la configuration des canaux
• Comportement de Mise à Jour - Retards et conditions de version native