채널 API 엔드포인트

Capgo에서 앱 업데이트를 관리하는 핵심 메커니즘인 채널에 대한 이해가 필요합니다. 자체 호스팅 모드에서, 디바이스 할당, 채널 쿼리 및 채널 관리 작업을 처리하기 위해 채널 엔드포인트를 implement해야합니다.

채널 이해

채널을 사용하면:

• 업데이트 배포를 제어할 수 있습니다.: 사용자 그룹에 다른 앱 버전을 assign할 수 있습니다.
• AB 테스트: 새로운 기능을 특정 사용자 세그먼트와 함께 테스트할 수 있습니다.
• 스테이지드 롤아웃: 업데이트를 최소한의 위험으로 배포하기 위해 점진적으로 배포합니다
• 환경 분리: 개발, 스테이징, 및 프로덕션 업데이트를 분리합니다

설정

설정 섹션에서 채널 엔드포인트 URL을 구성합니다 capacitor.config.json:

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

채널 운영

플러그인은 엔드포인트가 처리해야 하는 채널 연산이 다르기 때문에 수행하는 다양한 채널 연산을 수행합니다:

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: 이 채널은 기본 채널입니다.. 기기들은 이 채널에 자동 ASSIGN 할 수 없습니다. setChannel(). 대신에, 기기는 채널 ASSIGN 을 제거하는 경우 ( unsetChannel()) 이 채널의 PUBLIC UPDATE를 받게 됩니다. 이 채널은 기기의 조건과 일치할 경우.

• allow_self_set: true: 이 채널은 자체 ASSIGN 가능 채널입니다.. 기기들은 이 채널에 직접 ASSIGN 할 수 있습니다. setChannel(). 이 채널은 베타 테스트, A/B 테스트, 또는 사용자가 특정 업데이트 트랙에 가입할 수 있도록 허용하는 데 유용합니다.

주의

채널은 기본적으로 public 또는 allow_self_set그러나 일반적으로 둘 다 아니다. 공개 채널은 기본 대체로, 자체 할당 채널은 명시적 동의가 필요합니다.

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 요청)

플러그인이 호출할 때 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: true오류를 반환해야 합니다.

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

장치가 자체 할당을 허용하지 않는 채널에 할당하려고 할 때:

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

4. 채널 해제 (DELETE 요청)

플러그인이 unsetChannel()를 호출하면

장치의 채널 할당을 삭제하기 위해 DELETE 요청을 보냅니다.

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

자바스크립트로 채널 엔드포인트를 구현하는 방법에 대한 예시입니다.

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
}

장치 필터링 로직

Compatible 채널 목록을 표시할 때 (GET 요청), 다음 조건에 따라 채널을 필터링해야 합니다:

1. 플랫폼 확인: 장치의 플랫폼을 허용하는 채널이 있어야 합니다 (ios, android, 또는 electron)
2. 장치 유형 확인:
   • 만약 is_emulator=true: 채널이 allow_emulator=true
   • 만약 is_emulator=false: 채널이 allow_device=true
3. 빌드 유형 확인:
   • 만약 is_prod=true: 채널이 allow_prod=true
   • 만약 is_prod=false: 채널은 allow_dev=true
4. 가시성 확인: 채널은 public=true 또는 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
  })
}

데이터베이스 스키마 예시

채널 설정 및 장치 할당을 저장해야 합니다:

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

오류 처리

오류 처리 시나리오를 처리하는 방법:

// 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. 보안컨텍스트: Enterprise 제품/가격 페이지. 역할: UI 레이블. 표시되는 곳: enterprise.astro 페이지. 메시지 키 `enterprise_hero_security_label` (Enterprise Hero Security Label).
2. : 모든 채널 assignments를 사업 규칙과 일치시킵니다.로그
3. : 모든 채널 연산을 감사 및 디버깅을 위해 로깅합니다.성능
4. 컨텍스트: 홈페이지 문제/해결 섹션. 역할: 섹션 또는 페이지 제목. 표시되는 곳: page premium-support.astro. 메시지 키 `ps_help_performance_title` (Ps Help Performance Title).: 채널 구성이 캐시되도록 하여 데이터베이스 쿼리를 줄입니다. (Database Query Reduction).
5. 제한 속도 제어: 사용자 남용 방지를 위해 제한 속도 제어를 구현하세요

업데이트 통합

채널 assignments은 사용자와 함께 작동하여 업데이트 API 엔드포인트. 장치가 업데이트를 요청할 때, 채널 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 엔드포인트에서 계속하세요

만약 사용자 API 채널 API 엔드포인트 채널 라우팅과 스테이지드 롤아웃을 계획하고 연결하려면 capgo/capacitor-업데이터를 사용하여 capgo/capacitor-업데이터를 사용하여 __CAPGO_KEEP_0__ context Capgo 릴리스 채널 기능 이름. 페이지/영역: Capgo 솔루션 마케팅 페이지. 역할: 짧은 UI 레이블 또는 네비게이션 아이템. 본문 키 `solutions_white_label_visual_cell2_value` (솔루션 화이트 레이블 시각 셀2 값). __CAPGO_KEEP_0__ context Capgo 릴리스 채널 기능 이름. 페이지/영역: Capgo 솔루션 마케팅 페이지. 역할: 짧은 UI 레이블 또는 네비게이션 아이템. 본문 키 `solutions_white_label_visual_cell2_value` (솔루션 화이트 레이블 시각 셀2 값). __CAPGO_KEEP_0__ context