Canaux

Les canaux sont le mécanisme central pour gérer les mises à jour d'applications dans Capgo. Ils vous permettent de contrôler comment et quand vos utilisateurs reçoivent les mises à jour, facilitant des fonctionnalités comme l'A/B testing, le déploiement progressif et les mises à jour spécifiques à une plateforme.

Comprendre les canaux

Un canal représente un flux 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 bundle (version): Spécifier quel bundle (version) les utilisateurs reçoivent
• Ciblage de plateforme: Cibler des plateformes spécifiques (iOS/Android/Electron)
• Politiques de mise à jour: Contrôlez la diffusion des mises à jour
• Restrictions d'appareilGérez les appareils autorisés à accéder aux mises à jour

Options de configuration du canal

• public: Définir comme canal par défaut pour les nouveaux appareils.
• disableAutoUpdateUnderNative: Empêcher les mises à jour lorsque la version native de l’appareil est plus récente que le bundle stable du canal.
• disableAutoUpdate: Contrôler le comportement des mises à jour (major, minor, patch, version_number, ou none). metadata est accepté comme alias de version_number.
• updatePackage: Contrôle si les appareils téléchargent un zip, un delta, ou les deux (all, zip, delta, zip_from_builtin, ou delta_from_builtin). Consultez Format de téléchargement.
• ios/android/electron): Active ou désactive la diffusion par plateforme.
• allow_device_self_set: Permet aux appareils de choisir leur canal.
• allow_emulator, autoriser_appareil, allow_dev, allow_prod: Contrôlez quels appareils et types de build reçoivent les mises à jour.
• Déploiement progressif: Gardez un bundle stable tout en exposant un bundle cible à une cohorte spécifique. Voir Déploiements progressifs.

Bonnes pratiques

1. le canal de test: Maintenez un canal de test pour la validation interne
2. Déploiement progressifUtilisez plusieurs canaux pour un déploiement progressif des mises à jour
3. Séparation des plateformes: Créez des canaux distincts pour iOS, Android et Electron si nécessaire
4. Contrôle des bundles (versions) : Utilisez versionnage sémantique pour des chemins de mise à jour clairs

Endpoints

POST

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

Créer ou mettre à jour la configuration d'un canal.

Corps de la requête

type DisableAutoUpdate = "major" | "minor" | "patch" | "version_number" | "metadata" | "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 rollout et d'auto-pause, API accepte également la forme snake_case équivalente, telle que rollout_version ou auto_pause_enabled. updatePackage accepte aussi update_package. Si les deux formes sont fournies, la valeur en camelCase l'emporte. rollback est uniquement en camelCase.

Une cible de rollout nécessite un canal existant. Il doit déjà avoir un bundle stable assigné ou en recevoir un via version dans la même requête POST. rollback et promoteToStable sont des actions terminales ; ne les combinez pas entre elles.

Exemple de requête

Configurez un déploiement progressif à 5 % pour un production canal 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 en cas de succès

{
  "status": "ok"
}

POST effectue un upsert et renvoie uniquement son statut. Effectuez une requête GET pour lire la configuration du canal obtenue.

Limite de la clé App Preview

Pour une preview de PR à privilèges minimaux, authentifiez cet endpoint avec authorization: $CAPGO_API_KEY ou capgkey: $CAPGO_API_KEY. Le x-api-key le header n'est pas accepté par l'API des canaux.

Une app_preview peut créer un nouveau canal de preview non public. La création attribue automatiquement à cette clé un binding de cycle de vie limité à ce canal uniquement. Le rôle n'inclut pas channel.update_settings, il ne peut donc pas utiliser POST pour mettre à jour un canal existant, y compris un canal par défaut ou principal existant.

Quitter public non défini (ou le régler sur false) pour les canaux de preview PR. Utilisez bundle upload --channel pour le flux de création et d'upload au lieu de traiter POST comme un upsert de preview-channel générique.

GET

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

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

Paramètres de requête

• app_id: Requis. L'ID de votre application
• page: Optionnel. Numéro de page pour la pagination
• channel: Optionnel. Nom du canal spécifique à 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 est un raccourci en entrée uniquement et n'est pas renvoyé. Un déploiement progressif en pause est représenté par une valeur non nulle rolloutPausedAt.

Exemple de réponse

[
  {
    "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 requête

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

Exemple de requête

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 en cas de succès

{
  "status": "ok"
}

Nettoyage des App Previews

Avec delete_bundle: true, un app_preview la clé peut nettoyer de manière atomique uniquement le canal qu'elle a créé et son bundle lié non partagé. La clé ne reçoit pas de droits généraux 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

Toutes les erreurs utilisent le format d'erreur standard décrit dans la Aperçu de API.

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

// The API key has no access to the app
{
  "error": "cannot_access_app",
  "message": "You can't access this app",
  "moreInfo": { "app_id": "com.example.app" }
}

// Invalid disableAutoUpdate value
{
  "error": "invalid_disable_auto_update",
  "message": "Disable auto update must be major, minor, patch, version_number, metadata, or none",
  "moreInfo": { "disableAutoUpdate": "always" }
}

// Rollout percentage out of range
{
  "error": "invalid_rollout_percentage",
  "message": "Rollout percentage must be between 0 and 100",
  "moreInfo": { "rolloutPercentage": 150 }
}

// DELETE without a channel name
{
  "error": "missing_channel_name",
  "message": "You must provide a channel name",
  "moreInfo": {}
}

Cas d'usage courants

1. Tests bêta

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

2. Déploiement progressif en production

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

3. Mises à jour spécifiques à la 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 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, Solution de bêta-test pour le workflow produit de la solution Beta Testing, Solution de ciblage de version pour le workflow produit de la solution Version Targeting, et Bonnes pratiques pour l'environnement Capgo : staging avec un seul ID d'app mobile pour le contexte pratique de Capgo Environment Best Practices : Staging avec un seul ID d'application mobile.