채널 API 엔드포인트

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

채널 이해

채널을 사용하면 다음을 수행할 수 있습니다:

업데이트 배포 제어: 다른 사용자 그룹에 다른 앱 버전 할당
A/B 테스팅: 특정 사용자 세그먼트로 새로운 기능 테스트
단계적 출시: 위험을 최소화하기 위해 점진적으로 업데이트 배포
환경 분리: 개발, 스테이징 및 프로덕션 업데이트 분리

구성

capacitor.config.json에서 채널 엔드포인트 URL을 구성하세요:

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

채널 작업

플러그인은 엔드포인트가 처리해야 하는 다양한 채널 작업을 수행합니다:

1. 채널 가져오기 (GET 요청)

플러그인이 getChannel()을 호출하면 장치의 현재 채널 할당을 검색하기 위해 GET 요청을 보냅니다.

요청 형식

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

// Query parameters or body:
interface GetChannelRequest {
  device_id: string
  app_id: string
  platform: "ios" | "android"
  plugin_version: string
  version_build: string
  version_code: string
  version_name: string
}

응답 형식

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

2. 채널 설정 (POST 요청)

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

요청 형식

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

응답 형식

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

3. 채널 해제 (DELETE 요청)

플러그인이 unsetChannel()을 호출하면 장치의 채널 할당을 제거하기 위해 DELETE 요청을 보냅니다.

요청 형식

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

구현 예제

다음은 채널 엔드포인트를 구현하는 JavaScript 예제입니다:

interface ChannelRequest {
  device_id: string
  app_id: string
  channel?: string
  platform: "ios" | "android"
  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"
    }
  }

  // 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
  android: boolean

  // Device restrictions
  allowDeviceSelfSet: boolean  // Allow setChannel() calls
  allowEmulator: boolean
  allowDev: boolean           // Allow development builds

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

  // Assignment
  isDefault: boolean          // Default channel for new devices
}

데이터베이스 스키마 예제

채널 구성 및 장치 할당을 저장해야 합니다:

-- Channels table
CREATE TABLE channels (
  id SERIAL PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  app_id VARCHAR(255) NOT NULL,
  ios BOOLEAN DEFAULT true,
  android BOOLEAN DEFAULT true,
  allow_device_self_set BOOLEAN DEFAULT false,
  allow_emulator BOOLEAN DEFAULT true,
  allow_dev BOOLEAN DEFAULT true,
  disable_auto_update VARCHAR(50) DEFAULT 'none',
  disable_auto_update_under_native BOOLEAN DEFAULT false,
  is_default 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"
}

모범 사례

보안: 비즈니스 규칙에 대해 모든 채널 할당 유효성 검사
로깅: 감사 및 디버깅을 위해 모든 채널 작업 로그
성능: 데이터베이스 쿼리를 줄이기 위해 채널 구성 캐시
유효성 검사: device_id 및 app_id 진위 확인
속도 제한: 남용을 방지하기 위한 속도 제한 구현

업데이트와의 통합

채널 할당은 업데이트 API 엔드포인트와 함께 작동합니다. 장치가 업데이트를 요청할 때 채널 할당을 확인하여 제공할 버전을 결정하세요:

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

이렇게 하면 사용자에게 업데이트가 배포되는 방식을 완전히 제어할 수 있는 완전한 자체 호스팅 채널 관리 시스템이 생성됩니다.