내용으로 건너뛰기
Capgo - Capacitor 앱의 라이브 업데이트 Capgo

API 채널 엔드포인트

GitHub

Channels are a core mechanism for managing app updates in Capgo. In self-hosted mode, you need to implement channel endpoints to handle device assignments, channel queries, and channel management operations.

채널은 __CAPGO_KEEP_0__에서 앱 업데이트를 관리하는 핵심 메커니즘입니다. 자체 호스팅 모드에서, 채널 엔드포인트를 구현하여 장치 할당, 채널 쿼리 및 채널 관리 작업을 처리해야 합니다.

채널 이해

채널 이해

  • 채널을 사용하면:업데이트 배포를 제어할 수 있습니다.
  • A/B 테스트A/B 테스트
  • : 특정 사용자 세그먼트와 함께 새로운 기능을 테스트할 수 있습니다.스테이지드 롤아웃
  • 환경 분리: 개발, 스테이징, 및 프로덕션 업데이트 분리

설정

설정 섹션

설정에서 채널 엔드포인트 URL을 구성하십시오 capacitor.config.json:

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

채널 관리

채널 관리 섹션

플러그인은 채널을 처리하기 위해 엔드포인트가 필요로 하는 다양한 채널 관리를 수행합니다:

1. 호환 가능한 채널 목록 조회 (GET 요청)

1. 호환 가능한 채널 목록 조회 (GET 요청) 섹션

플러그인이 호출할 때 listChannels()장치가 호환되는 모든 채널을 검색하기 위해 GET 요청을 전송합니다. 이 요청은 장치의 환경 (개발/운영, 시뮬레이터/실제 장치)과 공개 접근 또는 자체 할당을 허용하는 채널을 반환합니다.

요청 형식

요청 형식
// 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
}

응답 형식

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

채널 유형 이해

채널 유형 이해

응답에는 각 채널에 대한 두 가지 중요한 플래그가 포함됩니다:

  • public: true기본 채널 기본 채널장치들은 자동으로 할당되지 않습니다. setChannel()대신, 장치가 채널 할당을 제거( )하는 경우, 이 공용 채널이 장치의 조건과 일치하는 경우 자동으로 업데이트를 받습니다. unsetChannel(): 이 채널은

  • allow_self_set: true: 자체 호스팅 업데이트 플러그인 이 채널은 베타 테스트, A/B 테스트 또는 사용자가 특정 업데이트 트랙에 가입할 수 있도록 허용하는 데 유용합니다.주의 setChannel()채널은

2. 채널 가져오기 (PUT 요청)

2. 채널 가져오기 (PUT 요청)

플러그인이 호출할 때 getChannel()이때 플러그인은 기기의 현재 채널 할당 정보를 가져오기 위해 PUT 요청을 보냅니다.

요청 형식

요청 형식
// 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
}

응답 형식

응답 형식
{
  "status": "ok",
  "channel": "production",
  "allowSet": true,
  "message": "",
  "error": ""
}

3. 채널 설정 (POST 요청)

3. 채널 설정 (POST 요청)

플러그인이 호출할 때 setChannel()그것은 특정 채널에 장치를 할당하기 위해 POST 요청을 보냅니다.

요청 형식

요청 형식 섹션
// 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
}

응답 형식

응답 형식 섹션
{
  "status": "ok",
  "message": "Device assigned to channel successfully",
  "error": ""
}

오류 사례

오류 사례 섹션

장치가 공공 채널에 할당하려고 할 때 장치가 공공 채널에 할당하려고 할 때 ( public: trueone with

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

your endpoint should return an error:

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

Copy to clipboard

4. 채널 해제 (DELETE 요청)

4. Channel 해제 (DELETE Request) unsetChannel()Section titled “4. Channel 해제 (DELETE Request)”

When the plugin calls

, it sends a DELETE request to remove the device’s channel assignment.
// 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
}

Implementation Example

Implementation Example

JavaScript에서 채널 엔드포인트를 구현하는 예제입니다.

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

채널 설정

채널 설정

채널 시스템은 다음 설정 옵션을 지원해야 합니다.

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
}

장치 필터링 논리

장치 필터링 논리

호환 가능한 채널 목록을 가져올 때 (GET 요청), 다음 조건에 따라 채널을 필터링해야 합니다.

  1. 플랫폼 확인채널은 장치의 플랫폼을 허용해야 합니다.ios, android, or electron)
  2. 장치 유형 확인:
    • If is_emulator=true: 채널은 반드시 있어야 합니다. allow_emulator=true
    • If is_emulator=false: 채널은 반드시 있어야 합니다. allow_device=true
  3. 업데이터 타입 확인:
    • If is_prod=true: 채널은 반드시 있어야 합니다. allow_prod=true
    • If is_prod=false: 채널은 반드시 있어야 합니다. allow_dev=true
  4. __CAPGO_KEEP_0____CAPGO_KEEP_1__ public=true OR 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
  })
}

__CAPGO_KEEP_3__

__CAPGO_KEEP_4__

__CAPGO_KEEP_5__

-- 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)
);

__CAPGO_KEEP_6__

__CAPGO_KEEP_7__

__CAPGO_KEEP_8__

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

최선의 방법

‘최선의 방법’ 섹션
  1. 보안context
  2. Logging채널 assignments
  3. 로그: 모든 채널 연산을 감사 및 디버깅을 위해 로그합니다
  4. 성능context
  5. Page/area: Homepage problem/solution section. Role: Section or page heading. Seen in: page premium-support.astro. Message key `ps_help_performance_title` (Ps Help Performance Title).: 채널 구성이 데이터베이스 쿼리를 줄이기 위해 캐시합니다.

업데이트 통합

Integration with Updates

채널 assignments은 당신의 업데이트 API 엔드포인트__CAPGO_KEEP_0__의 버전을 결정하기 위해, 장치가 업데이트를 요청할 때 채널 assignments를 확인하세요.

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

이것은 완전한 자체 호스팅 채널 관리 시스템을 만듭니다. 사용자에게 업데이트가 어떻게 분배되는지에 대한 완전한 제어권을 제공합니다.

채널 API 엔드포인트에서 계속 진행

Keep going from Channel API Endpoint

만약 __CAPGO_KEEP_0__를 사용 중이라면 채널 API 엔드포인트 Channel __CAPGO_KEEP_0__ Endpoint capgo-capacitor 업데이터를 사용하여 capgo-capacitor 업데이터를 사용하여 채널 __CAPGO_KEEP_0__-__CAPGO_KEEP_1__ 업데이터 채널 __CAPGO_KEEP_0__-__CAPGO_KEEP_1__ 업데이터 채널 __CAPGO_KEEP_0__-__CAPGO_KEEP_1__ 업데이터 __CAPGO_KEEP_0__-__CAPGO_KEEP_1__ 업데이터 __CAPGO_KEEP_0__