Endpoint Channel API

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

Channel adalah mekanisme inti untuk mengelola update aplikasi di Capgo. Dalam mode self-hosted, Anda perlu mengimplementasikan endpoint channel untuk menangani penugasan perangkat, query channel, dan operasi manajemen channel.

Memahami Channels

Channel memungkinkan Anda untuk:

Mengontrol distribusi update: Menugaskan versi app berbeda ke grup user berbeda
A/B testing: Test fitur baru ke segmen user tertentu
Rollout bertahap: Deploy update secara bertahap untuk minimalkan risiko
Pemisahan environment: Pisahkan update development, staging, dan production

Konfigurasi

Konfigurasikan URL endpoint channel di capacitor.config.json:

{
  "plugins": {
    "CapacitorUpdater": {
      "channelUrl": "https://myserver.com/api/channel_self"
    }
  }
}

Operasi Channel

Plugin melakukan berbagai operasi channel yang perlu ditangani endpoint Anda:

1. Daftar Channel yang Kompatibel (GET Request)

Saat plugin memanggil listChannels(), plugin mengirimkan request GET untuk mengambil semua channel yang kompatibel dengan perangkat. Ini mengembalikan channel yang cocok dengan environment perangkat (dev/prod, emulator/perangkat fisik) dan mengizinkan akses publik maupun self-assignment.

Format Request

// GET /api/channel_self
// Headers:
{
  "Content-Type": "application/json"
}

// Query parameters:
interface ListChannelsRequest {
  app_id: string
  platform: "ios" | "android" | "electron"
  is_emulator: boolean
  is_prod: boolean
  key_id?: string
}

Format Response

[
  {
    "id": 1,
    "name": "production",
    "public": true,
    "allow_self_set": false
  },
  {
    "id": 2,
    "name": "beta",
    "public": false,
    "allow_self_set": true
  }
]

Memahami Tipe Channel

Response menyertakan dua flag penting untuk setiap channel:

public: true: Ini adalah channel default. Devices cannot self-assign to it using setChannel(). Sebaliknya, jika device menghapus channel assignment-nya (menggunakan unsetChannel()), device akan otomatis menerima update dari public channel ini jika sesuai dengan kondisi device.
allow_self_set: true: Ini adalah sebuah channel yang bisa diatur sendiri. Perangkat dapat secara eksplisit mendaftarkan diri ke channel ini menggunakan setChannel(). Ini berguna untuk beta testing, A/B testing, atau mengizinkan pengguna memilih track update tertentu.

2. Ambil Channel (Request PUT)

Saat plugin memanggil getChannel(), ia mengirimkan request PUT untuk mengambil penugasan channel perangkat saat ini.

Format Request

// PUT /api/channel_self
// Headers:
{
  "Content-Type": "application/json"
}

// Body:
interface GetChannelRequest {
  device_id: string
  app_id: string
  platform: "ios" | "android" | "electron"
  plugin_version: string
  version_build: string
  version_code: string
  version_name: string
  is_emulator: boolean
  is_prod: boolean
  defaultChannel?: string
  channel?: string  // For newer plugin versions, contains local channel override
}

Format Response

{
  "status": "ok",
  "channel": "production",
  "allowSet": true,
  "message": "",
  "error": ""
}

3. Atur Channel (Request POST)

Saat plugin memanggil setChannel(), ia mengirimkan request POST untuk menetapkan perangkat ke channel tertentu.

Format Request

// POST /api/channel_self
interface SetChannelRequest {
  device_id: string
  app_id: string
  channel: string
  platform: "ios" | "android" | "electron"
  plugin_version: string
  version_build: string
  version_code: string
  version_name: string
  is_emulator: boolean
  is_prod: boolean
}

Format Response

{
  "status": "ok",
  "message": "Device assigned to channel successfully",
  "error": ""
}

Kasus Error

Saat perangkat mencoba mendaftarkan diri ke channel publik (yang memiliki public: true), endpoint Anda harus mengembalikan error:

{
  "status": "error",
  "error": "public_channel_self_set_not_allowed",
  "message": "This channel is public and does not allow device self-assignment. Unset the channel and the device will automatically use the public channel."
}

Saat perangkat mencoba menetapkan dirinya ke channel yang tidak mengizinkan self-assignment:

{
  "status": "error",
  "error": "channel_self_set_not_allowed",
  "message": "This channel does not allow devices to self associate"
}

4. Hapus Channel (Request DELETE)

Saat plugin memanggil unsetChannel(), perangkat akan mengirimkan request DELETE untuk menghapus penetapan channel tersebut.

Format Request

