Devices

Devices repräsentieren einzelne Installationen Ihrer App, die von Capgo verwaltet werden. Die Devices-API ermöglicht es Ihnen, Geräte zu verfolgen und zu verwalten, einschließlich ihrer Versionen, Kanäle und Update-Status.

Geräte verstehen

Jedes Gerät hat einzigartige Eigenschaften und Zustände:

Platform: iOS oder Android
Version: Aktuelle Bundle-Version und native Build-Version
Environment: Produktion oder Entwicklung, Emulator oder physisches Gerät
Channel: Aktuelle Update-Kanalzuweisung
Custom ID: Optionaler Identifikator für Ihre eigenen Tracking-Zwecke

Best Practices

Versionsverfolgung: Überwachen Sie Geräteversionen, um die Update-Akzeptanz sicherzustellen
Kanalverwaltung: Weisen Sie Geräte basierend auf Testanforderungen geeigneten Kanälen zu
Umgebungsbewusstsein: Behandeln Sie verschiedene Umgebungen (Prod/Dev/Emulator) angemessen
Benutzerdefinierte Identifikation: Verwenden Sie benutzerdefinierte IDs zur Integration mit Ihren bestehenden Systemen

Endpoints

POST

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

Verknüpfen Sie ein Gerät mit einer bestimmten Version oder einem Kanal.

Request Body

interface DeviceLink {
  app_id: string
  device_id: string
  version_id?: string // version name
  channel?: string    // channel name
}

Beispielanfrage

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

Erfolgsantwort

{
  "status": "ok"
}

GET

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

Abrufen von Geräteinformationen. Verwendet cursor-basierte Paginierung für effizientes Abrufen großer Gerätelisten.

Query-Parameter

app_id: Erforderlich. Die ID Ihrer App
device_id: Optional. Spezifische Geräte-ID zum Abrufen eines einzelnen Geräts
cursor: Optional. Cursor aus vorheriger Antwort für Paginierung
limit: Optional. Anzahl der Geräte pro Seite (Standard: 50)

Beispielanfrages

# Get all devices (first page)
curl -H "authorization: your-api-key" \
  "https://api.capgo.app/device/?app_id=app_123"

# Get specific device
curl -H "authorization: your-api-key" \
  "https://api.capgo.app/device/?app_id=app_123&device_id=device_456"

# Get next page using cursor
curl -H "authorization: your-api-key" \
  "https://api.capgo.app/device/?app_id=app_123&cursor=2024-01-01T00:00:00Z|device_456"

Antworttyp (Liste)

Bei Anforderung mehrerer Geräte (kein device_id Parameter):

interface DeviceListResponse {
  data: Device[];
  nextCursor?: string;  // Als 'cursor' Parameter übergeben, um nächste Seite zu erhalten
  hasMore: boolean;     // true wenn weitere Seiten verfügbar
}

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";
  plugin_version: string;
  os_version: string;
  version_build: string;
  is_prod: boolean;
  is_emulator: boolean;
}

Antworttyp (Einzelnes Gerät)

Bei Anforderung eines bestimmten Geräts mit device_id Parameter wird das Geräteobjekt direkt zurückgegeben:

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";
  plugin_version: string;
  os_version: string;
  version_build: string;
  is_prod: boolean;
  is_emulator: boolean;
}

Beispielantwort (Liste)

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

Beispielantwort (Einzelnes Gerät)

{
  "device_id": "device_456",
  "custom_id": "test-device-1",
  "version": 1,
  "version_name": "1.0.0",
  "app_id": "app_123",
  "platform": "ios",
  "plugin_version": "5.0.0",
  "os_version": "17.0",
  "version_build": "1",
  "is_prod": true,
  "is_emulator": false,
  "updated_at": "2024-01-01T00:00:00Z",
  "channel": "production"
}

DELETE

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

Trennen Sie ein Gerät von seiner Kanalüberschreibung. Dies setzt das Gerät zurück, um seinen Standardkanal zu verwenden.

Query Parameters

interface Device {
  device_id: string
  app_id: string
}

Beispielanfrage

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

Erfolgsantwort

{
  "status": "ok"
}

Fehlerbehandlung

Häufige Fehlerszenarien und ihre Antworten:

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

// Invalid version
{
  "error": "Version not found",
  "status": "KO"
}

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

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

Häufige Anwendungsfälle

Beta Device Registration

{
  "app_id": "app_123",
  "device_id": "device_456",
  "channel": "beta"
}

Version Override

{
  "app_id": "app_123",
  "device_id": "device_456",
  "version_id": "1.1.0"
}

Reset to Default Channel

// Use DELETE endpoint to remove overrides

Tipps zur Geräteverwaltung

Überwachung: Überprüfen Sie regelmäßig den Gerätestatus und die Versionsverteilung
Testen: Verwenden Sie benutzerdefinierte IDs, um Testgeräte einfach zu identifizieren
Fehlerbehebung: Verfolgen Sie Geräte-Updates und Kanalzuweisungen
Versionskontrolle: Überwachen Sie native App-Versionen, um Kompatibilität sicherzustellen