Version Ciblage

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

Migrer depuis AppFlow d'Ionic ?

Si vous venez de AppFlow d'Ionic, ce guide est particulièrement important pour vous. AppFlow a automatiquement correspondu les mises à jour aux versions natives, et Capgo offre la même capacité avec encore plus de contrôl’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:

• Délivrer automatiquement des mises à jour compatibles aux utilisateurs en fonction de leur version d'application native
• Prévenir les modifications de rupture de ne pas atteindre les versions d'application incompatibles
• Gérer plusieurs versions d'application sans logique complexe simultanément
• Déployer les mises à jour de manière fluide 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 s'assurer que les utilisateurs reçoivent uniquement des mises à jour compatibles. AppFlow a automatiquement associé les lots de mise à jour en direct aux versions natives d'application, empêchant ainsi que du JavaScript incompatibles ne soit pas livré aux versions natives plus anciennes code.

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é dans la distribution de version
• 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 avez besoin de maintenir la compatibilité inverseur tout en mettant en place des changements brisants
• Vous voulez empêcher les nouvelles ensembles de casser les anciens natives code
• Vous êtes en train de migrer les utilisateurs progressivement d'une version à l'autre
• Vous êtes en train de migrer de AppFlow et souhaitez 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 de être livrés à des versions natives incompatibles
2. Affichage de canal: Routage d'applications différentes vers différents canaux de mise à jour
3. Contrôles de version sémantique: Bloquer automatiquement les mises à jour à travers les limites majeures/minores/patch
4. Survol de dispositif: Cibler 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

Ceci est la méthode 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.

Scénario d'exemple

• App v1.x (100 000 utilisateurs) → production chaîne
• App v2.x (50 000 utilisateurs avec des modifications de rupture) → v2 chaîne
• App v3.x (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 des ensembles 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

When les utilisateurs ouvrent l'application, ils se connectent automatiquement à leur canal désigné en fonction de defaultChannel in their installed app bundle. No JavaScript code changes required!

Avantages

• Zero code changes - La mise en route du canal se fait automatiquement
• - Une séparation claire - Chaque version a son propre pipeline d'actualisation
• - La mise à jour peut être ciblée vers des groupes de versions spécifiques - Les mises à jour sont sécurisées
• - Les modifications de rupture ne parviennent jamais aux versions incompatibles - Chaque version a son propre pipeline d'actualisation

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

Utilisez les contrôles de versionnement sémantique intégrés à Capgo pour empêcher les mises à jour à travers les limites de version. Désactiver les Mises à Jour Automatiques Entre Versions Majeures

Section intitulée « 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

Les utilisateurs sur la version de l'application

• recevront des mises à jour jusqu'à 1.2.3 version 1.9.9
• Les utilisateurs recevront NE PAS recevront automatiquement 2.0.0 Empêche les modifications de version de briser les versions natives plus anciennes __CAPGO_KEEP_0__
• Prevents breaking changes from reaching older native code
• Options de contrôle granulaire version_build

Section intitulée « 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

Options de contrôle granulaire

Cette stratégie ne fonctionne que si vous suivez la versionnement semantique (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 natives

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

Cela utilise la stratégie de méta-données du canal (--disable-auto-update metadata) plus --min-update-version ou --auto-min-update-version __CAPGO_KEEP_0__ --native-version CLI flag.

Activer la ciblage de 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

Section intitulée « Fixer une version native minimale lors de l'upload »

Fenêtre de terminal

# 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 niveau de compatibilité des packages natifs :

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 le niveau de base natif (version_build) est inférieur à celui du bundle min_update_version ignoreront l'update. Seuls les appareils sur cette version ou supérieure la recevront. Voir Compatibilité pour --auto-min-update-version détails.

Utilisations de cas

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 natifs API brisants

   # 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évention de la dégradation automatique

Prévenir les utilisateurs de recevoir des ensembles plus anciens que leur version native actuelle.

Activer dans les paramètres du canal

Dans le tableau de bord Capgo :

1. Allez à Canaux context : Nom du canal de mise à jour de Capgo. Page/zone : Page de marketing des solutions de Capgo. Rôle : Étiquette de navigation ou élément de menu court. Voir dans : page solutions/white-label.astro. Clé de message `solutions_white_label_visual_cell2_value` (Valeur de cellule visuelle de Solutions White Label).
2. → Sélectionnez votre canal Activer
3. « Désactiver la mise à niveau automatique sous native »

Or via CLI:

npx @capgo/cli@latest channel set production --no-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 inférieure)

Cela est utile dans les cas suivants :

• Les utilisateurs ont manuellement installé une version plus récente depuis l'app store
• Vous devez 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

Surpasser la mise à jour automatique 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' })
  }
}

Tableau de bord : ciblage d'appareil

Dans le tableau de bord Capgo :

1. Allez à Appareils → Trouvez l'appareil
2. Cliquez Configure le canal ou ou
3. Configure la version spécifique du canal ou du bundle
4. Le dispositif recevra les mises à jour de la source surchargée

Tests de mises à jour

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

Flux de travail complet AppFlow-Style

