Zum Inhalt springen
Capgo - Capacitor-Apps bauen, ausliefern und updaten Capgo

API Channel-Endpoint

GitHub

Channels sind ein zentraler Mechanismus für die Verwaltung von App-Updates in Capgo. Im Self-hosted-Modus müssen Sie Channel-Endpoints implementieren, um Gerätezuweisungen, Channel-Abfragen und Channel-Management-Operationen zu bearbeiten.

Channels verstehen

Abschnitt: „Channels verstehen“

Channels ermöglichen es dir:

  • Die Update-Verteilung zu steuern: Verschiedene App-Versionen verschiedenen Nutzergruppen zuzuweisen
  • A/B-Testing: Neue Features mit spezifischen Nutzersegmenten zu testen
  • Staged Rollouts: Updates schrittweise zu deployen, um Risiken zu minimieren
  • Trennung der Umgebungen: Development-, Staging- und Production-Updates zu trennen

Konfiguration

Abschnitt „Konfiguration“

Konfiguriere die Channel-Endpoint-URL in deiner capacitor.config.json:

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

Channel-Operationen

Abschnitt „Channel-Operationen“

Das Plugin führt verschiedene Channel-Operationen aus, die dein Endpoint verarbeiten muss:

1. Kompatible Channels auflisten (GET-Request)

Abschnitt „1. Kompatible Channels auflisten (GET-Request)“

Wenn das Plugin listChannels() aufruft, sendet es einen GET-Request, um alle Channels abzurufen, die mit dem Gerät kompatibel sind. Dies liefert Channels zurück, die zur Umgebung des Geräts passen (dev/prod, Emulator/Echtgerät) und entweder öffentlichen Zugriff oder Self-Assignment erlauben.

Request-Format

Abschnitt „Request-Format“
// 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
}

Response-Format

Abschnitt mit dem Titel „Response-Format“
[
  {
    "id": 1,
    "name": "production",
    "public": true,
    "allow_self_set": false
  },
  {
    "id": 2,
    "name": "beta",
    "public": false,
    "allow_self_set": true
  }
]

Channel-Typen verstehen

Abschnitt mit dem Titel „Channel-Typen verstehen“

Die Response enthält für jeden Channel zwei wichtige Flags:

  • public: true: Dies ist ein Default-Channel. Devices cannot self-assign to it using setChannel(). Wenn ein Gerät stattdessen seine Channel-Zuweisung entfernt (mit unsetChannel()), erhält es automatisch Updates von diesem öffentlichen Channel, sofern es den Bedingungen des Geräts entspricht.

  • allow_self_set: true: Dies ist ein selbstzuweisbarer Channel. Geräte können sich über folgenden Befehl explizit diesem Channel zuweisen: setChannel(). Das ist ideal für Beta-Tests, A/B-Tests oder wenn User gezielt bestimmte Update-Tracks wählen sollen.

2. Channel abrufen (PUT-Request)

Abschnitt mit dem Titel „2. Channel abrufen (PUT-Request)“

Wenn das Plugin getChannel(), es sendet einen PUT-Request, um die aktuelle Channel-Zuweisung des Geräts abzurufen.

Request-Format

Abschnitt „Request-Format“
// 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
}

Response-Format

Abschnitt mit dem Titel „Response-Format“
{
  "status": "ok",
  "channel": "production",
  "allowSet": true,
  "message": "",
  "error": ""
}

3. Channel setzen (POST-Request)

Abschnitt mit dem Titel „3. Channel festlegen (POST-Request)“

Wenn das Plugin setChannel(), es sendet einen POST-Request, um das Gerät einem bestimmten Channel zuzuweisen.

Request-Format

Abschnitt „Request-Format“
// 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
}

Response-Format

Abschnitt mit dem Titel „Response-Format“
{
  "status": "ok",
  "message": "Device assigned to channel successfully",
  "error": ""
}

Fehlerfälle

Abschnitt „Error Cases“

Wenn ein Gerät versucht, sich einem öffentlichen Channel (einen mit public: true) zuzuweisen, sollte dein Endpoint einen Fehler zurückgeben:

{
  "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 selbst einem Kanal zuzuweisen, der keine Selbstzuweisung erlaubt:

{
  "status": "error",
  "error": "channel_self_set_not_allowed",
  "message": "This channel does not allow devices to self associate"
}

4. Channel entfernen (DELETE-Request)

Abschnitt mit dem Titel „4. Unset Channel (DELETE Request)“

Wenn das Plugin unsetChannel(), sendet es einen DELETE-Request, um die Kanalzuweisung des Geräts zu entfernen.

Request-Format

Abschnitt „Request-Format“
// 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
}

Implementierungsbeispiel

Abschnitt mit dem Titel „Implementierungsbeispiel“

Hier ist ein JavaScript-Beispiel für die Implementierung des Channel-Endpoints:

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

Abschnitt „Channel-Konfiguration“

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

Logik zur Gerätefilterung

Abschnitt „Logik zur Gerätefilterung“

Beim Auflisten kompatibler Channels (GET-Request) solltest du die Channels nach diesen Bedingungen filtern:

  1. Plattform-Check: Der Channel muss die Plattform des Geräts erlauben (ios, android, oder electron)
  2. Gerätetyp-Check:
    • Wenn is_emulator=true: Channel muss haben allow_emulator=true
    • Wenn is_emulator=false: Channel muss haben allow_device=true
  3. Build-Typ-Check:
    • Wenn is_prod=true: Channel muss haben allow_prod=true
    • Wenn is_prod=false: Channel muss haben allow_dev=true
  4. Sichtbarkeits-Check: Channel muss entweder public=true ODER 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
  })
}

Beispiel für das Datenbankschema

Abschnitt mit dem Titel „Beispiel für das Datenbankschema“

Du musst Channel-Konfigurationen und Device-Zuweisungen speichern:

-- 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)
);

Fehlerbehandlung

Abschnitt mit dem Titel „Fehlerbehandlung“

Häufige Fehlerszenarien 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“
  1. Sicherheit: Alle Channel-Zuweisungen gegen deine Business-Rules validieren
  2. Logging: Alle Channel-Operationen für Audits und Debugging loggen
  3. Performance: Channel-Konfigurationen cachen, um Datenbankabfragen zu reduzieren
  4. Validierung: Authentizität von device_id und app_id prüfen
  5. Rate Limiting: Rate Limiting implementieren, um Missbrauch zu verhindern

Integration mit Updates

Abschnitt mit dem Titel „Integration mit Updates“

Channel-Zuweisungen arbeiten zusammen mit deinem API Update-EndpointWenn ein Gerät ein Update anfordert, prüfe die Channel-Zuweisung, um zu entscheiden, welche Version ausgeliefert 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
  }
}

So erhältst du ein vollständiges, selbst gehostetes Channel-Management-System, mit dem du die volle Kontrolle über die Update-Verteilung an deine Nutzer hast.

Weiter mit dem Channel API Endpoint

Abschnitt mit dem Titel „Weiter mit dem Channel API Endpoint“

Wenn du es nutzt API Channel-Endpoint um Channel-Routing und Staged Rollout zu planen, verbinde es mit Verwendung von @capgo/capacitor-updater für die native Funktion in der Verwendung von @capgo/capacitor-updater, Kanäle für die Implementierungsdetails in Channels, Kanäle für die Implementierungsdetails in Channels, Kanäle für die Implementierungsdetails in Channels, und Beta-Testing-Lösung für den Produkt-Workflow in der Beta Testing Solution.