Aller au contenu

Canaux

Les canaux sont le mécanisme central pour gérer les mises à jour d’app dans Capgo. Ils vous permettent de contrôler la manière et le moment où vos utilisateurs reçoivent des mises à jour, en activant des fonctionnalités comme les tests A/B, les déploiements progressifs et les mises à jour spécifiques à une plateforme.

Un canal représente une piste de distribution pour vos mises à jour d’app. Chaque canal peut être configuré avec des règles et des contraintes spécifiques :

  • Contrôle du bundle (version): spécifiez quel bundle (version) les utilisateurs reçoivent
  • Ciblage par plateforme: ciblez des plateformes spécifiques (iOS/Android/Electron)
  • Politiques de mise à jour: Contrôlez la livraison des mises à jour
  • Restrictions par appareilGérez les appareils autorisés à accéder aux mises à jour
  • 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ôlez 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: Activez ou désactivez la diffusion par plateforme.
  • allow_device_self_set: Laissez les appareils choisir leur canal.
  • autoriser_émulateur, autoriser_appareil, allow_dev, allow_prod: Contrôlez quels types d’appareils et de builds reçoivent les mises à jour.
  • Déploiement progressif: Conservez un bundle stable tout en exposant un bundle cible à une cohorte sticky. Voir Déploiements progressifs.
  1. Canal de test: Maintenez un canal de test pour la validation interne
  2. Déploiement progressif: Utilisez plusieurs canaux pour un déploiement progressif des mises à jour
  3. Séparation par plateforme: Créez des canaux distincts pour iOS, Android et Electron si nécessaire
  4. Contrôle du bundle (version) : Utilisez versionnage sémantique pour des chemins de mise à jour clairs

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

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

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, l’API accepte également la forme équivalente snake_case sous forme de rollout_version ou auto_pause_enabled. updatePackage accepte également update_package. Si les deux formes sont fournies, la valeur en camelCase prévaut. rollback est uniquement en camelCase.

Une cible de rollout nécessite un canal existant. Celui-ci 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.

Configurez un déploiement progressif à 5 % pour un production canal dont le bundle stable est déjà défini :

Fenêtre de terminal
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/
{
"status": "ok"
}

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

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.

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 de canal.

  • app_id: Requis. L'ID de votre application
  • page: Optionnel. Numéro de page pour la pagination
  • channel: Facultatif. Nom du canal spécifique à récupérer
Fenêtre de terminal
# 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"
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 lecture seule et n'est pas renvoyé. Un déploiement progressif en pause est représenté par une valeur non nulle rolloutPausedAt.

[
{
"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"
}
]

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

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

interface Channel {
channel: string
app_id: string
delete_bundle?: boolean // also delete the linked bundle
}
Fenêtre de terminal
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/
{
"status": "ok"
}

Avec delete_bundle: true, un app_preview la clé peut nettoyer de manière atomique uniquement un 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.

Fenêtre de terminal
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/

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": {}
}
  1. Tests bêta
{
"app_id": "com.example.app",
"channel": "beta",
"version": "1.2.0-beta",
"public": false,
"allow_emulator": true,
"allow_dev": true
}
  1. Déploiement progressif en production
{
"app_id": "com.example.app",
"channel": "production",
"version": "1.2.0",
"public": true,
"disableAutoUpdate": "minor"
}
  1. Mises à jour spécifiques à la plateforme
{
"app_id": "com.example.app",
"channel": "ios-hotfix",
"version": "1.2.1",
"ios": true,
"android": false
}

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 dans la solution de tests bêta, Solution de ciblage de version pour le workflow produit dans la solution de ciblage de version, et Bonnes pratiques pour l'environnement Capgo : staging avec un seul ID d'app mobile pour le contexte pratique dans Capgo : bonnes pratiques d’environnement : staging avec un seul ID d’application mobile.