Dispositivos

Los dispositivos son instalaciones individuales de la app que envían metadatos del actualizador a Capgo. Usa esta API para recuperar esos metadatos o para establecer y eliminar un override de canal privado específico del dispositivo.

Dos políticas de 90 días

Inventario de dispositivos: los registros de dispositivos se conservan durante 90 días desde la última actividad del dispositivo. Un dispositivo no necesita instalar una actualización para aparecer: las comprobaciones de updater y estadísticas pueden actualizar su metadatos.

Sobrescrituras de canal: una sobrescritura POST se elimina 90 días después de la última escritura de sobrescritura, incluso si el dispositivo sigue haciendo check-in. Hacer check-in no reinicia ese temporizador. Para evitar esa limpieza, establece defaultChannel en la config de Capacitor (sobrevive a la reinstalación) o llamar setChannel() desde la app. El @capgo/capacitor-updater métodos setChannel() y unsetChannel() solo son compatibles con Android e iOS. En el plugin 5.34.0 / 6.34.0 / 7.34.0 / 8.0.0 y posteriores, setChannel() es local y no se elimina con esta limpieza. En Android e iOS con el updater 8.51.0 o superior, persistDefaultChannelOnReinstall por defecto es true, de modo que la asignación local solo pueda sobrevivir a una reinstalación cuando el sistema operativo restaure los datos de la app y la opción siga habilitada. Reinstalar con un updater anterior, hacer una instalación limpia sin restaurar los datos de la app o configurar persistDefaultChannelOnReinstall: false para la reinstalación puede borrar una asignación local. Usa unsetChannel() para borrar la elección local explícitamente; no elimina los overrides de console/API. Los plugins anteriores a las versiones de local-channel indicadas arriba escriben un override de backend que sobrevive a la reinstalación y esta limpieza lo elimina. Consulta Los overrides de Console y API caducan tras 90 días.

Metadatos del dispositivo

Cada registro puede incluir el ID del dispositivo, la plataforma, las versiones de updater y OS, el Native Build, el bundle instalado, el estado de producción y de emulador, el ID personalizado y el override de canal.

Cuando está disponible, country_code es el code de país ISO 3166-1 de dos letras válido más reciente recibido de una solicitud gestionada por Cloudflare para el dispositivo. No es GPS ni un valor de ubicación que proporcione tu app. Puede ser null cuando no está disponible; usa una búsqueda por dispositivo único cuando necesites este campo.

Endpoints

POST

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

Set a device-specific override to a canal privado. Para elegir un bundle para un dispositivo, asigna ese bundle al canal; no se admiten overrides de bundle directos por dispositivo. La override expira 90 días después de la última escritura a menos que vuelvas a hacer POST.

Cuerpo de la solicitud

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

Ejemplo de petición

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/

Los canales públicos no se pueden usar como overrides de dispositivo.

Respuesta exitosa

{
  "status": "ok"
}

GET

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

Obtén los metadatos del dispositivo. Los resultados usan paginación por cursor si omites device_id.

Parámetros de consulta

• app_id: ID de app en dominio inverso obligatorio, como com.example.app.
• device_id: ID de dispositivo opcional. Si se incluye, la respuesta será un único dispositivo en lugar de una lista paginada.
• customIdMode: Booleano opcional. Establecer en true para devolver solo dispositivos con un valor no vacío custom_id.
• cursor: Cursor opcional de la respuesta de la lista anterior.
• limit: Número opcional de dispositivos por página.

Ejemplos de peticiones

# 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"

Tipos de respuesta

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 se rellena mediante una búsqueda específica del dispositivo cuando Capgo ha almacenado un code de país válido derivado de Cloudflare. Las solicitudes sin un país válido no borran el último valor válido; las respuestas de lista pueden devolver null para este campo.

Ejemplo de respuesta (lista)

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

Ejemplo de respuesta (dispositivo único)

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

ELIMINAR

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

Elimina la sobrescritura de canal de un dispositivo. El dispositivo volverá a usar su selección de canal normal; este endpoint no elimina su registro de metadatos.

Cuerpo de la petición o parámetros de consulta

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

Ejemplo de petición

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/

Respuesta exitosa

{
  "status": "ok"
}

Errores

Los errores usan un código de estado HTTP y un cuerpo JSON con error y message campos. Los códigos de error comunes incluyen:

• invalid_app_id cuando app_id no es un identificador de dominio inverso.
• device_not_found para una búsqueda de un dispositivo desconocido.
• channel_not_found cuando el canal solicitado no existe.
• public_channel_override al intentar hacer override de un dispositivo a un canal público.
• invalid_version_id al intentar un bundle override directo; usa un channel en su lugar.
• cannot_access_app o cannot_access_channel cuando la clave API no tiene los permisos necesarios.

Casos de uso comunes

1. Mover un dispositivo de prueba a un canal beta privado

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

2. Restablecer un dispositivo a la selección de canal normal

   Usa la DELETE endpoint con los IDs de la app y el dispositivo.

Continuar desde Devices

Si estás usando Dispositivos para planificar el enrutamiento de canales y el despliegue gradual, conéctalo con Canales para los detalles de implementación en Channels, Canales para los detalles de implementación en Channels, Canales para los detalles de implementación en Channels, Solución de beta testing para el workflow del producto en la solución de beta testing, y Solución de segmentación por versión para el workflow del producto en la solución de segmentación por versión.