Appareils

Les appareils sont des installations individuelles de l'application qui transmettent les métadonnées de l'updater à Capgo. Utilisez cette API pour récupérer ces métadonnées, ou pour définir et supprimer un override de canal privé propre à l'appareil.

Deux politiques de 90 jours

Inventaire des appareils : les enregistrements d'appareils sont conservés pendant 90 jours de la dernière activité de l'appareil. Un appareil n'a pas besoin d'installer une mise à jour pour apparaître : les check-ins de l'updater et des stats peuvent rafraîchir ses métadonnées.

Overrides de canal : un override POST est supprimé 90 jours après la dernière écriture d'override, même si l'appareil continue de faire des check-ins. Le check-in ne réinitialise pas ce délai. Pour éviter ce nettoyage, configurez defaultChannel dans la config Capacitor (survit à la réinstallation) ou appelez setChannel() depuis l'app. Les @capgo/capacitor-updater méthodes setChannel() et unsetChannel() sont pris en charge uniquement sur Android et iOS. À partir des versions 5.34.0 / 6.34.0 / 7.34.0 / 8.0.0 du plugin, setChannel() est local et n'est pas supprimé par ce nettoyage. Sur Android et iOS avec l'updater 8.51.0 et les versions ultérieures, persistDefaultChannelOnReinstall par défaut sur true, afin que l'attribution locale puisse survivre à la réinstallation uniquement si le système d'exploitation restaure les données de l'application et que l'option reste activée. Réinstaller avec un updater antérieur, effectuer une réinstallation propre sans restauration des données de l'application, ou définir persistDefaultChannelOnReinstall: false pour la réinstallation peut effacer une attribution locale. Utilisez unsetChannel() pour effacer explicitement le choix local ; cela ne supprime pas les overrides de console/API. Les plugins antérieurs aux versions de canal local ci-dessus écrivent un override backend qui survit à la réinstallation et est supprimé par ce nettoyage. Voir les overrides Console et API expirent après 90 jours.

Métadonnées de l'appareil

Chaque enregistrement peut inclure l'ID de l'appareil, la plateforme, les versions de l'updater et du système d'exploitation, le build natif, le bundle installé, l'état de production et d'émulateur, l'ID personnalisé et l'override de canal.

Lorsqu'il est disponible, country_code est le dernier code pays ISO 3166-1 à deux lettres valide code reçu d'une requête gérée par Cloudflare pour l'appareil. Il ne s'agit pas d'une valeur GPS ou d'une position fournie par votre application. Il peut être null lorsqu’il est indisponible ; utilisez une recherche par appareil unique si vous avez besoin de ce champ.

Endpoints

POST

https://api.capgo.app/device/

Définir une surcharge spécifique à un appareil privé . Pour choisir un bundle pour un appareil, assignez ce bundle au canal ; les surcharges directes de bundle par appareil ne sont pas prises en charge. La surcharge expire 90 jours après la dernière écriture, sauf si vous la POSTez à nouveau.

Corps de la requête

interface DeviceChannelOverride {
  app_id: string; // reverse-domain app ID, for example com.example.app
  device_id: string;
  channel: string; // existing non-public channel name
}

Exemple de requête

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

Les canaux publics ne peuvent pas être utilisés comme overrides d’appareil.

Réponse de succès

{
  "status": "ok"
}

GET

https://api.capgo.app/device/

Récupère les métadonnées de l’appareil. Les résultats sont paginés par curseur si vous omettez device_id.

Paramètres de requête

• app_id: identifiant d’application en domaine inversé, par exemple com.example.app.
• device_id: identifiant d’appareil facultatif. S’il est présent, la réponse est un appareil unique plutôt qu’une liste paginée.
• customIdMode: booléen facultatif. Définir sur true pour ne renvoyer que les appareils dont le custom_id.
• cursor: curseur facultatif issu de la réponse de liste précédente.
• limit: nombre facultatif d’appareils par page.

Exemples de requêtes

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

# Get one device, including its request-derived country when available
curl -H "authorization: your-api-key" \
  "https://api.capgo.app/device/?app_id=com.example.app&device_id=device_456"

