チャネル API エンドポイント
インストール手順と、このプラグインの完全なMarkdownガイドを含むセットアッププロンプトをコピーします。
チャンネルは、Capgo におけるアプリ更新の管理における中核的な仕組みです。セルフホストモードでは、デバイスの割り当て、チャンネルのクエリ、およびチャンネル管理操作を処理するために、チャンネルエンドポイントを実装する必要があります。
チャンネルの仕組み
「チャンネルの理解」セクションチャンネルを使用すると、以下を行うことができます:
- 更新の配布を制御する:異なるユーザーグループに異なるアプリバージョンを割り当てる
- A/Bテスト:特定のユーザーセグメントで新しい機能をテストする
- 段階的ロールアウト:リスクを最小限に抑えるために、段階的に更新をデプロイする
- 環境の分離:開発、ステージング、本番環境の更新を分離
のチャンネルエンドポイントURLを設定します capacitor.config.json:
{ "plugins": { "CapacitorUpdater": { "channelUrl": "https://myserver.com/api/channel_self" } }}Channel の操作
セクション「チャンネル操作」プラグインは、エンドポイントで処理する必要があるさまざまなチャンネル操作を実行します:
1. 互換性のある Channel の一覧取得 (GET リクエスト)
セクション「1. 互換性のあるチャンネル一覧(GETリクエスト)」プラグインが呼び出すと、 listChannels()、デバイスと互換性のあるすべてのチャンネルを取得するためにGETリクエストを送信します。これにより、デバイスの環境(dev/prod、エミュレーター/実機)に一致し、パブリックアクセスまたはセルフアサインメントのいずれかを許可するチャンネルが返されます。
リクエスト形式
「リクエスト形式」セクション// 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. Channel の取得 (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. Channel の設定 (POST リクエスト)
「3. チャンネルの設定(POSTリクエスト)」という見出しのセクションプラグインが呼び出すと、 setChannel()、デバイスを特定のチャンネルに割り当てるためにPOSTリクエストを送信します。
リクエスト形式
「リクエスト形式」セクション// POST /api/channel_selfinterface 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. Channel の解除 (DELETE リクエスト)
セクション「4. チャンネルの設定解除 (DELETE リクエスト)」プラグインが呼び出すと、 unsetChannel()、デバイスのチャンネル割り当てを解除するために DELETE リクエストを送信します。
リクエスト形式
「リクエスト形式」セクション// DELETE /api/channel_selfinterface 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" }}Channel の設定
セクション「Channel Configuration」チャネルシステムでは、これらの設定オプションをサポートする必要があります。
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}デバイスのフィルタリングロジック
セクション「Device Filtering Logic」互換性のあるチャネルをリストアップする際(GET リクエスト)、これらの条件に基づいてチャネルをフィルタリングする必要があります。
- プラットフォームチェック:チャネルは、デバイスのプラットフォーム(
ios,android、またはelectron) - デバイス種別の確認:
- もし
is_emulator=true:Channelに必須ですallow_emulator=true - もし
is_emulator=false:Channelに必須ですallow_device=true
- もし
- Buildタイプのチェック:
- もし
is_prod=true:Channelに必須ですallow_prod=true - もし
is_prod=false:Channelに必須ですallow_dev=true
- もし
- Visibilityのチェック:Channelはいずれかである必要があります
public=trueまたはallow_device_self_set=true
// Example filtering logicfunction 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 tableCREATE 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 tableCREATE 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 の正当性を検証する
- レート制限: 不正利用を防ぐため、レート制限を実装する
Updates との連携
「Updates との連携」セクションチャンネル割り当ては、以下と連携して動作します: アップデート 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 エンドポイントの続きへ
「チャンネル API エンドポイントの続きへ」というタイトルのセクション使用している場合 チャネル API エンドポイント チャンネルルーティングと段階的ロールアウトを計画するには、次と組み合わせてください: @capgo/capacitor-updater を使用する 「@capgo/capacitor-updater を使用する」のネイティブ機能については、 チャンネル Channelsの実装の詳細については、 チャンネル Channelsの実装の詳細については、 チャンネル Channels の実装詳細については、 ベータテストソリューション Beta Testing Solution のプロダクトワークフローについては。