Canaux

Copiez un prompt de configuration avec les étapes d'installation et la guide markdown complète pour ce plugin.

Les canaux constituent le mécanisme de base pour gérer les mises à jour de l'application dans Capgo. Ils vous permettent de contrôler comment et quand vos utilisateurs reçoivent les mises à jour, ce qui permet des fonctionnalités comme les tests A/B, les déploiements étalés et les mises à jour spécifiques au plateau.

Comprendre les canaux

Un canal représente une piste de distribution pour les mises à jour de votre application. Chaque canal peut être configuré avec des règles et des contraintes spécifiques.

Contrôle du paquet (version): Spécifiez le paquet (version) que les utilisateurs reçoivent
Ciblage de plateforme: Ciblez des plateformes spécifiques (iOS/Android/Electron)
Politiques de mise à jour: Control how updates are delivered
Restrictions de dispositifGérer les appareils qui peuvent accéder aux mises à jour

Gestion des options de canal

public: Définir le canal par défaut pour les nouveaux appareils.
disableAutoUpdateUnderNative: Empêcher les mises à jour lorsque la version native de l'application du dispositif est plus récente que la version stable du canal.
disableAutoUpdate: Contrôle du comportement de mise à jour (major, minor, metadata, patch, ou none).
updatePackage: Contrôler si les appareils téléchargent un zip, un delta ou les deux (all, zip, delta, zip_from_builtin, ou delta_from_builtin). Voir Format de téléchargement.
ios/android/électron: Activer ou désactiver la livraison par plateforme.
: Laisser les appareils choisir leur canal.: Autoriser les émulateurs
: Autoriser les appareils, : Autoriser les développeurs, allow_dev, permettre_prod: Contrôler les types d'appareils et de build qui reçoivent les mises à jour.
Déploiement progressif: Gardez un bundle stable tout en exposant un bundle cible à un groupe cohérent. Voir Déploiements progressifs.

Meilleures Pratiques

Test de canal: Maintenez un canal de test pour la validation interne
Déploiement PréalableUtilisez plusieurs canaux pour un déploiement d'actualisation progressive
Séparation de plateformeCréez des canaux séparés pour iOS, Android et Electron lorsque nécessaire.
Contrôle de la version du Bundle: Utilisez la versionnement semantique pour des chemins d'actualisation clairs

Endpoints

POST

https://api.capgo.app/channel/

Créer ou mettre à jour une configuration de canal.

Corps de la demande

type DisableAutoUpdate = "major" | "minor" | "metadata" | "patch" | "none"
type AutoPauseAction = "pause" | "rollback" | "notify"

interface ChannelSet {
  app_id: string
  channel: string
  version?: string | null // stable bundle name
  public?: boolean
  disableAutoUpdateUnderNative?: boolean
  disableAutoUpdate?: DisableAutoUpdate
  updatePackage?: "all" | "zip" | "delta" | "zip_from_builtin" | "delta_from_builtin"
  ios?: boolean
  android?: boolean
  electron?: boolean
  allow_device_self_set?: boolean
  allow_emulator?: boolean
  allow_device?: boolean
  allow_dev?: boolean
  allow_prod?: boolean

  // Progressive rollout (camelCase is preferred)
  rolloutVersion?: string | number | null // target bundle name or ID
  rolloutPercentage?: number // 0–100
  rolloutPercentageBps?: number // 0–10000; takes precedence when both are set
  rolloutEnabled?: boolean
  rolloutPaused?: boolean // input-only convenience flag
  rolloutPausedAt?: string | null // ISO timestamp or null
  rolloutPauseReason?: string | null
  rolloutCacheTtlSeconds?: number // 60–31536000
  rollback?: boolean
  promoteToStable?: boolean

  // Rollout auto-pause policy
  autoPauseEnabled?: boolean
  autoPauseWindowMinutes?: number
  autoPauseFailureRateBps?: number | null
  autoPauseConfidence?: number
  autoPauseMinAttempts?: number | null
  autoPauseMinFailures?: number | null
  autoPauseAction?: AutoPauseAction
  autoPauseCooldownMinutes?: number
}

