Dispositivi

Copia un prompt di configurazione con i passaggi di installazione e la guida markdown completa per questo plugin.

I Device sono singole installazioni dell'app che inviano i metadati dell'updater a Capgo. Usa questa API per recuperare tali metadati o per impostare e rimuovere un override del canale privato specifico per il dispositivo.

Inventario dispositivi: i record dei dispositivi vengono conservati per 90 giorni dall'ultima attività del dispositivo. Non è necessario installare un aggiornamento per visualizzarlo: i check-in di updater e stats possono aggiornarne i metadati.

Override dei canali: un override POST viene rimosso 90 giorni dopo l'ultima scrittura dell'override, anche se il dispositivo continua a effettuare il check-in. Il check-in non resetta il timer. Per evitare la pulizia, imposta defaultChannel in Capacitor config (survives reinstall) or call setChannel() dall'app. Il @capgo/capacitor-updater metodi setChannel() e unsetChannel() sono supportati solo su Android e iOS. Con il plugin 5.34.0 / 6.34.0 / 7.34.0 / 8.0.0 e versioni successive, setChannel() è locale e non viene rimosso da questa pulizia. Su Android e iOS con updater 8.51.0 e versioni successive, persistDefaultChannelOnReinstall ha come default true, in modo che l'assegnazione locale sopravviva alla reinstallazione solo se il sistema operativo ripristina i dati dell'app e l'opzione rimane attiva. Reinstallare con un updater precedente, eseguire una reinstallazione pulita senza ripristino dati o impostare persistDefaultChannelOnReinstall: false per la reinstallazione può cancellare un'assegnazione locale. Usa unsetChannel() per cancellare esplicitamente la scelta locale; non elimina gli override in console/API. I plugin precedenti alle versioni local-channel sopra citate scrivono un override sul backend che sopravvive alla reinstallazione e viene rimosso da questa pulizia. Vedi Gli override di Console e API scadono dopo 90 giorni.

Metadati del dispositivo

Ogni record può includere il device ID, la piattaforma, le versioni di updater e OS, il Native Build, il bundle installato, lo stato di produzione o emulatore, l'ID personalizzato e l'override del channel.

Quando disponibile, country_code è il più recente codice paese ISO 3166-1 di due lettere code ricevuto da una richiesta gestita da Cloudflare per il dispositivo. Non è un valore GPS o di posizione fornito dalla tua app. Può essere null quando non disponibile; usa una ricerca per singolo dispositivo se ti serve questo campo.

Endpoint

POST

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

Set a device-specific override to a canale privato. Per scegliere un bundle per un dispositivo, assegna quel bundle al canale; non sono supportati gli override diretti del bundle per singolo dispositivo. L'override scade dopo 90 giorni dall'ultimo aggiornamento, a meno che non venga eseguito nuovamente un POST.

Corpo della richiesta

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

Esempio di richiesta

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/

I canali pubblici non possono essere usati come override di device.

Risposta di successo

{
  "status": "ok"
}

GET

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

Recupera i metadati del device. I risultati sono paginati tramite cursore quando ometti device_id.

Parametri di query

app_id: ID app in reverse-domain richiesto, ad esempio com.example.app.
device_id: ID dispositivo opzionale. Se presente, la risposta conterrà un singolo dispositivo invece di una lista paginata.
customIdMode: Booleano opzionale. Imposta a true per restituire solo i dispositivi con un custom_id.
cursor: Cursor opzionale dalla risposta della lista precedente.
limit: Numero opzionale di dispositivi per pagina.

Esempi di richieste

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

Tipi di risposta

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 viene popolato tramite un lookup specifico per il dispositivo quando Capgo ha memorizzato un code di paese valido derivato da Cloudflare. Le richieste senza un paese valido non cancellano l'ultimo valore valido; le risposte della lista possono restituire null per questo campo.

Risposta di esempio (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
}

Risposta di esempio (singolo dispositivo)

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

ELIMINA

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

Rimuove l'override del canale di un dispositivo. Il dispositivo tornerà a usare la normale selezione del canale; questo endpoint non elimina il record dei metadati.

Corpo della richiesta o parametri query

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

Esempio di richiesta

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/

Risposta di successo

{
  "status": "ok"
}

Errori

Gli errori utilizzano un codice di stato HTTP e un corpo JSON con error e message campi. I codici di errore comuni includono:

invalid_app_id quando app_id non è un identificatore reverse-domain.
device_not_found per una ricerca di un dispositivo sconosciuto.
channel_not_found quando il canale richiesto non esiste.
public_channel_override durante il tentativo di sovrascrivere un dispositivo con un canale pubblico.
invalid_version_id durante un tentativo di bundle override diretto; usa un canale al suo posto.
cannot_access_app o cannot_access_channel quando la chiave API non ha i permessi necessari.

Casi d'uso comuni

Sposta un dispositivo di test su un canale beta privato

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

Ripristina la selezione del canale normale per un dispositivo

Usa il DELETE endpoint con gli ID dell'app e del dispositivo.

Continua da Devices

Se stai usando Dispositivi per pianificare il routing dei canali e il rollout graduale, connettilo a Canali per i dettagli di implementazione nei Channels, Canali per i dettagli di implementazione nei Channels, Canali per i dettagli di implementazione nei Channels, Soluzione Beta Testing per il workflow di prodotto nella Soluzione Beta Testing, e Soluzione Version Targeting per il workflow di prodotto nella Soluzione Version Targeting.