Endpoint canale API

I canali sono un meccanismo fondamentale per la gestione degli aggiornamenti delle app in Capgo. Nella modalità self-hosted, è necessario implementare gli endpoint del canale per gestire le assegnazioni dei dispositivi, le query del canale e le operazioni di gestione del canale.

Comprendere i canali

I canali ti consentono di:

• Controlla la distribuzione degli aggiornamenti: assegna diverse versioni dell’app a diversi gruppi di utenti
• Test A/B: prova nuove funzionalità con segmenti di utenti specifici
• Implementazioni graduali: distribuisci gradualmente gli aggiornamenti per ridurre al minimo i rischi
• Separazione dell’ambiente: aggiornamenti separati di sviluppo, gestione temporanea e produzione

##Configurazione

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

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

Operazioni sul canale

Il plugin esegue diverse operazioni di canale che il tuo endpoint deve gestire:

1. Elenco canali compatibili (richiesta GET)

Quando il plugin chiama listChannels(), invia una richiesta GET per recuperare tutti i canali compatibili con il dispositivo. Ciò restituisce i canali che corrispondono all’ambiente del dispositivo (sviluppo/produzione, emulatore/dispositivo reale) e consentono l’accesso pubblico o l’autoassegnazione.

Richiedi formato

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

Comprendere i tipi di canale

La risposta include due flag importanti per ciascun canale:

• public: true: questo è un canale predefinito. I dispositivi non possono autoassegnarsi utilizzando setChannel(). Invece, se un dispositivo rimuove l’assegnazione del canale (utilizzando unsetChannel()), riceverà automaticamente gli aggiornamenti da questo canale pubblico se corrisponde alle condizioni del dispositivo.

• allow_self_set: true: questo è un canale autoassegnabile. I dispositivi possono assegnarsi esplicitamente a questo canale utilizzando setChannel(). Ciò è utile per il beta testing, il test A/B o per consentire agli utenti di aderire a specifici percorsi di aggiornamento.

Note

Un canale può essere public O allow_self_set, ma in genere non entrambi. I canali pubblici fungono da fallback predefinito, mentre i canali autoassegnabili richiedono un consenso esplicito.

2. Ottieni canale (richiesta PUT)

Quando il plug-in chiama getChannel(), invia una richiesta PUT per recuperare l’assegnazione corrente del canale del dispositivo.

Richiedi formato

// 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 canale (richiesta POST)

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

Richiedi formato

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

Formato 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), l’endpoint dovrebbe restituire un errore:

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

Quando un dispositivo tenta di assegnarsi a un canale che non consente l’autoassegnazione:

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

4. Cancella canale (richiesta ELIMINA)

Quando il plug-in chiama unsetChannel(), invia una richiesta DELETE per rimuovere l’assegnazione del canale del dispositivo.

Richiedi formato

// 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 JavaScript di 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

Il tuo 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 dispositivoQuando si elencano i canali compatibili (richiesta GET), è necessario filtrare i canali in base a queste condizioni:

1. Controllo della piattaforma: il canale deve consentire la piattaforma del dispositivo (ios, android o electron)
2. Verifica 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. Verifica del tipo di costruzione:
   • Se is_prod=true: il canale deve avere allow_prod=true
   • Se is_prod=false: il canale deve avere allow_dev=true
4. Controllo visibilità: il canale deve essere 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

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

Migliori pratiche

1. Sicurezza: convalida tutte le assegnazioni dei canali rispetto alle regole aziendali
2. Logging: registra tutte le operazioni del canale per il controllo e il debug
3. Prestazioni: memorizza nella cache le configurazioni dei canali per ridurre le query del database
4. Convalida: verifica l’autenticità di device_id e app_id
5. Limitazione della velocità: implementa la limitazione della velocità per prevenire abusi

Integrazione con aggiornamenti

Le assegnazioni dei canali funzionano insieme al tuo Update API Endpoint. Quando un dispositivo richiede un aggiornamento, controlla l’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
  }
}

Ciò crea un sistema completo di gestione dei canali self-hosted che ti offre il pieno controllo sul modo in cui gli aggiornamenti vengono distribuiti ai tuoi utenti.