Perangkat

Salin prompt setup yang berisi langkah install dan panduan markdown lengkap untuk plugin ini.

Device adalah instalasi aplikasi individual yang mengirimkan metadata updater ke Capgo. Gunakan API ini untuk mengambil metadata tersebut atau untuk mengatur dan menghapus override private-channel khusus perangkat.

Inventaris perangkat: catatan perangkat disimpan selama 90 hari dari aktivitas perangkat terakhir. Perangkat tidak perlu menginstal update agar muncul: check-in updater dan stats dapat memperbarui metadatanya.

Override Channel: POST override akan dihapus 90 hari setelah penulisan override terakhir, meskipun perangkat masih melakukan check-in. Check-in tidak akan mereset timer tersebut. Untuk menghindari pembersihan itu, atur defaultChannel pada konfigurasi Capacitor (tetap ada setelah reinstall) atau panggil setChannel() dari aplikasi. Metode @capgo/capacitor-updater tersebut setChannel() dan unsetChannel() hanya didukung di Android dan iOS. Pada plugin 5.34.0 / 6.34.0 / 7.34.0 / 8.0.0 dan versi setelahnya, setChannel() bersifat lokal dan tidak dihapus oleh pembersihan ini. Pada Android dan iOS dengan updater 8.51.0 dan versi setelahnya, persistDefaultChannelOnReinstall defaultnya adalah true, sehingga assignment lokal hanya bisa bertahan saat reinstall jika OS memulihkan data aplikasi dan opsi tersebut tetap aktif. Reinstall dengan updater versi lama, melakukan clean reinstall tanpa pemulihan data, atau mengatur persistDefaultChannelOnReinstall: false saat reinstall dapat menghapus assignment lokal. Gunakan unsetChannel() untuk menghapus pilihan lokal secara eksplisit; ini tidak menghapus override console/API. Plugin yang lebih lama dari versi local-channel di atas menulis backend override yang bertahan saat reinstall dan dihapus oleh pembersihan ini. Lihat Override dari Console dan API kedaluwarsa setelah 90 hari.

Metadata device

Setiap record dapat mencakup device ID, platform, versi updater dan OS, native build, bundle yang terinstal, status produksi dan emulator, custom ID, serta channel override.

Jika tersedia, country_code adalah kode negara ISO 3166-1 dua huruf code terbaru yang diterima dari request yang ditangani Cloudflare untuk device tersebut. Ini bukan GPS atau nilai lokasi dari aplikasi Anda. Bisa berupa null saat tidak tersedia; gunakan pencarian single-device jika Anda memerlukan field ini.

Endpoint

POST

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

Atur override spesifik perangkat ke private channel. Untuk memilih bundle bagi sebuah perangkat, assign bundle tersebut ke channel; override bundle langsung per-perangkat tidak didukung. Override akan kedaluwarsa dalam 90 hari setelah penulisan terakhir kecuali Anda melakukan POST kembali.

Body request

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

Contoh request

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/

Channel publik tidak bisa dipakai sebagai device override.

Respons sukses

{
  "status": "ok"
}

GET

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

Ambil metadata device. Hasil dipaginasi dengan cursor jika Anda tidak menyertakan device_id.

Parameter query

app_id: ID aplikasi reverse-domain yang wajib, contohnya com.example.app.
device_id: ID perangkat opsional. Jika diisi, respons akan berupa satu perangkat tunggal, bukan daftar terpaginasi.
customIdMode: Boolean opsional. Set ke true untuk mengembalikan perangkat dengan custom_id.
cursor: Cursor opsional dari respons daftar sebelumnya.
limit: Cursor opsional dari respons daftar sebelumnya.

: Jumlah perangkat per halaman (opsional).

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

Bagian berjudul “Contoh request”

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 diisi melalui lookup spesifik perangkat saat Capgo telah menyimpan code negara yang valid dari Cloudflare. Request tanpa negara yang valid tidak akan menghapus nilai valid terakhir; respons list mungkin mengembalikan null untuk field ini.

Contoh respons (list)

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

Contoh respons (single device)

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

HAPUS

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

Hapus channel override perangkat. Perangkat akan kembali menggunakan pemilihan channel normal; endpoint ini tidak menghapus record metadatanya.

Body request atau parameter query

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

Contoh request

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/

Respons sukses

{
  "status": "ok"
}

Error

Error menggunakan status HTTP error dan body JSON dengan error dan message field berikut. Kode error umum meliputi:

invalid_app_id saat app_id bukan merupakan reverse-domain identifier.
device_not_found untuk pencarian device yang tidak dikenal.
channel_not_found saat channel yang diminta tidak ada.
public_channel_override saat mencoba melakukan override device ke public channel.
invalid_version_id saat mencoba direct bundle override; gunakan channel sebagai gantinya.
cannot_access_app atau cannot_access_channel saat key API tidak memiliki permission yang diperlukan.

Kasus penggunaan umum

Pindahkan perangkat uji ke channel beta privat

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

Reset perangkat ke pemilihan channel normal

Gunakan DELETE endpoint dengan ID app dan device.

Lanjutkan dari Perangkat

Jika Anda menggunakan Perangkat untuk merencanakan routing channel dan staged rollout, hubungkan dengan Channel untuk detail implementasi di Channels, Channel untuk detail implementasi di Channels, Channel untuk detail implementasi di Channels, Solusi Beta Testing untuk workflow produk di Solusi Beta Testing, dan Solusi Version Targeting untuk workflow produk di Version Targeting Solution.