# Get only devices with a custom ID
curl -H "authorization: your-api-key" \
  "https://api.capgo.app/device/?app_id=com.example.app&customIdMode=true"

# Get the next page
curl -H "authorization: your-api-key" \
  "https://api.capgo.app/device/?app_id=com.example.app&cursor=2024-01-01T00:00:00Z%7Cdevice_456"

Types de réponse

interface DeviceListResponse {
  data: Device[];
  nextCursor?: string;
  hasMore: boolean;
}

interface Device {
  updated_at: string;
  device_id: string;
  custom_id: string;
  version?: number;
  version_name: string | null;
  channel?: string;
  app_id: string;
  platform: "ios" | "android" | "electron";
  plugin_version: string;
  os_version: string;
  version_build: string;
  is_prod: boolean;
  is_emulator: boolean;
  key_id: string | null;
  install_source: string | null;
  country_code: string | null;
}

country_code est renseigné par une recherche spécifique à l’appareil lorsque Capgo a stocké un code de pays valide dérivé de Cloudflare. Les requêtes sans pays valide ne suppriment pas la dernière valeur valide ; les réponses de liste peuvent renvoyer null pour ce champ.

Exemple de réponse (liste)

{
  "data": [
    {
      "device_id": "device_456",
      "custom_id": "test-device-1",
      "version": 1,
      "version_name": "1.0.0",
      "app_id": "com.example.app",
      "platform": "ios",
      "plugin_version": "5.0.0",
      "os_version": "17.0",
      "version_build": "1",
      "is_prod": true,
      "is_emulator": false,
      "key_id": null,
      "install_source": null,
      "country_code": null,
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "nextCursor": "2024-01-01T00:00:00Z|device_456",
  "hasMore": true
}

Exemple de réponse (appareil unique)

{
  "device_id": "device_456",
  "custom_id": "test-device-1",
  "version": 1,
  "version_name": "1.0.0",
  "app_id": "com.example.app",
  "platform": "ios",
  "plugin_version": "5.0.0",
  "os_version": "17.0",
  "version_build": "1",
  "is_prod": true,
  "is_emulator": false,
  "key_id": "MIIB",
  "install_source": null,
  "country_code": "FR",
  "updated_at": "2024-01-01T00:00:00Z",
  "channel": "beta"
}

Supprimer

https://api.capgo.app/device/

Supprime la surcharge de canal d’un appareil. L’appareil utilisera à nouveau sa sélection de canal normale ; cet endpoint ne supprime pas son enregistrement de métadonnées.

Corps de la requête ou paramètres de requête

interface DeviceOverrideRemoval {
  app_id: string;
  device_id: string;
}

Exemple de requête

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

Réponse de succès

{
  "status": "ok"
}

Erreurs

Les erreurs renvoient un statut d'erreur HTTP et un corps JSON avec error et message des champs. Les codes d'erreur courants incluent :

• invalid_app_id Quand app_id n'est pas un identifiant de domaine inversé.
• device_not_found pour la recherche d'un appareil inconnu.
• channel_not_found lorsque le canal demandé n'existe pas.
• public_channel_override lors d'une tentative de forcer un appareil vers un canal public.
• invalid_version_id lors d'une tentative de surcharge directe de bundle ; utilisez plutôt un canal.
• cannot_access_app ou cannot_access_channel lorsque la clé API ne dispose pas de l'autorisation requise.

Cas d'usage courants

1. Déplacer un appareil de test vers un canal bêta privé

   {
     "app_id": "com.example.app",
     "device_id": "device_456",
     "channel": "beta"
   }

2. Rétablir la sélection de canal normale d’un appareil

   Utilisez le DELETE endpoint avec les ID de l’app et de l’appareil.

Continuer depuis Appareils

Si vous utilisez Appareils 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, Canaux pour les détails d'implémentation des canaux, Solution de bêta-test pour le workflow produit de la Solution de bêta-test, et Solution de ciblage de version pour le workflow produit de la Solution de ciblage de version.