// DELETE /api/channel_self
interface UnsetChannelRequest {
  device_id: string
  app_id: string
  platform: "ios" | "android" | "electron"
  plugin_version: string
  version_build: string
  version_code: string
  version_name: string
}

Contoh Implementasi

Berikut adalah contoh JavaScript untuk mengimplementasikan endpoint channel:

interface ChannelRequest {
  device_id: string
  app_id: string
  channel?: string
  platform: "ios" | "android" | "electron"
  plugin_version: string
  version_build: string
  version_code: string
  version_name: string
}

interface ChannelResponse {
  status: "ok" | "error"
  channel?: string
  allowSet?: boolean
  message?: string
  error?: string
}

export const handler = async (event) => {
  const method = event.httpMethod || event.method
  const body = JSON.parse(event.body || '{}') as ChannelRequest

  const { device_id, app_id, channel, platform } = body

  try {
    switch (method) {
      case 'GET':
        return await getDeviceChannel(device_id, app_id)

      case 'POST':
        return await setDeviceChannel(device_id, app_id, channel!, platform)

      case 'DELETE':
        return await unsetDeviceChannel(device_id, app_id)

      default:
        return {
          status: "error",
          error: "Method not allowed"
        }
    }
  } catch (error) {
    return {
      status: "error",
      error: error.message
    }
  }
}

async function getDeviceChannel(deviceId: string, appId: string): Promise<ChannelResponse> {
  // Query your database for device channel assignment
  const assignment = await database.getDeviceChannel(deviceId, appId)

  if (assignment) {
    return {
      status: "ok",
      channel: assignment.channel,
      allowSet: assignment.allowSelfAssign
    }
  }

  // Return default channel if no assignment found
  return {
    status: "ok",
    channel: "production", // Your default channel
    allowSet: true
  }
}

async function setDeviceChannel(
  deviceId: string,
  appId: string,
  channel: string,
  platform: string
): Promise<ChannelResponse> {
  // Validate channel exists and allows self-assignment
  const channelConfig = await database.getChannelConfig(channel, appId)

  if (!channelConfig) {
    return {
      status: "error",
      error: "Channel not found"
    }
  }

  if (!channelConfig.allowDeviceSelfSet) {
    return {
      status: "error",
      error: "Channel does not allow self-assignment"
    }
  }

  // Check platform restrictions
  if (platform === "ios" && !channelConfig.ios) {
    return {
      status: "error",
      error: "Channel not available for iOS"
    }
  }

  if (platform === "android" && !channelConfig.android) {
    return {
      status: "error",
      error: "Channel not available for Android"
    }
  }

  if (platform === "electron" && !channelConfig.electron) {
    return {
      status: "error",
      error: "Channel not available for Electron"
    }
  }

  // Save the assignment
  await database.setDeviceChannel(deviceId, appId, channel)

  return {
    status: "ok",
    message: "Device assigned to channel successfully"
  }
}

async function unsetDeviceChannel(deviceId: string, appId: string): Promise<ChannelResponse> {
  // Remove device channel assignment
  await database.removeDeviceChannel(deviceId, appId)

  return {
    status: "ok",
    message: "Device channel assignment removed"
  }
}

Konfigurasi Channel

Sistem channel Anda harus mendukung opsi konfigurasi berikut:

interface ChannelConfig {
  name: string
  appId: string

  // Platform targeting
  ios: boolean              // Allow updates to iOS devices
  android: boolean          // Allow updates to Android devices
  electron: boolean         // Allow updates to Electron apps

  // Device type restrictions
  allow_emulator: boolean   // Allow updates on emulator/simulator devices
  allow_device: boolean     // Allow updates on real/physical devices

  // Build type restrictions
  allow_dev: boolean        // Allow updates on development builds (is_prod=false)
  allow_prod: boolean       // Allow updates on production builds (is_prod=true)

  // Channel assignment
  public: boolean           // Default channel - devices fall back to this when no override
  allowDeviceSelfSet: boolean  // Allow devices to self-assign via setChannel()

  // Update policies
  disableAutoUpdate: "major" | "minor" | "version_number" | "none"
  disableAutoUpdateUnderNative: boolean
}

Logika Filtering Device

Saat menampilkan daftar channel yang kompatibel (request GET), Anda harus memfilter channel berdasarkan kondisi berikut:

Pengecekan platform: Channel harus mengizinkan platform perangkat tersebut (ios, android, atau electron)
Pengecekan tipe perangkat:
- Jika is_emulator=true: Channel harus memiliki allow_emulator=true
- Jika is_emulator=false: Channel harus memiliki allow_device=true
Cek tipe build:
- Jika is_prod=true: Channel harus memiliki allow_prod=true
- Jika is_prod=false: Channel harus memiliki allow_dev=true
Cek visibilitas: Channel harus berupa public=true ATAU allow_device_self_set=true

