Lebih lanjut ke konten
Capgo - Update Hidup untuk Aplikasi Capacitor Capgo

Endpoint Saluran API

GitHub

Saluran adalah mekanisme inti untuk mengelola pembaruan aplikasi di Capgo. Dalam mode self-hosted, Anda perlu mengimplementasikan endpoint saluran untuk menghandle pengasasan perangkat, pertanyaan saluran, dan operasi manajemen saluran.

Paham Saluran

Bab berjudul “Paham Saluran”

Saluran memungkinkan Anda:

  • Mengontrol distribusi pembaruan: Mengasignkan versi aplikasi yang berbeda kepada kelompok pengguna yang berbeda
  • Pengujian A/B: Menguji fitur baru dengan segmen pengguna tertentu
  • Rollout yang Dipersiapkan: Meluncurkan pembaruan secara bertahap untuk mengurangi risiko
  • Pemisahan Lingkungan: Memisahkan pembaruan pengembangan, pengujian, dan produksi

Konfigurasi

: Bagian berjudul “Konfigurasi”

Konfigurasi URL Endpoint Saluran di dalam capacitor.config.json:

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

Operasi Saluran

: Bagian berjudul “Operasi Saluran”

Plugin melakukan operasi saluran yang berbeda yang perlu diolah oleh endpoint Anda:

1. Daftar Saluran yang Kompatibel (Permintaan GET)

Judul Bagian: “1. Daftar Saluran yang Kompatibel (GET Request)”

Ketika plugin memanggil listChannels(), maka plugin mengirimkan permintaan GET untuk mengambil semua saluran yang kompatibel dengan perangkat. Hal ini mengembalikan saluran yang sesuai dengan lingkungan perangkat (dev/prod, emulator/real device) dan memungkinkan akses publik atau pengasasan sendiri.

Format Permintaan

Judul Bagian: “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

Judul Bagian: “Format Respons”
[
  {
    "id": 1,
    "name": "production",
    "public": true,
    "allow_self_set": false
  },
  {
    "id": 2,
    "name": "beta",
    "public": false,
    "allow_self_set": true
  }
]

Pengertian Tipe Saluran

Judul Bagian: “Pengertian Tipe Saluran”

Responsnya termasuk dua flag penting untuk setiap saluran:

  • public: true: Ini adalah saluran default. Perangkat tidak dapat menetapkan diri sendiri ke saluran ini menggunakan setChannel(). Sebaliknya, jika perangkat menghapus penugasan saluran (menggunakan unsetChannel()), maka perangkat akan secara otomatis menerima update dari saluran publik ini jika saluran tersebut sesuai dengan kondisi perangkat.

  • allow_self_set: true: Ini adalah saluran yang dapat ditetapkan oleh perangkat. Perangkat dapat menetapkan diri sendiri ke saluran ini secara eksplisit menggunakan setChannel(). Hal ini berguna untuk tes beta, tes A/B, atau memungkinkan pengguna untuk memilih update tertentu.

2. Dapatkan Saluran (Request PUT)

Bagian berjudul “2. Dapatkan Saluran (Request PUT)”

Ketika plugin memanggil getChannel()itu mengirimkan permintaan PUT untuk memperoleh penugasan saluran perangkat saat ini.

Format Permintaan

Salinan ke clipboard
// 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
}

Bagian berjudul “Format Respons”

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

3. Atur Saluran (Permintaan POST)

Judul Bagian “3. Atur Saluran (Permintaan POST)”

Ketika plugin memanggil setChannel()itu mengirimkan permintaan POST untuk menetapkan perangkat ke saluran tertentu.

Format Permintaan

Judul Bagian “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

Judul Bagian “Format Respons”
{
  "status": "ok",
  "message": "Device assigned to channel successfully",
  "error": ""
}

Kasus Kesalahan

Judul Bagian “Kasus Kesalahan”

When perangkat mencoba untuk menetapkan dirinya ke sebuah Pengaturan publik (salah satu dengan public: true), endpoint Anda harus mengembalikan sebuah kesalahan:

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

When perangkat mencoba untuk menetapkan dirinya ke sebuah saluran yang tidak memungkinkan penugasan diri sendiri:

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

4. Hapus Saluran (DELETE Request)

Bab berjudul “4. Hapus Saluran (DELETE Request)”

