Kanal API-Endpunkt
Eine Einrichtungsanweisung mit den Installationsanweisungen und der vollständigen Markdown-Dokumentation für diesen Plugin kopieren.
Kanäle sind ein zentraler Mechanismus für die Verwaltung von App-Updates in Capgo. In der Selbstverwaltungsmode müssen Sie Kanäleinstiegspunkte implementieren, um Gerätezuweisungen, Kanalabfragen und Kanalverwaltungsbefehle zu verarbeiten.
Kanäle verstehen
Abschnitt mit dem Titel “Kanäle verstehen”Kanäle ermöglichen dir:
- Updateverteilung steuern: Verschiedenen App-Versionen verschiedenen Benutzergruppen zuweisen
- A/B-Test: Neue Funktionen mit bestimmten Benutzersegmenten testen
- Stufenweise Bereitstellung: Updates schrittweise bereitstellen, um Risiken zu minimieren
- Umgebungsseparation: Entwicklung, Staging und Produktionsupdates voneinander trennen
Konfiguration
Abschnitt mit dem Titel “Konfiguration”Konfigurieren Sie die Kanalendpunkt-URL in Ihrem capacitor.config.json:
{ "plugins": { "CapacitorUpdater": { "channelUrl": "https://myserver.com/api/channel_self" } }}Kanaloperationen
Abschnitt mit dem Titel “Kanaloperationen”Das Plugin führt verschiedene Kanaloperationen durch, die Ihr Endpunkt ausführen muss:
1. Liste kompatibler Kanäle (GET-Anfrage)
Abschnitt mit dem Titel “1. Liste kompatibler Kanäle (GET-Anfrage)”Wenn das Plugin listChannels()aufruft,
sendet es eine GET-Anfrage, um alle mit dem Gerät kompatiblen Kanäle abzurufen. Dies gibt Kanäle zurück, die dem Gerätemodus (Entwicklung/Produktion, Emulator/Echtzeitgerät) und der Zugriffsberechtigung (öffentlich oder Selbstzuweisung) entsprechen.
Anfrageformat// 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}Antwortformat
Abschnitt mit dem Titel „Antwortformat“[ { "id": 1, "name": "production", "public": true, "allow_self_set": false }, { "id": 2, "name": "beta", "public": false, "allow_self_set": true }]Kanaltypen verstehen
Abschnitt mit dem Titel „Kanaltypen verstehen“Die Antwort enthält zwei wichtige Flags für jeden Kanal:
-
public: true: Dies ist ein Standardkanal. Geräte können sich nicht selbst auf diesen Kanal zuweisen, indem siesetChannel()anstatt, wenn ein Gerät seine Kanalzuweisung (mitunsetChannel()entfernt), wird es automatisch Updates von diesem öffentlichen Kanal erhalten, wenn es den Bedingungen des Geräts entspricht. -
allow_self_set: true: Dies ist ein selbstzuweisbares Kanal. Geräte können sich explizit dieser Kanal zuweisen, indem siesetChannel(). Dies ist nützlich für Beta-Tests, A/B-Tests oder für die Möglichkeit, Benutzern bestimmte Aktualisierungs-Tracks zur Verfügung zu stellen.
2. Kanal abrufen (PUT-Anfrage)
Abschnitt mit dem Titel „2. Kanal abrufen (PUT-Anfrage)“Wenn der Plugin-Aufruf getChannel()wird, sendet es eine PUT-Anfrage, um die derzeitige Kanalzuweisung des Geräts abzurufen.
Anforderungsformat
Abschnitt mit dem Titel „Anforderungsformat“// 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}Antwortformat
Abschnitt mit dem Titel „Antwortformat“{ "status": "ok", "channel": "production", "allowSet": true, "message": "", "error": ""}3. Kanal festlegen (POST-Anfrage)
Abschnitt mit dem Titel „3. Kanal festlegen (POST-Anfrage)“Wenn der Pluginaufruf erfolgt, setChannel()es sendet eine POST-Anfrage, um das Gerät einem bestimmten Kanal zuzuweisen.
Anforderungsformat
Abschnitt mit dem Titel „Anforderungsformat“// 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}Antwortformat
Abschnitt mit dem Titel „Antwortformat“{ "status": "ok", "message": "Device assigned to channel successfully", "error": ""}Fehlerfälle
Abschnitt mit dem Titel „Fehlerfälle“Wenn ein Gerät versucht, sich einer öffentlichen Kanalgruppe zuzuordnen (einer mit öffentlichem Kanal Ihr Endpunkt sollte einen Fehler zurückgeben: public: trueZur Zwischenablage kopieren
{ "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."}Wenn ein Gerät versucht, sich einer Kanalgruppe zuzuordnen, die Selbstzuweisung nicht zulässt:
{ "status": "error", "error": "channel_self_set_not_allowed", "message": "This channel does not allow devices to self associate"}4. Kanal löschen (DELETE-Anfrage)
Abschnitt mit dem Titel „4. Kanal löschen (DELETE-Anfrage)“Wenn der Pluginaufruf unsetChannel()__CAPGO_KEEP_0__
es sendet eine DELETE-Anfrage, um die Gerätekanalzuweisung zu entfernen.
Anfrageformat// 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}Zur Zwischenablage kopieren
ImplementierungsbeispielAbschnitt mit dem Titel „Implementierungsbeispiel“
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" }}Kanal-Konfiguration
Abschnitt „Kanal-Konfiguration“Ihr Kanal-System sollte diese Konfigurationsoptionen unterstützen:
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}Geräte-Filter-Logik
Abschnitt „Geräte-Filter-Logik“Wenn Sie kompatible Kanäle (GET-Anfrage) auflisten, sollten Sie die Kanäle basierend auf diesen Bedingungen filtern:
- Plattform-Überprüfung: Der Kanal muss die Plattform des Geräts (
ios,android, oderelectron) - Geräte-Typ-Überprüfung:
- Wenn
is_emulator=true: Kanal muss habenallow_emulator=true - Wenn
is_emulator=false: Kanal muss habenallow_device=true
- Wenn
- Build-Typ-Überprüfung:
- Wenn
is_prod=true: Kanal muss habenallow_prod=true - Wenn
is_prod=false: Kanal muss habenallow_dev=true
- Wenn
- Sichtbarkeitsprüfung: Der Kanal muss entweder
public=trueODERallow_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 })}Beispieldatenbank-Struktur
Abschnitt mit dem Titel „Beispieldatenbank-Struktur“Sie müssen die Kanalkonfigurationen und die Gerätezuweisungen speichern: __CAPGO_KEEP_0__
-- 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));Fehlerbehandlung
Abschnitt mit dem Titel „Fehlerbehandlung“Gemeinsame Fehlerzenarien handhaben: __CAPGO_KEEP_0__
// 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"}Gute Praxis
Abschnitt mit dem Titel „Gute Praxis“- SicherheitAlle Kanalzuweisungen gegen Ihre Geschäftsregeln validieren
- Protokollierung: Alle Kanaloperationen protokollieren, um Audit- und Debug-Zwecke zu ermöglichen
- Leistung: Kanalkonfigurationen im Cache speichern, um Datenbankanfragen zu reduzieren
- Validierung: Die Authentizität von device_id und app_id überprüfen
- Rate Limiting: Rate Limiting implementieren, um Missbrauch zu verhindern
Integration mit Updates
Abschnitt mit dem Titel “Integration mit Updates”Kanalzuweisungen arbeiten zusammen mit Ihrem Update API-Endpunkt. Wenn ein Gerät eine Aktualisierung anfordert, überprüfen Sie seine Kanalzuweisung, um zu bestimmen, welche Version bereitgestellt werden soll:
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 }}Dies erstellt ein vollständiges selbstgeführtes Kanalmanagement-System, das Ihnen die volle Kontrolle über die Verteilung von Updates an Ihre Benutzer gibt.