チャネル API エンドポイント

チャネルは、Capgo でアプリの更新を管理するための中心的なメカニズムです。セルフホストモードでは、デバイスの割り当て、チャネルクエリ、およびチャネル管理操作を処理するためにチャネルエンドポイントを実装する必要があります。

チャネルを理解する

チャネルを使用すると、次のことが可能になります。

アップデートの配布を制御: 異なるアプリのバージョンを異なるユーザーグループに割り当てます
A/B テスト: 特定のユーザーセグメントを対象に新機能をテストします
段階的ロールアウト: リスクを最小限に抑えるためにアップデートを段階的に展開します。
環境の分離: 開発、ステージング、実稼働の更新を分離します。

構成

capacitor.config.json でチャネルエンドポイント URL を構成します。

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

チャネルの種類を理解する

応答には、チャネルごとに 2 つの重要なフラグが含まれています。

public: true: これは デフォルトチャンネルです。 setChannel() を使用してデバイスを自己割り当てすることはできません。代わりに、デバイスが (unsetChannel() を使用して) チャネル割り当てを削除すると、デバイスの条件に一致する場合は、このパブリックチャネルから更新を自動的に受信します。
allow_self_set: true: これは自己割り当て可能なチャンネルです。デバイスは、setChannel() を使用して、デバイス自体をこのチャネルに明示的に割り当てることができます。これは、ベータテスト、A/B テスト、またはユーザーが特定の更新トラックにオプトインできるようにする場合に役立ちます。

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
}

実装例

チャネルエンドポイントを実装する方法の 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 リクエスト) をリストする場合は、次の条件に基づいてチャネルをフィルタリングする必要があります。

プラットフォームチェック: チャネルはデバイスのプラットフォーム (ios、android、または electron) を許可する必要があります。
デバイスタイプのチェック:
- is_emulator=true の場合: チャネルには allow_emulator=true が必要です
- is_emulator=false の場合: チャネルには allow_device=true が必要です
ビルドタイプのチェック:
- is_prod=true の場合: チャネルには allow_prod=true が必要です
- is_prod=false の場合: チャンネルには allow_dev=true が必要です
可視性チェック: チャネルは 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"
}

ベストプラクティス

セキュリティ: ビジネスルールに照らしてすべてのチャネル割り当てを検証します。
ログ: 監査とデバッグのためにすべてのチャネル操作をログに記録します。
パフォーマンス: キャッシュチャネル構成によりデータベースクエリを削減します。
検証: 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
  }
}

これにより、更新をユーザーに配布する方法を完全に制御できる完全な自己ホスト型チャネル管理システムが作成されます。

チャネル API エンドポイント

チャネルを理解する

構成

チャネル操作

1. 互換性のあるチャネルのリスト (GET リクエスト)

リクエストのフォーマット

応答形式

チャネルの種類を理解する

2. チャネルの取得 (PUT リクエスト)

リクエストのフォーマット

応答形式

3. チャネルの設定 (POST リクエスト)

リクエストのフォーマット

応答形式

エラーのケース

4. チャネルの設定解除 (DELETE リクエスト)

リクエストのフォーマット

実装例

チャネル構成

デバイスフィルタリングロジック互換性のあるチャネル (GET リクエスト) をリストする場合は、次の条件に基づいてチャネルをフィルタリングする必要があります。

データベース スキーマの例

エラー処理

ベストプラクティス

アップデートとの統合

データベーススキーマの例