Saluran API Titik Akhir

Saluran adalah mekanisme inti untuk mengelola pembaruan aplikasi di Capgo. Dalam mode yang dihosting sendiri, Anda perlu menerapkan titik akhir saluran untuk menangani penetapan perangkat, kueri saluran, dan operasi pengelolaan saluran.

Memahami Saluran

Saluran memungkinkan Anda untuk:

• Kontrol distribusi pembaruan: Tetapkan versi aplikasi yang berbeda ke grup pengguna yang berbeda
• Pengujian A/B: Menguji fitur baru dengan segmen pengguna tertentu
• Peluncuran bertahap: Terapkan pembaruan secara bertahap untuk meminimalkan risiko
• Pemisahan lingkungan: Pisahkan pengembangan, staging, dan pembaruan produksi

Konfigurasi

Konfigurasikan URL titik akhir saluran di capacitor.config.json Anda:

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

Operasi Saluran

Plugin ini melakukan operasi saluran berbeda yang perlu ditangani oleh titik akhir Anda:

1. Daftar Saluran yang Kompatibel (GET Request)

Saat plugin memanggil listChannels(), plugin mengirimkan permintaan GET untuk mengambil semua saluran yang kompatibel dengan perangkat. Ini mengembalikan saluran yang cocok dengan lingkungan perangkat (dev/prod, emulator/perangkat nyata) dan mengizinkan akses publik atau penetapan mandiri.

Format Permintaan

// 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 Respons

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

Memahami Jenis Saluran

Responsnya mencakup dua tanda penting untuk setiap saluran:

• public: true: Ini adalah saluran default. Perangkat tidak dapat menetapkan sendiri ke perangkat tersebut menggunakan setChannel(). Sebaliknya, jika perangkat menghapus penetapan salurannya (menggunakan unsetChannel()), perangkat akan otomatis menerima pembaruan dari saluran publik ini jika cocok dengan kondisi perangkat.

• allow_self_set: true: Ini adalah saluran yang dapat ditetapkan sendiri. Perangkat dapat secara eksplisit menetapkan dirinya sendiri ke saluran ini menggunakan setChannel(). Ini berguna untuk pengujian beta, pengujian A/B, atau memungkinkan pengguna untuk ikut serta dalam jalur pembaruan tertentu.

Note

Saluran dapat berupa public ATAU allow_self_set, namun biasanya tidak keduanya. Saluran publik berfungsi sebagai pengganti default, sedangkan saluran yang dapat ditetapkan sendiri memerlukan keikutsertaan yang jelas.

2. Dapatkan Saluran (Permintaan PUT)

Saat plugin memanggil getChannel(), plugin mengirimkan permintaan PUT untuk mengambil penetapan saluran perangkat saat ini.

Format Permintaan

// 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 Respons

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

3. Atur Saluran (Permintaan POST)

Saat plugin memanggil setChannel(), plugin mengirimkan permintaan POST untuk menetapkan perangkat ke saluran tertentu.

Format Permintaan

// 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 Respons

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

Kasus Kesalahan

Saat perangkat mencoba menetapkan dirinya ke saluran publik (saluran dengan public: true), titik akhir Anda akan menampilkan 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 sendiri ke saluran yang tidak mengizinkan penetapan mandiri:

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

4. Saluran Tidak Disetel (Permintaan HAPUS)

Saat plugin memanggil unsetChannel(), plugin mengirimkan permintaan DELETE untuk menghapus penetapan saluran perangkat.

Format Permintaan

// 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 JavaScript contoh cara mengimplementasikan titik akhir saluran:

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 Saluran

Sistem saluran 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 Pemfilteran PerangkatSaat membuat daftar saluran yang kompatibel (permintaan GET), Anda harus memfilter saluran berdasarkan kondisi berikut:

1. Pemeriksaan platform: Saluran harus mengizinkan platform perangkat (ios, android, atau electron)
2. Pemeriksaan jenis perangkat:
   • Jika is_emulator=true: Saluran harus memiliki allow_emulator=true
   • Jika is_emulator=false: Saluran harus memiliki allow_device=true
3. Pemeriksaan tipe build:
   • Jika is_prod=true: Saluran harus memiliki allow_prod=true
   • Jika is_prod=false: Saluran harus memiliki allow_dev=true
4. Pemeriksaan visibilitas: Saluran harus 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 Basis Data

Anda harus menyimpan konfigurasi saluran dan penetapan perangkat:

-- 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 Kesalahan

Tangani skenario kesalahan umum:

// 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

1. Keamanan: Validasi semua penetapan saluran terhadap aturan bisnis Anda
2. Logging: Mencatat semua operasi saluran untuk audit dan debugging
3. Kinerja: Konfigurasi saluran cache untuk mengurangi kueri database
4. Validasi: Verifikasi keaslian device_id dan app_id
5. Pembatasan Tarif: Menerapkan pembatasan tarif untuk mencegah penyalahgunaan

Integrasi dengan Pembaruan

Penetapan saluran berfungsi sama dengan Titik Akhir API Pembaruan Anda. Saat perangkat meminta pembaruan, periksa penetapan salurannya untuk menentukan versi mana yang akan ditayangkan:

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

Hal ini menciptakan sistem manajemen saluran lengkap yang dihosting sendiri yang memberi Anda kendali penuh atas bagaimana pembaruan didistribusikan kepada pengguna Anda.