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 AppFlowCela 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 d'Ionic AppFlow, ce guide est particulièrement important pour vous. AppFlow a automatiquement mis à jour les versions natives, et Capgo offre la même capacité avec encore plus de contrôle et de flexibilité. Consultez le Guide de migration d'AppFlow pour des instructions de migration étape par étape.

Vue d'ensemble

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

• Fournir automatiquement des mises à jour compatibles aux utilisateurs en fonction de leur version d'applications natives
• Empêcher les modifications de rupture de parvenir aux versions d'applications incompatibles
• Gérer plusieurs versions d'applications simultanément sans logique complexe
• Roulez sans heurts les mises à jour vers des segments d'utilisateurs spécifiques

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

Si vous êtes familiarisé avec Ionic AppFlow, vous savez à quel point il est crucial de vous assurer que les utilisateurs reçoivent uniquement des mises à jour compatibles. AppFlow a automatiquement associé des lots de mise à jour en direct à des versions natives d'applications, empêchant ainsi du JavaScript incompatibles d'être livrés à des 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 version
• Plusieurs stratégies (canaux, semver, contraintes natives)
• Une meilleure visibilité sur la distribution de version
• API and CLI control alongside dashboard management

Cet 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 avez besoin de maintenir la compatibilité inverseur tout en mettant en œuvre des changements de rupture
• Vous voulez empêcher les nouvelles archives de casser les code natifs 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 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: Prévenir les bundles d'être livrés à des versions natives incompatibles
2. Routage basé sur le canal: Routez différentes versions d'applications vers différents canaux de mise à jour
3. Contrôles de versionnement semantique: Bloquez automatiquement les mises à jour à travers les limites de version majeure/minor/patch
4. Survol de niveau de dispositif: Ciblez des appareils ou des groupes d'utilisateurs spécifiques

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 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 de version basé sur le canal

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

Section intitulée “Exemple de scénario”

• (100 000 utilisateurs) → canal production App v2.x
• (50 000 utilisateurs avec des changements de version majeure) → canal v2 App v3.x
• (100 000 utilisateurs avec des changements de version majeure) → (10 000 utilisateurs bêta) → v3 chaîne

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: '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 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 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'application, ils se connectent automatiquement à leur canal désigné en fonction de defaultChannel dans leur bundle d'application installé. Aucune modification JavaScript code requise !

Avantages

• Zéro code modifications - La mise en route des canaux se fait automatiquement
• Une séparation claire - Chaque version a son propre pipeline d'actualisation
• Une cible flexible - Envoyez des mises à jour vers des groupes de versions spécifiques
• Un lancement sûr - Les changements de rupture ne parviennent jamais aux versions incompatibles

Stratégie 2 : Contrôles de versionnement sémantique

Use Capgo’s built-in intégrés à __CAPGO_KEEP_0__ pour empêcher les mises à jour à travers les limites de version. Utilisez les contrôles de versionnement sémantique intégrés à __CAPGO_KEEP_0__ pour empêcher les mises à jour à travers les limites de version.

Désactiver la mise à jour automatique entre les 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 la version 2.0.0 automatiquement
• Empêche les modifications de rupture de parvenir aux anciens code natives
• La comparaison utilise la ligne de base 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

Versionnement Sémantique Obligatoire

Cette stratégie ne fonctionne que si vous suivez le versionnement sémantique (semver) pour vos versions d'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 minimales de version native pour les lots pour empêcher la livraison à des appareils incompatibles.

Utilisation de la condition de retard de version native

Lors de l'upload d'un lot, 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 la version native 1.x NE recevront PAS ce lot. 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.

Cas d'utilisation

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. Changements natifs API importants

   # 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

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

Activer dans les paramètres de la chaîne

Dans le tableau de bord Capgo :

1. Allez à Chaînes → Sélectionnez votre chaîne
2. Activer « Désactiver la mise à niveau automatique native »
3. Enregistrer 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 vers une version antérieure)

Cela est utile lorsque :

• Les utilisateurs ont manuellement installé une version plus récente depuis l'App Store
• Vous avez besoin de vous assurer que les utilisateurs disposent toujours des dernières mises à jour de sécurité
• Vous souhaitez 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 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' })
  }
}

Ouverture de session de l'appareil

Dans le tableau de bord Capgo :

1. Allez à Appareils → Trouvez l'appareil
2. Cliquez Définir le canal ou Fixer la version
3. Remplacez par une version spécifique de canal ou de paquet
4. L'appareil recevra des mises à jour de la source remplacée

Tester les mises à jour

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

Flux de travail complet AppFlow-Style

Voici un exemple complet combinant toutes les stratégies :

1. Initialisation (App v1.0.0)

# 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: 'atBackground',
      defaultChannel: 'production',
    }
  }
};

2. Modification 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: 'atBackground',
      defaultChannel: 'v2', // New users get v2 channel
    }
  }
};

3. Envoyer des 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. Surveillance de la distribution de versions

Utilisez le tableau de bord Capgo pour suivre :

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

5. Dépréciation de la version ancienne

Une fois l'utilisation de v1 chute 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)

Ordre de Préférence de Canal

Lorsqu'il existe plusieurs configurations de canal, Capgo utilise cet ordre de préférence :

