Zum Inhalt springen
Capgo - Build, ship und update Capacitor-Apps Capgo

Geräte

Devices sind einzelne App-Installationen, die Updater-Metadaten an Capgo melden. Nutze diese API, um diese Metadaten abzurufen oder einen gerätespezifischen Private-Channel-Override zu setzen oder zu entfernen.

Gerätemetadaten

Abschnitt mit dem Titel „Device metadata“

Jeder Datensatz kann die Device ID, Plattform, Updater- und OS-Versionen, Native Build, installiertes Bundle, Production- und Emulator-Status, eine Custom ID und einen Channel Override enthalten.

Falls verfügbar, country_code ist der aktuellste gültige zweistellige ISO 3166-1 Ländercode, der in einer von Cloudflare verarbeiteten Anfrage für das Gerät empfangen wurde. Es handelt sich nicht um GPS oder einen von deiner App bereitgestellten Standortwert. Er kann null sein, wenn nicht verfügbar; nutze einen Single-Device-Lookup, wenn du dieses Feld benötigst.

Endpoints

Abschnitt mit dem Titel „Endpoints“

POST

Abschnitt mit dem Titel „POST“

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

Setze einen gerätespezifischen Override für einen privaten Channel. Um ein Bundle für ein Gerät auszuwählen, weise dieses Bundle dem Channel zu; direkte Bundle-Overrides pro Gerät werden nicht unterstützt. Der Override läuft 90 Tage nach dem letzten Schreibvorgang ab, sofern kein erneuter POST erfolgt.

Request Body

Abschnitt mit dem Titel „Request Body“
interface DeviceChannelOverride {
  app_id: string; // reverse-domain app ID, for example com.example.app
  device_id: string;
  channel: string; // existing non-public channel name
}

Beispiel-Request

Abschnitt mit dem Titel „Beispiel-Request“
Terminalfenster
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/

Öffentliche Channels können nicht für Device Overrides genutzt werden.

Erfolgreiche Antwort

Abschnitt mit dem Titel „Erfolgreiche Antwort“
{
  "status": "ok"
}

GET

Abschnitt mit dem Titel „GET“

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

Geräte-Metadaten abrufen. Die Ergebnisse sind per Cursor-Pagination geliefert, wenn Sie device_id.

Query-Parameter

Abschnitt mit dem Titel „Query-Parameter“
  • app_id: Erforderliche App-ID im Reverse-Domain-Format, z. B. com.example.app.
  • device_id: Optionale Device-ID. Wenn angegeben, liefert die Response ein einzelnes Device statt einer paginierten Liste.
  • customIdMode: Optionaler Boolean. Auf true setzen, um nur Devices mit einem nicht-leeren custom_id.
  • cursor: Optionaler Cursor aus der vorherigen Listen-Response.
  • limit: Optionale Anzahl der Devices pro Seite.

Beispiel-Requests

Abschnitt mit dem Titel „Beispiel-Requests“
Terminalfenster
# 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"

Response-Typen

Abschnitt mit dem Titel „Response-Typen“
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 wird durch einen gerätespezifischen Lookup befüllt, wenn Capgo ein gültiges, aus Cloudflare abgeleitetes Land code gespeichert hat. Anfragen ohne gültiges Land löschen den letzten gültigen Wert nicht; Listen-Responses können null für dieses Feld zurückgeben.

Beispiel-Response (Liste)

Abschnitt „Beispiel-Response (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
}

Beispiel-Response (einzelnes Gerät)

Abschnitt „Beispiel-Response (einzelnes Gerät)“
{
  "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"
}

LÖSCHEN

Abschnitt „DELETE“

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

Entfernt den Channel-Override eines Geräts. Das Gerät nutzt danach wieder seine normale Channel-Auswahl; dieser Endpoint löscht seinen Metadaten-Eintrag nicht.

Request-Body oder Query-Parameter

Abschnitt „Request-Body oder Query-Parameter“
interface DeviceOverrideRemoval {
  app_id: string;
  device_id: string;
}

Beispiel-Request

Abschnitt „Beispiel-Request“
Terminalfenster
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/

Erfolgreiche Antwort

Abschnitt „Erfolgreiche Antwort“
{
  "status": "ok"
}

Fehler

Abschnitt „Fehler“

Fehler nutzen einen HTTP-Statuscode und einen JSON-Body mit error und message Felder. Zu den häufigsten Fehlercodes gehören:

  • invalid_app_id wenn app_id ist kein Reverse-Domain-Identifier.
  • device_not_found bei der Suche nach einem unbekannten Device.
  • channel_not_found wenn der angeforderte Channel nicht existiert.
  • public_channel_override beim Versuch, ein Device auf einen öffentlichen Channel zu überschreiben.
  • invalid_version_id beim Versuch eines direkten Bundle-Overrides; nutze stattdessen einen Channel.
  • cannot_access_app oder cannot_access_channel wenn dem API Key die erforderliche Berechtigung fehlt.

Häufige Anwendungsfälle

Abschnitt mit dem Titel „Häufige Anwendungsfälle“

  1. Testgerät in einen privaten Beta-Channel verschieben

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

  2. Gerät auf normale Channel-Auswahl zurücksetzen

    Nutze den DELETE Endpoint mit den App- und Device-IDs.

Weiter mit Devices

Abschnitt mit dem Titel „Weiter mit Devices“

Wenn Sie ... verwenden Geräte nutzt, um das Channel-Routing und Staged Rollouts zu planen, verbinde es mit Kanäle für die Implementierungsdetails in Channels, Kanäle für die Implementierungsdetails in Channels, Kanäle für die Implementierungsdetails in Channels, Beta-Testing-Lösung für den Produkt-Workflow in der Beta-Testing-Lösung, und Version-Targeting-Lösung für den Produkt-Workflow in der Version-Targeting-Lösung.