Zum Inhalt springen
Capgo - Live-Updates für Capacitor-Apps Capgo

Channel API-Punkt

GitHub

Kanäle sind ein zentraler Mechanismus für die Verwaltung von App-Updates in Capgo. In der Selbstverwaltungsmode müssen Sie Kanäle implementieren, um Gerätezuweisungen, Kanalabfragen und Kanalverwaltungsbefehle zu handhaben.

Kanäle verstehen

Abschnitt mit dem Titel “Kanäle verstehen”

Kanäle ermöglichen Ihnen:

  • Die Verteilung von Updates steuern: Verschiedene App-Versionen verschiedenen Benutzergruppen zuweisen
  • A/B-Test: Neue Funktionen mit bestimmten Benutzersegmenten testen
  • Stufenfahrpläne: Updates allmählich bereitstellen, um das Risiko zu minimieren
  • Umgebungstrennung: Trennen Sie sich bei der Bereitstellung von Updates für Entwicklung, Staging und Produktion

Konfiguration

Abschnitt mit dem Titel “Konfiguration”

Konfigurieren Sie die URL des Kanalendpunkts 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 der Pluginaufruf listChannels()sind, 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 (öffentlicher Zugriff oder Selbstzuweisung) entsprechen.

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

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 diesem Kanal zuweisen, indem sie setChannel(). Anstatt dessen, wenn ein Gerät seine Kanalzuweisung (mit unsetChannel()) entfernt, erhält es automatisch Updates von diesem öffentlichen Kanal, wenn es den Bedingungen des Geräts entspricht.

  • allow_self_set: true: Dies ist ein selbst zuweisbarer Kanal. Geräte können sich explizit diesem Kanal zuweisen, indem sie setChannel(). Dies ist nützlich für Beta-Tests, A/B-Tests oder für die Möglichkeit, Benutzern bestimmte Aktualisierungsverfolgungen zur Verfügung zu stellen.

2. Kanal abrufen (PUT-Anfrage)

Abschnitt mit dem Titel „2. Kanal abrufen (PUT-Anfrage)“

Wenn der Pluginaufruf 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()es sendet eine POST-Anfrage, um das Gerät einem bestimmten Kanal zuzuweisen.

Anfrageformat

Abschnitt mit dem Titel „Anfrageformat“
// 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
}

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 öffentlicher Kanal einer mit public: trueKopieren in die Zwischenablage

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

Kopieren in die Zwischenablage

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

Abschnitt mit dem Titel „4. Kanalgruppe löschen (DELETE-Anfrage)“

Wenn der Pluginaufruf

gesendet wird, sendet es eine DELETE-Anfrage, um die Kanalgruppenzuweisung des Geräts zu entfernen. unsetChannel()Anfrageformat

protectedTokens

Abschnitt mit dem Titel “Anforderungsformat”
// 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, wie Sie den Kanal-Endpunkt 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”

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 mit dem Titel “Geräte-Filter-Logik”

Wenn Sie kompatible Kanäle (GET-Anfrage) auflisten, sollten Sie die Kanäle auf Grundlage dieser Bedingungen filtern:

  1. Plattformüberprüfung: Der Kanal muss die Plattform des Geräts zulassen (ios, android, oder electron)
  2. Geräteartüberprüfung:
    • Wenn is_emulator=true: Der Kanal muss haben allow_emulator=true
    • Wenn is_emulator=false: Der Kanal muss haben allow_device=true
  3. Build-Typ-Überprüfung:
    • Wenn is_prod=true: Der Kanal muss haben allow_prod=true
    • Wenn is_prod=false: Der Kanal muss haben allow_dev=true
  4. Sichtbarkeitsprüfung: Der Kanal 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 die Datenbank-Schema

Abschnitt mit dem Titel „Beispiel für die Datenbank-Schema“

Sie müssen die Kanal-Konfigurationen und Gerätezuweisungen 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 Fehler einplanen:

// 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. SicherheitSeite/ Bereich: Produkt/Preisliste für Unternehmen. Rolle: Benutzeroberflächeneintrag. Anzeige in: Seite enterprise.astro. Nachrichtenschlüssel `enterprise_hero_security_label` (Sicherheitshero für Unternehmen).
  2. : Überprüfen Sie alle Kanalzuweisungen gegen Ihre GeschäftsregelnProtokollierung
  3. : Protokollieren Sie alle Kanaloperationen für die Rechnungslegung und FehlerbehebungLeistung
  4. Seite/ Bereich: Homepage-Problemlösungsbereich. Rolle: Abschnitt oder Seiteüberschrift. Anzeige in: Seite premium-support.astro. Nachrichtenschlüssel `ps_help_performance_title` (Ps-Hilfe-Leistungstitel).: Speichern Sie Kanalkonfigurationen im Cache, um Datenbankanfragen zu reduzieren
  5. Rate Limiting: Implemente eine Rate-Begrenzung, um Missbrauch zu verhindern

Integration mit Updates

Sektion mit dem Titel “Integration mit Updates”

Kanalzuweisungen arbeiten zusammen mit Ihrem Update API-Endpunkt. Wenn ein Gerät einen Update-Antrag stellt, ü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 schafft ein vollständiges selbst gehostetes Kanal-Verwaltungssystem, das Ihnen die volle Kontrolle über die Verteilung von Updates an Ihre Benutzer gibt.

Fortsetzen von Kanal API-Endpunkt

Sektion mit dem Titel “Fortsetzen von Kanal API-Endpunkt”

Wenn Sie Kanal API-Endpunkt um das Routing und die geplante Rollout-Phase für den Kanal zu planen, verbinden Sie ihn mit Mit @capgo/capacitor-Updater zur nativen Fähigkeit in Mit @capgo/capacitor-Updater, Kanäle Kanäle Kanäle Kanäle, und Testversionen zur Produktionsablauf in Testversionen. Testversionen. Testversionen.