L'Endpoint del Canale API

I canali sono un meccanismo fondamentale per la gestione degli aggiornamenti delle app in Capgo. In modalità self-hosted, è necessario implementare i punti di fine dei canali per gestire le assegnazioni dei dispositivi, le query dei canali e le operazioni di gestione dei canali.

I canali

I canali ti consentono di:

• Gestire la distribuzione degli aggiornamenti: Assegnare versioni diverse dell'app a diversi gruppi di utenti
• Test di A/B: Testare nuove funzionalità con segmenti di utenti specifici
• Rilasci in fase di staging: Esegui rilasci progressivi per minimizzare il rischio
• Separazione dell'ambiente: Separa gli aggiornamenti di sviluppo, di staging e di produzione

Configurazione

Configura l'URL del endpoint del canale nel tuo capacitor.config.json:

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

Operazioni sui canali

Il plugin esegue diverse operazioni sui canali che il tuo endpoint deve gestire:

1. Elenco dei canali compatibili (Richiesta GET)

Quando il plugin invoca listChannels(), invia una richiesta GET per recuperare tutti i canali che sono compatibili con il dispositivo. Questo restituisce canali che corrispondono all'ambiente del dispositivo (dev/prod, emulatore/dispositivo reale) e consentono l'accesso pubblico o l'assegnazione auto.

Formato della richiesta

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

Formato della risposta

[
  {
    "id": 1,
    "name": "production",
    "public": true,
    "allow_self_set": false
  },
  {
    "id": 2,
    "name": "beta",
    "public": false,
    "allow_self_set": true
  }
]

Capire i tipi di canale

La risposta include due flag importanti per ogni canale:

• public: true: Questo è un canale predefinito. I dispositivi non possono assegnarsi automaticamente a esso utilizzando setChannel(). Al contrario, se un dispositivo elimina l'assegnazione del suo canale (utilizzando unsetChannel()), riceverà automaticamente gli aggiornamenti da questo canale pubblico se corrispondono alle condizioni del dispositivo.

• allow_self_set: true: Questo è un canale assegnabile. I dispositivi possono assegnarsi esplicitamente a questo canale utilizzando setChannel(). Ciò è utile per il testing beta, A/B testing o per consentire agli utenti di optare per specifiche tracce di aggiornamento.

Nota

Un canale può essere sia public O O allow_self_setTuttavia, di solito non entrambi. I canali pubblici funzionano come default fallback, mentre i canali assegnabili richiedono un'opzione esplicita.

2. Ottieni Canale (Richiesta PUT)

Quando il plugin chiama getChannel()invia una richiesta PUT per recuperare l'assegnazione del canale attuale del dispositivo.

Formato della richiesta

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

Formato della risposta

{
  "status": "ok",
  "channel": "production",
  "allowSet": true,
  "message": "",
  "error": ""
}

3. Imposta il canale (Richiesta POST)

Quando il plugin invoca setChannel()invia una richiesta POST per assegnare il dispositivo a un canale specifico.

Sintassi della richiesta

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

Sintassi della risposta

{
  "status": "ok",
  "message": "Device assigned to channel successfully",
  "error": ""
}

Casi di errore

Quando un dispositivo tenta di assegnarsi a un canale pubblico (uno con 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."
}

Copia nel portapenne

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

Copia nel portapenne

Sezione intitolata “4. Rimuovi canale (Richiesta DELETE)” unsetChannel()Quando il plugin chiama

invia una richiesta DELETE per rimuovere l'assegnazione del canale del dispositivo.

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

Esempio di implementazione

Ecco un esempio di JavaScript su come implementare l'endpoint del canale:

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

Configurazione del canale

La tua sistema di canali dovrebbe supportare queste opzioni di configurazione:

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
}

Logica di filtraggio del dispositivo

When elencare i canali compatibili (richiesta GET), dovresti filtrare i canali in base a queste condizioni:

1. Controllo della piattaforma: Il canale deve consentire alla piattaforma del dispositivo (ios, androido electron)
2. Controllo del tipo di dispositivo:
   • Se is_emulator=true: Il canale deve avere allow_emulator=true
   • Se is_emulator=false: Il canale deve avere allow_device=true
3. Controllo del tipo di build:
   • Se is_prod=true: Il canale deve avere allow_prod=true
   • Se is_prod=false: Il canale deve avere allow_dev=true
4. Controllo di visibilità: Il canale deve essere o public=true O 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
  })
}

Esempio di schema di database

Dovrai memorizzare le configurazioni dei canali e le assegnazioni dei dispositivi:

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

Gestione degli errori

Affrontare gli scenari di errore comuni:

// 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"
}

Pratiche raccomandate

1. Sicurezzacontext: Pagina/area: Pagina prodotti/prezzi aziendale. Ruolo: Etichetta di interfaccia utente. Visualizzato in: pagina enterprise.astro. Chiave messaggio `enterprise_hero_security_label` (Etichetta sicurezza eroe aziendale).
2. : Verifica tutte le assegnazioni dei canali rispetto alle regole aziendaliLogging
3. : Registra tutte le operazioni dei canali per la revisione e il debugPerformance
4. context: Pagina/area: Sezione problema/soluzione homepage. Ruolo: Intestazione di sezione o pagina. Visualizzato in: pagina premium-support.astro. Chiave messaggio `ps_help_performance_title` (Titolo aiuto prestazioni Ps).: Caching le configurazioni dei canali per ridurre le query al database
5. Limitazione dei Ratei: Implementare la limitazione dei ratei per prevenire l'abuso

Integrazione con gli Aggiornamenti

Gli assegnamenti dei canali funzionano insieme al tuo Punto di accesso per il canale API. Quando un dispositivo richiede un aggiornamento, controlla la sua assegnazione del canale per determinare quale versione servire:

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

Questo crea un sistema completo di gestione dei canali auto-hosted che ti dà il controllo completo su come gli aggiornamenti vengono distribuiti ai tuoi utenti.

Continua da qui dal Punto di accesso per il canale API

Se stai utilizzando Canale API Endpoint per pianificare la routing dei canali e la distribuzione in fase di testing, connettilo con Utilizzando @capgo/capacitor-aggiornatore per la capacità nativa in Utilizzando @capgo/capacitor-aggiornatore, Canali contexto: nome del feature di rilascio di Capgo. Pagina/area: pagina di marketing delle soluzioni di Capgo. Ruolo: etichetta UI breve o elemento di navigazione. Visto in: pagina solutions/white-label.astro. Chiave di messaggio `solutions_white_label_visual_cell2_value` (Valore della cella visiva del white label delle soluzioni). per la dettaglio di implementazione in Canali, Canali contexto: nome del feature di rilascio di Capgo. Pagina/area: pagina di marketing delle soluzioni di Capgo. Ruolo: etichetta UI breve o elemento di navigazione. Visto in: pagina solutions/white-label.astro. Chiave di messaggio `solutions_white_label_visual_cell2_value` (Valore della cella visiva del white label delle soluzioni). per la dettaglio di implementazione in Canali, Canali contexto: nome del feature di rilascio di Capgo. Pagina/area: pagina di marketing delle soluzioni di Capgo. Ruolo: etichetta UI breve o elemento di navigazione. Visto in: pagina solutions/white-label.astro. Chiave di messaggio `solutions_white_label_visual_cell2_value` (Valore della cella visiva del white label delle soluzioni). e per la dettaglio di implementazione in Canali, e per il flusso di lavoro del prodotto in Beta Testing Solution.