Perangkat

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

Devices adalah instalasi aplikasi individual yang melaporkan metadata updater ke Capgo. Gunakan API ini untuk mengambil metadata tersebut atau 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 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 di 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 akan 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 lebih lama, melakukan clean reinstall tanpa pemulihan data aplikasi, atau mengatur persistDefaultChannelOnReinstall: false untuk 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 override backend yang bertahan setelah reinstall dan akan dihapus oleh pembersihan ini. Lihat Override dari Console dan API kedaluwarsa setelah 90 hari.

Metadata perangkat

Setiap record dapat mencakup device ID, platform, versi updater dan OS, Native Build, bundle yang terinstal, status production dan emulator, custom ID, serta override channel.

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

Endpoint

POST

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

Set override khusus perangkat ke private channel. Untuk memilih bundle untuk perangkat, tetapkan bundle tersebut ke channel; override bundle per perangkat langsung tidak didukung. Override kedaluwarsa 90 hari setelah penulisan terakhir kecuali Anda POST-nya lagi.

Body permintaan

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 wajib, seperti 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 hanya perangkat dengan custom_id.
cursor: Cursor opsional dari respons daftar sebelumnya.
limit: Jumlah perangkat per halaman (opsional).

Contoh request

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

Tipe respons

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 oleh lookup khusus perangkat ketika Capgo telah menyimpan code negara valid yang diturunkan dari Cloudflare. Permintaan tanpa negara valid tidak menghapus nilai valid terakhir; respons daftar dapat mengembalikan null untuk field ini.

Contoh respons (daftar)

{
  "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 (satu perangkat)

{
  "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 override channel perangkat. Perangkat akan kembali menggunakan pemilihan channel normalnya; endpoint ini tidak menghapus record metadata-nya.

Body request atau parameter query

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

Contoh permintaan

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 error HTTP dan body JSON dengan error dan message field berikut. Kode error umum meliputi:

invalid_app_id saat app_id bukan identifier reverse-domain.
device_not_found untuk pencarian device yang tidak dikenal.
channel_not_found saat channel yang diminta tidak ada.
public_channel_override saat mencoba 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 aplikasi dan perangkat.

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.