// Example filtering logic
function getCompatibleChannels(
  platform: 'ios' | 'android' | 'electron',
  isEmulator: boolean,
  isProd: boolean,
  channels: ChannelConfig[]
): ChannelConfig[] {
  return channels.filter(channel => {
    // Platform check
    if (!channel[platform]) return false

    // Device type check
    if (isEmulator && !channel.allow_emulator) return false
    if (!isEmulator && !channel.allow_device) return false

    // Build type check
    if (isProd && !channel.allow_prod) return false
    if (!isProd && !channel.allow_dev) return false

    // Must be accessible (public or self-assignable)
    if (!channel.public && !channel.allowDeviceSelfSet) return false

    return true
  })
}

Contoh Skema Database

Anda perlu menyimpan konfigurasi channel dan penugasan device:

-- Channels table
CREATE TABLE channels (
  id SERIAL PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  app_id VARCHAR(255) NOT NULL,

  -- Platform targeting
  ios BOOLEAN DEFAULT true,
  android BOOLEAN DEFAULT true,
  electron BOOLEAN DEFAULT true,

  -- Device type restrictions
  allow_emulator BOOLEAN DEFAULT true,   -- Allow emulator/simulator devices
  allow_device BOOLEAN DEFAULT true,     -- Allow real/physical devices

  -- Build type restrictions
  allow_dev BOOLEAN DEFAULT true,        -- Allow development builds
  allow_prod BOOLEAN DEFAULT true,       -- Allow production builds

  -- Channel assignment
  public BOOLEAN DEFAULT false,          -- Default channel (fallback)
  allow_device_self_set BOOLEAN DEFAULT false,  -- Allow self-assignment

  -- Update policies
  disable_auto_update VARCHAR(50) DEFAULT 'none',
  disable_auto_update_under_native BOOLEAN DEFAULT false,

  created_at TIMESTAMP DEFAULT NOW(),
  UNIQUE(name, app_id)
);

-- Device channel assignments table
CREATE TABLE device_channels (
  id SERIAL PRIMARY KEY,
  device_id VARCHAR(255) NOT NULL,
  app_id VARCHAR(255) NOT NULL,
  channel_name VARCHAR(255) NOT NULL,
  assigned_at TIMESTAMP DEFAULT NOW(),
  UNIQUE(device_id, app_id)
);

Penanganan error

Tangani skenario error yang umum terjadi:

// Channel not found
{
  "status": "error",
  "error": "Channel 'beta' not found"
}

// Self-assignment not allowed
{
  "status": "error",
  "error": "Channel does not allow device self-assignment"
}

// Platform not supported
{
  "status": "error",
  "error": "Channel not available for this platform"
}

// Invalid request
{
  "status": "error",
  "error": "Missing required field: device_id"
}

Praktik Terbaik

Keamanan: Validasi semua penetapan channel sesuai aturan bisnis Anda
Logging: Log semua operasi channel untuk audit dan debugging
Performa: Cache konfigurasi channel untuk mengurangi query database
Validasi: Verifikasi autentisitas device_id dan app_id
Pembatasan Laju (Rate Limiting): Implementasikan rate limiting untuk mencegah penyalahgunaan

Integrasi dengan Updates

Penetapan channel bekerja bersama dengan Endpoint Update API. Saat perangkat meminta update, periksa penugasan channel-nya untuk menentukan versi mana yang akan dikirim:

async function getUpdateForDevice(deviceId: string, appId: string) {
  // Get device's channel assignment
  const channelAssignment = await getDeviceChannel(deviceId, appId)
  const channel = channelAssignment.channel || 'production'

  // Get the version assigned to this channel
  const channelVersion = await getChannelVersion(channel, appId)

  return {
    version: channelVersion.version,
    url: channelVersion.url,
    checksum: channelVersion.checksum
  }
}

Ini menciptakan sistem manajemen channel self-hosted lengkap yang memberi Anda kontrol penuh atas cara distribusi update ke pengguna.

Lanjutkan dari Endpoint Channel API

Jika Anda menggunakan Endpoint Channel API untuk merencanakan routing channel dan staged rollout, hubungkan dengan Menggunakan @capgo/capacitor-updater untuk fitur native di bagian Menggunakan @capgo/capacitor-updater, Channel untuk detail implementasi di Channels, Channel untuk detail implementasi di Channels, Channel untuk detail implementasi di Channels, dan Solusi Beta Testing untuk alur kerja produk di Beta Testing Solution.