Ici est un exemple complet qui combine 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. Modification de rupture de version (Application 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 vers les 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 répartition 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 que l'utilisation de v1 est inférieure au 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 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. defaultChannel dans capacitor.config.ts
4. Canal par défaut (Paramètres 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' sur la plateforme, ils recevront des mises à jour du 'beta' canal.

La mise en page de la surcharge de l'appareil ne liste que les surcharges définies à partir de la plateforme ou Publique API. Appeler setChannel() à partir de l'application valide le canal avec le serveur de backend, 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. 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. Testez avant la mise en production

# 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 répartition des versions

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

• Les utilisateurs se mettent-ils à jour vers de nouvelles versions natives ?
• 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 AppFlowVoici comment Capgo cible les versions :

Caractéristique	Ionic AppFlow	Capgo
Versionnage basé sur la version	Routage basé sur la version	Automatique en fonction de la version native defaultChannel Automatique via
+ plusieurs stratégies	Gestion de version semantique	Support de base --disable-auto-update Avancé avec
Contraintes de version native	Configuration manuelle dans le tableau de bord d'AppFlow	Intégré --min-update-version / --auto-min-update-version avec des canaux de métadonnées
Gestion de canaux	Interface Web + CLI	Interface Web + CLI + API
Surcharge de dispositif	Contrôle limité au niveau du dispositif	Contrôle total via le tableau de bord/API
Prévention de la descente automatique	Oui	Oui via --no-downgrade
Maintenance multi-version	Gestion manuelle de branch et de canal	Automatisé avec priorité au canal
Hébergement auto	Non	Oui (contrôle total)
Analytiques de version	Basique	Informations détaillées par version

AppFlow Parité et au-delà

Capgo fournit toutes les capacités de ciblage de version qui étaient proposées par AppFlow, ainsi que des mécanismes de contrôle supplémentaires. Si vous vous appuyiez sur la mise en correspondance automatique de version de AppFlow, vous trouverez Capgo tout aussi sûr avec plus de flexibilité.

Résolution des problèmes

Utilisateurs qui ne reçoivent pas les mises à jour

Vérifiez les éléments suivants :

1. Affectation du canal: Vérifiez que le dispositif 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 natives

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

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

   npx @capgo/cli channel list

4. Surcharge de version du dispositif: Vérifiez si le dispositif a une surcharge de version manuelle

   • Tableau de bord → Dispositifs → Recherchez le dispositif → Vérifiez le canal/la version

Section intitulée « Le bundle a été livré à la mauvaise version »

1. Réviser le canal par défaut: Assurez-vous que le canal est correct capacitor.config.ts
2. Vérifier l'envoi du bundle: Vérifiez que le bundle a été envoyé au canal prévu
3. Inspecter la version d'update minimale: Confirmez --min-update-version (ou) --auto-min-update-version) a été défini et le canal utilise --disable-auto-update metadata

Changements de rupture affectant les anciennes versions

1. Réparation immédiate: Survoler les appareils affectés vers le bundle de sécurité
   • Tableau de bord → Appareils → Sélection multiple → Définir la version
2. Réparation à long termeCréer des canaux versionnés et maintenir des branches séparées
3. PréventionTester toujours les mises à jour sur des appareils représentatifs avant le lancement

Migration depuis Ionic AppFlow

Ionic AppFlow La ciblage de version fonctionne de manière très similaire dans __CAPGO_KEEP_0__, avec une flexibilité améliorée :, version targeting works very similarly in Capgo, with improved flexibility:

Section intitulée « Cartographie de concepts »

Concept AppFlow	Capgo Equivalent	Notes
Canal de déploiement	Capgo Canal	Même concept, plus puissant
Verrouillage de version native	--min-update-version / --auto-min-update-version	Plus de contrôle granulaire
Priorité du canal	Prééminence du canal (surcharge → cloud → par défaut)	Prééminence plus transparente
Cible de déploiement	Contrôle du canal + semver	Plusieurs stratégies disponibles
Canal de production	production canal (ou tout nom)	Nomination flexible
Déploiement basé sur Git	CLI téléchargement du paquet depuis la branche	Même flux de travail
Compatibilité automatique avec les versions	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 offre plusieurs stratégies (canaux, semver, version native) qui peuvent être combinées
2. Une Visibilité Améliorée: Le tableau de bord affiche la distribution des versions et les problèmes de compatibilité
3. API Accès: Contrôle programmatique complet sur la ciblage de version
4. Auto-Hébergement: Option de lancer votre propre serveur d'actualisation avec la même logique de version

Étapes de Migration

1. Cartographiez vos canaux AppFlow vers les Capgo canaux (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. Charger des ensembles de versions spécifiques en utilisant --min-update-version sur
5. (le canal doit utiliser la stratégie de métadonnées) in Capgo dashboard

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 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 aux versions :

1. Routage basé sur le canal: Séparation automatique de la version via defaultChannel
2. Numérotation Sémantique: Empêcher les mises à jour en traversant les limites de version majeure/minor/patch
3. Contraintes de version natives: Exiger une version native minimale pour les ensembles
4. Prévention de la dégradation automatique: Ne livre jamais de versions plus anciennes aux versions natives plus récentes
5. Survol de l'appareil: Contrôle manuel pour les tests et la ciblage

En combinant ces stratégies, vous pouvez atteindre une mise à jour automatique AppFlow-style avec encore plus de flexibilité et de contrôle. Choisissez l'approche qui convient le mieux à la versionnage et au workflow de déploiement de votre 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 avec la ciblage de version

Si vous utilisez La ciblage de version Pour planifier la routage des canaux et la mise en production étape par étape, connectez-l’avec Les canaux pour les détails d'implémentation dans Les canaux, pour les détails d'implémentation dans Les canaux, pour les détails d'implémentation dans Les canaux, La solution de test bêta pour le flux de travail du produit dans La solution de test bêta, et pour le flux de travail du produit dans La solution de test bêta, et pour le flux de travail du produit dans La solution de test bêta, et Solution de ciblage de version pour le flux de travail du produit dans la Solution de ciblage de version.