When plugin memanggil unsetChannel(), plugin mengirimkan sebuah permintaan DELETE untuk menghapus penugasan saluran perangkat.

Format Permintaan

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

Judul Bagian “Contoh Implementasi”

Contoh berikut adalah implementasi JavaScript untuk endpoint 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

Judul Bagian “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 Perangkat

Judul Bagian “Logika Pemfilteran Perangkat”

Mengenai daftar saluran yang kompatibel (permintaan GET), Anda harus menyaring saluran berdasarkan kondisi-kondisi berikut:

  1. Pengecekan platform: Saluran harus memungkinkan platform perangkat ('ios, android, atau electron)
  2. Pengecekan jenis perangkat:
    • Jika is_emulator=true: Saluran harus memiliki allow_emulator=true
    • Jika is_emulator=false: Saluran harus memiliki allow_device=true
  3. Pengecekan jenis konstruksi:
    • Jika is_prod=true: Saluran harus memiliki allow_prod=true
    • Jika is_prod=false: Saluran harus memiliki allow_dev=true
  4. Pengecekan Visibilitas: Saluran harus merupakan salah satu 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

Bab berjudul “Contoh Skema Basis Data”

Anda perlu menyimpan konfigurasi saluran dan penugasan 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)
);

Pengelolaan Kesalahan

Bab berjudul “Pengelolaan Kesalahan”

Menangani 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

Judul bagian “Praktik Terbaik”
  1. Keamanancontext: Halaman/area: Halaman produk/pricing perusahaan. Peran: Label UI. Dilihat di: halaman enterprise.astro. Kunci pesan `enterprise_hero_security_label` (Label Keamanan Hero Perusahaan).
  2. Validasi semua pengaturan saluran terhadap aturan bisnis AndaPengaturan Log
  3. : Catat semua operasi saluran untuk auditing dan debuggingKinerja
  4. context: Halaman/area: Bagian atau halaman judul. Dilihat di: halaman premium-support.astro. Kunci pesan `ps_help_performance_title` (Judul Bantuan Kinerja Ps).: Simpan konfigurasi saluran ke cache untuk mengurangi kueri database
  5. Pengaturan Batas: Implementasikan pengaturan batas untuk mencegah penyalahgunaan

Pengintegrasian dengan Perbarui

Bab berjudul “Pengintegrasian dengan Perbarui”

Penugasan saluran bekerja sama dengan Endpoint Perbarui API. Ketika perangkat meminta perbarui, periksa penugasan saluran untuk menentukan versi mana yang harus disajikan:

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 saluran mandiri yang lengkap yang memberi Anda kendali penuh atas bagaimana perbarui disebarkan kepada pengguna Anda.

Teruskan dari Endpoint Saluran API

Bab berjudul “Teruskan dari Endpoint Saluran API”

Jika Anda menggunakan Saluran API Endpoint untuk merencanakan routing saluran dan peluncuran tahap demi tahap, hubungkannya dengan Menggunakan @capgo/capacitor-updater untuk kemampuan asli dalam Menggunakan @capgo/capacitor-updater, Saluran-Saluran context: Fitur nama saluran rilis Capgo. Halaman/Areas: Halaman pemasaran solusi Capgo. Peran: Label UI singkat atau item navigasi. Dilihat di: halaman solusi/white-label.astro. Kunci pesan `solutions_white_label_visual_cell2_value` (Nilai Sel Tampilan Putih Label Solusi). untuk detail implementasi dalam Saluran-Saluran, Saluran-Saluran context: Fitur nama saluran rilis Capgo. Halaman/Areas: Halaman pemasaran solusi Capgo. Peran: Label UI singkat atau item navigasi. Dilihat di: halaman solusi/white-label.astro. Kunci pesan `solutions_white_label_visual_cell2_value` (Nilai Sel Tampilan Putih Label Solusi). untuk detail implementasi dalam Saluran-Saluran, Saluran-Saluran context: Fitur nama saluran rilis Capgo. Halaman/Areas: Halaman pemasaran solusi Capgo. Peran: Label UI singkat atau item navigasi. Dilihat di: halaman solusi/white-label.astro. Kunci pesan `solutions_white_label_visual_cell2_value` (Nilai Sel Tampilan Putih Label Solusi). dan untuk detail implementasi dalam Saluran-Saluran, dan untuk alur produk dalam Beta Testing Solution.