1. Surcharge de Dispositif (Tableau de bord ou API) - Priorité la plus élevée et visible dans l'interface de Surcharge de Dispositif
2. Canal de plugin local via setChannel() - Stocké uniquement sur le dispositif et non affiché dans l'interface de Surcharge de Dispositif
3. canalParDéfaut dans capacitor.config.ts
4. Canal Par Défaut (Réglage Cloud) - Priorité la plus basse

Exemple de Préférence

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

La mise en œuvre de la prise en charge du dispositif ne liste que les surécrivages définis à partir du tableau de bord ou Public API. Appeler setChannel() à partir de l'application valide le canal avec l'arrière-plan, puis le stocke localement sur l'appareil.

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. Utiliser la versionnement semantique

# ✅ 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 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. Suivre la distribution des versions

Vérifiez régulièrement votre tableau de bord :

• 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 depuis Ionic AppFlow, voici comment Capgo cible les versions :

Fonctionnalité	Ionic AppFlow	Capgo
Routage basé sur la version	Automatique en fonction de la version native	Automatique via defaultChannel + plusieurs stratégies
Versionnement semantique	Support de base	Avancé avec --disable-auto-update (major/minor/patch)
Contraintes de version native	Configuration manuelle dans le tableau de bord d'AppFlow	Intégré --native-version drapeau dans CLI
Gestion de la chaîne	UI Web + CLI	UI Web + CLI + API
Surcharge de dispositif	Contrôle limité au niveau du dispositif	Contrôle total via Dashboard/API
Prévention de la descente automatique	Oui	Oui via --disable-downgrade
Maintenance multi-version	Gestion de branchement/chânel manuelle	Automatisé avec priorité de chânel
Hébergement auto	Non	Oui (contrôle total)
Analytique de version	Basique	Métriques détaillées par version

Équivalence et au-delà d'AppFlow

Capgo fournit All les capacités de ciblage de version, plus des mécanismes de contrôle supplémentaires. Si vous vous êtes appuyé sur la mise en correspondance automatique de version proposée par AppFlow, vous trouverez __CAPGO_KEEP_0__ tout aussi sécurisé avec plus de flexibilité. that AppFlow offered, plus additional control mechanisms. If you relied on AppFlow’s automatic version matching, you’ll find Capgo equally safe with more flexibility.

Sous-titre : « Résolution des problèmes »

Sous-titre : « Les utilisateurs ne reçoivent pas les mises à jour »

Affectation du canal

1. : Vérifiez que le dispositif est sur le bon canalCopier dans le presse-papier

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

2. : Vérifiez si le bundle a des exigences de version nativesCopy to clipboard

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

3. Paramètres Semver: Vérifiez le canal de « disable-auto-update paramètre

   npx @capgo/cli channel list

4. Désactivation de l'appareil: Vérifiez si l'appareil a une désactivation manuelle

   • Tableau de bord → Appareils → Recherchez l'appareil → Vérifiez le canal/la version

Paquet livré à la mauvaise version

1. Examen de la valeur par défaut de la chaîne de canal: Assurez-vous que le canal est correct capacitor.config.ts
2. Vérifiez l'envoi du bundle: Vérifiez si le bundle a été envoyé vers le canal prévu
3. Inspectez la version native: Confirmez --native-version l'indicateur a été utilisé correctement

Changements de rupture affectant les anciennes versions

1. Solution immédiate: Forcez les appareils affectés à utiliser le bundle sécurisé
   • Tableau de bord → Appareils → Sélection multiple → Définir la version
2. Solution à long terme: Créez des canaux versionnés et maintenez des branches séparées
3. Prévention: Testez toujours les mises à jour sur des appareils représentatifs avant le lancement

Mise à niveau depuis Ionic AppFlow

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

Cartographie de concepts

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

Differences clés pour les utilisateurs d'AppFlow

1. Plus de Contrôle: Capgo vous offre plusieurs stratégies (canaux, semver, version native) qui peuvent être combinées
2. Une Meilleure Visibilité: Le tableau de bord montre la répartition des versions et les problèmes de compatibilité
3. API Access: Contrôle programmé complet sur la cible de version
4. Auto-Hébergement: Option pour exécuter votre propre serveur d'actualisation avec la même logique de version

Étapes de Migration

1. Cartographiez vos canaux AppFlow vers les 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 des instructions de migration complètes, y compris le remplacement de SDK et la mise en correspondance de API, voir le Guide de migration de 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 fournit plusieurs stratégies pour la livraison d'actualisations spécifiques à la version :

1. Channel-Based Routing : Séparation automatique de la version via defaultChannel
2. Semantic Versioning : Empêcher les mises à jour à travers les limites de version majeure/minor/patch
3. Native Version Constraints : Exiger une version native minimale pour les ensembles
4. Auto-Downgrade Prevention : Jamais livrer des ensembles plus anciens à des versions natives plus récentes
5. Paramètres de dispositif: Contrôle manuel pour la mise en œuvre et la cible

En combinant ces stratégies, vous pouvez atteindre une mise à jour automatique de style 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 majeurs - 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

Continuez de la ciblage de version

If vous utilisez Planification de version pour planifier la routage de canal 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, Canaux pour les détails d'implémentation dans Canaux, Solution de test bêta pour le flux de travail du produit dans Solution de test bêta, et Solution de planification de version pour le flux de produit dans la Solution de ciblage de version.