Kanal API-Endpunkt
Kopieren Sie einen Einrichtungsprompt mit den Installationsanweisungen und der vollständigen Markdown-Guideline für diesen Plugin.
Kanäle sind ein zentraler Mechanismus für die Verwaltung von App-Updates in Capgo. Bei selbstgefertigten Modus müssen Sie Kanalendpunkte implementieren, um Gerätezuweisungen, Kanalabfragen und Kanalverwaltungsbefehle zu bearbeiten.
Kanäle verstehen
Abschnitt mit dem Titel “Kanäle verstehen”Kanäle ermöglichen Ihnen:
- Update-Verteilung steuern: Verschiedene App-Versionen verschiedenen Benutzergruppen zuweisen
- A/B-Testen: Neue Funktionen mit bestimmten Benutzersegmenten testen
- Phasenweise Bereitstellung: Graduell Updates bereitstellen, um das Risiko zu minimieren
- Umgebungstrennung: Trenne Entwicklungs-, Staging- und Produktionsupdates
Konfiguration
Abschnitt mit dem Titel „Konfiguration“Konfigurieren Sie die Kanal-Endpunkt-URL in Ihrem capacitor.config.json:
{ "plugins": { "CapacitorUpdater": { "channelUrl": "https://myserver.com/api/channel_self" } }}Kanal-Operationen
Abschnitt mit dem Titel „Kanal-Operationen“Das Plugin führt verschiedene Kanal-Operationen durch, die Ihr Endpunkt ausführen muss:
1. Liste kompatible Kanäle (GET-Anfrage)
Abschnitt mit dem Titel “1. Liste kompatibler Kanäle (GET-Anfrage)”Wenn der Pluginaufruf listChannels(), sendet es eine GET-Anfrage, um alle Kanäle abzurufen, die mit dem Gerät kompatibel sind. Dies gibt Kanäle zurück, die dem Geräteumfeld entsprechen (dev/prod, Emulator/Realgerät) und entweder öffentlich zugänglich oder selbst zugewiesen sind.
Anfrageformat
Abschnitt mit dem Titel “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 }]Verständnis von Kanaltypen
Abschnitt mit dem Titel “Verständnis von Kanaltypen”Die Antwort enthält zwei wichtige Flags für jeden Kanal:
-
public: true: Dies ist ein __CAPGO_KEEP_0__. Geräte können sich nicht selbst auf dieses Channel zuweisen.setChannel(). Stattdessen wird ein Gerät, wenn es seine Channel-Zuweisung (mitunsetChannel()) entfernt, automatisch Updates von diesem öffentlichen Channel erhalten, wenn es den Bedingungen des Geräts entspricht. -
allow_self_set: true: Dies ist ein __CAPGO_KEEP_0__. Geräte können sich explizit auf dieses Channel zuweisen.setChannel(). 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(), sendet es eine PUT-Anfrage, um die derzeitige Kanalzuweisung des Geräts abzurufen.
Anfrageformat
Abschnitt mit dem Titel „Anfrageformat“// 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 setzen (POST-Anfrage)
Abschnitt mit dem Titel „3. Kanal setzen (POST-Anfrage)“Wenn der Pluginaufruf setChannel(), sendet es eine POST-Anfrage, um das Gerät einer bestimmten Kanal zuzuweisen.
Anfrageformat
Abschnitt mit dem Titel „Anfrageformat“// 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 zuzuweisen (einer mit __CAPGO_KEEP_0__), sollte Ihr Endpunkt einen Fehler zurückgeben: Zum Clipboard kopieren Wenn ein Gerät versucht, sich einer Kanalgruppe zuzuweisen, die Selbstzuweisung nicht zulässt: public: trueZum Clipboard 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."}Abschnitt mit dem Titel „4. Kanal deaktivieren (DELETE-Anfrage)“
{ "status": "error", "error": "channel_self_set_not_allowed", "message": "This channel does not allow devices to self associate"}Anforderungsformat
targetLanguageprotectedTokens unsetChannel()texts
Request Format
Abschnitt mit dem Titel „Anforderungsformat“// 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}Implementierungsbeispiel
Abschnitt mit dem Titel „Implementierungsbeispiel“Hier ist ein JavaScript-Beispiel, wie Sie den Kanalendpunkt implementieren können:
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 mit dem Titel „Kanal-Konfiguration“Ihre Kanal-Systeme sollten 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-Filterlogik
Abschnitt mit dem Titel „Geräte-Filterlogik“Wenn Sie kompatible Kanäle auflisten (GET-Anfrage), sollten Sie die Kanäle auf Grundlage dieser 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: Der Kanal muss habenallow_emulator=true - Wenn
is_emulator=false: Der Kanal muss habenallow_device=true
- Wenn
- Build-Typ-Überprüfung:
- Wenn
is_prod=true: Der Kanal muss habenallow_prod=true - Wenn
is_prod=false: Der 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 })}Beispiel für die Datenbank-Schema
Abschnitt mit dem Titel „Beispiel für die Datenbank-Schema“Sie müssen die Kanal-Konfigurationen und die Gerätezuweisungen speichern:
-- 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“Häufige Fehlerfälle behandeln:
// 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"}Best Practices
Abschnitt mit dem Titel „Best Practices“- Sicherheit: Überprüfe alle Kanalzuweisungen gegen deine Geschäftsregeln
- Protokollierung: Protokolliere alle Kanaloperationen für die Rechnungslegung und Fehlerbehebung
- Leistung: Cachiere Kanalkonfigurationen, um Datenbankabfragen zu reduzieren
- Validierung: Überprüfe die Authentizität von device_id und app_id
- Rate Limiting: Implement rate limiting, um Missbrauch zu verhindern
Integration mit Updates
Abschnitt mit dem Titel “Integration mit Updates”Kanalzuweisungen arbeiten zusammen mit Ihrem Update API-EndpunktWenn ein Gerät einen Update 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.