Pour les champs de lancement et de pause automatique, l’API accepte également l'équivalent snake_case formes, telles que rollout_version ou auto_pause_enabled. updatePackage accepte également update_packageSi les deux formes sont fournies, la valeur camelCase l'emporte. rollback Seul camelCase.

Un objectif de déploiement nécessite un canal existant. Il doit avoir un bundle stable déjà affecté ou en recevoir un à travers version dans la même requête POST. rollback and promoteToStable ne sont pas des actions terminales; n'y associez pas d'autres.

Exemple de requête

Configure a 5% rollout for an existing production chaîne dont le bundle stable est déjà défini :

curl -X POST \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "com.example.app",
    "channel": "production",
    "rolloutVersion": "1.3.0",
    "rolloutPercentage": 5,
    "rolloutEnabled": true,
    "rolloutCacheTtlSeconds": 2592000,
    "autoPauseEnabled": true,
    "autoPauseFailureRateBps": 500,
    "autoPauseMinAttempts": 100,
    "autoPauseAction": "pause"
  }' \
  https://api.capgo.app/channel/

Réponse de succès

{
  "status": "ok"
}

La méthode POST est une mise à jour et retourne uniquement son statut. Effectuez une requête GET pour lire la configuration de la chaîne résultante.

Limite de clé de prévisualisation de l'application

Authentifier cet endpoint pour une prévisualisation de PR avec un minimum de privilèges authorization: $CAPGO_API_KEY ou capgkey: $CAPGO_API_KEY. The x-api-key L'en-tête n'est pas acceptée par les canaux API.

Un app_preview une clé peut créer un nouveau canal de prévisualisation non public. La création donne automatiquement à cette clé une liaison de cycle de vie définie sur le canal uniquement. Le rôle ne comprend pas channel.update_settingsIl ne peut pas utiliser la méthode POST pour mettre à jour un canal existant, y compris un canal par défaut ou principal.

Quitter public non défini (ou définissez-le sur false) pour les canaux de prévisualisation PR. Utilisez bundle upload --channel Pour la création et l'upload en lieu et place de traiter POST comme une mise en avant de canal de prévisualisation.

GET

https://api.capgo.app/channel/

Récupérer les informations du canal. Renvoie 50 canaux par page. Sans channel, la réponse est un tableau. Avec channel, la réponse est un objet de canal.

Paramètres de requête

app_id: Obligatoire. L'ID de votre application
page: Facultatif. Numéro de page pour la pagination
channel: Facultatif. Nom spécifique du canal à récupérer

Exemples de requêtes

# Get all channels
curl -H "authorization: your-api-key" \
  "https://api.capgo.app/channel/?app_id=com.example.app"

# Get a specific channel
curl -H "authorization: your-api-key" \
  "https://api.capgo.app/channel/?app_id=com.example.app&channel=production"

# Get the next page
curl -H "authorization: your-api-key" \
  "https://api.capgo.app/channel/?app_id=com.example.app&page=1"

Type de réponse

interface Channel {
  id: number
  created_at: string
  updated_at: string
  name: string
  app_id: string
  created_by: string
  public: boolean
  disableAutoUpdateUnderNative: boolean
  disableAutoUpdate: DisableAutoUpdate
  updatePackage: "all" | "zip" | "delta" | "zip_from_builtin" | "delta_from_builtin"
  allow_device_self_set: boolean
  allow_emulator: boolean
  allow_device: boolean
  allow_dev: boolean
  allow_prod: boolean
  version: { id: number, name: string } | null // stable bundle

  // These three response identifiers intentionally use snake_case.
  rollout_version: number | null
  rollout_id: string
  rollout_version_info: { id: number, name: string } | null

  rolloutPercentageBps: number
  rolloutEnabled: boolean
  rolloutPausedAt: string | null
  rolloutPauseReason: string | null
  rolloutCacheTtlSeconds: number
  autoPauseEnabled: boolean
  autoPauseWindowMinutes: number
  autoPauseFailureRateBps: number | null
  autoPauseConfidence: number
  autoPauseMinAttempts: number | null
  autoPauseMinFailures: number | null
  autoPauseAction: AutoPauseAction
  autoPauseCooldownMinutes: number
  autoPauseLastTriggeredAt: string | null
  autoPauseLastCheckedAt: string | null
}

rolloutPaused C'est un raccourci d'entrée uniquement et n'est pas retourné. Une mise en production suspendue est représentée par un objet non nul. rolloutPausedAt.

Réponse d'exemple

[
  {
    "id": 1,
    "name": "production",
    "app_id": "com.example.app",
    "updatePackage": "all",
    "version": { "id": 1, "name": "1.2.0" },
    "rollout_version": 2,
    "rollout_id": "e60c19c9-2e65-4e0d-bc06-d1f5b4f96276",
    "rollout_version_info": { "id": 2, "name": "1.3.0" },
    "rolloutPercentageBps": 500,
    "rolloutEnabled": true,
    "rolloutPausedAt": null,
    "rolloutCacheTtlSeconds": 2592000,
    "autoPauseEnabled": true,
    "autoPauseFailureRateBps": 500,
    "autoPauseAction": "pause"
  }
]

SUPPRIMER

https://api.capgo.app/channel/

Supprimer un canal. Notez que cela affectera tous les appareils utilisant ce canal.

Corps de la demande

interface Channel {
  channel: string
  app_id: string
  delete_bundle?: boolean // also delete the linked bundle
}

Exemple de demande

curl -X DELETE \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
  "app_id": "com.example.app",
    "channel": "beta"
  }' \
  https://api.capgo.app/channel/

Réponse de succès

{
  "status": "ok"
}

Nettoyage de l'avant-première de l'application

Avec delete_bundle: true, un app_preview Clé qui peut nettoyer atomiquement uniquement un canal qu'elle a créé et son lot lié, non partagé. La clé n'a pas de permission générale. bundle.delete permission.

curl -X DELETE \
  -H "capgkey: $CAPGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "com.example.app",
    "channel": "pr-123",
    "delete_bundle": true
  }' \
  https://api.capgo.app/channel/

Gestion des erreurs

Scénarios d'erreurs courants et leurs réponses :

// Channel not found
{
  "error": "Channel not found",
  "status": "KO"
}

// Invalid bundle (version) format
{
  "error": "Invalid version format. Use semantic versioning",
  "status": "KO"
}

// Invalid update policy
{
  "error": "Invalid disableAutoUpdate value",
  "status": "KO"
}

// Permission denied
{
  "error": "Insufficient permissions to manage channels",
  "status": "KO"
}

Utilisations courantes

Lancement en production

{
  "app_id": "com.example.app",
  "channel": "beta",
  "version": "1.2.0-beta",
  "public": false,
  "allow_emulator": true,
  "allow_dev": true
}

Déploiement en Production

{
  "app_id": "com.example.app",
  "channel": "production",
  "version": "1.2.0",
  "public": true,
  "disableAutoUpdate": "minor"
}

Mises à jour spécifiques au plateforme

{
  "app_id": "com.example.app",
  "channel": "ios-hotfix",
  "version": "1.2.1",
  "ios": true,
  "android": false
}

Continuer depuis les canaux

Si vous utilisez Canaux to plan channel routing and staged rollout, connect it with Canaux pour les détails d'implémentation dans les canaux, Canaux pour les détails d'implémentation dans les canaux, Solution de test bêta pour le flux de produit en Solution de test en bêta, Solution de ciblage de version pour le flux de produit en Solution de ciblage de version, et Pratiques de l'environnement Capgo : Mise en scène avec un seul ID d'application mobile pour le contexte pratique dans Capgo Pratiques de l'environnement : Mise en scène avec un ID d'application mobile unique.