Endpoint de canal API

Los canales son un mecanismo fundamental para gestionar actualizaciones de aplicaciones en Capgo. En modo autogestionado, debes implementar puntos finales de canal para manejar asignaciones de dispositivos, consultas de canales y operaciones de gestión de canales.

Entendiendo los canales

Los canales te permiten:

• Distribución de actualizaciones: Asignar diferentes versiones de la aplicación a diferentes grupos de usuarios
• Pruebas A/B: Probar nuevas características con segmentos de usuarios específicos
• Despliegue en etapas: Desplegar actualizaciones de manera gradual para minimizar el riesgo
• Separación de entornos: Separar actualizaciones de desarrollo, pruebas y producción

Configuración

Configura la URL del extremo de canal en tu capacitor.config.json:

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

Operaciones de Canal

El plugin realiza diferentes operaciones de canal que su punto final necesita manejar:

1. Listar Canales Compatibles (Solicitud GET)

Cuando el plugin llama listChannels(), envía una solicitud GET para recuperar todos los canales que son compatibles con el dispositivo. Esto devuelve canales que coinciden con el entorno del dispositivo (dev/prod, emulador/dispositivo real) y permiten acceso público o autoasignación.

Formato de Solicitud

// 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 de Respuesta

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

Entendiendo los tipos de canal

La respuesta incluye dos banderas importantes para cada canal:

• public: trueEste es un canal canal predeterminado. Los dispositivos no pueden autoasignarse a él usando setChannel()En su lugar, si un dispositivo elimina su asignación de canal (utilizando unsetChannel()), recibirá automáticamente actualizaciones de este canal público si coincide con las condiciones del dispositivo.

• allow_self_set: trueEste es un canal autoasignable. Los dispositivos pueden asignarse explícitamente a este canal usando setChannel(). Esto es útil para la prueba beta, la prueba A/B o permitir a los usuarios optar por pistas de actualización específicas.

Nota

Un canal puede ser public O allow_self_set, pero típicamente no ambos. Los canales públicos sirven como fallback predeterminado, mientras que los canales autoasignables requieren una opt-in explícita.

2. Obtener Canal (Solicitud PUT)

Cuando el plugin llama getChannel(), envía una solicitud PUT para recuperar la asignación de canal actual del dispositivo.

Formato de Solicitud

// 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 de respuesta

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

3. Establecer canal (Solicitud POST)

Cuando el plugin llama setChannel(), envía una solicitud POST para asignar el dispositivo a un canal específico.

Formato de solicitud

// 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 de respuesta

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

Casos de error

Cuando un dispositivo intenta asignarse a un canales públicos (uno con public: true), su punto de conexión debería devolver un error:

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

Cuando un dispositivo intenta asignarse a un canal que no permite la asignación de sí mismo:

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

4. Canal deshabilitado (Solicitud DELETE)

Cuando el plugin llama unsetChannel(), envía una solicitud DELETE para eliminar la asignación de canal del dispositivo.

Formato de solicitud

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

Implementación de ejemplo

Aquí hay un ejemplo de JavaScript de cómo implementar el punto final de canal:

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

Configuración de canal

Su sistema de canales debe admitir estas opciones de configuración:

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
}

Razonamiento de filtrado de dispositivos

Al listar canales compatibles (solicitud GET), debe filtrar los canales según estas condiciones:

1. Verificación de plataforma: El canal debe permitir la plataforma del dispositivo (ios, android, o electron)
2. Verificación de tipo de dispositivo:
   • Si is_emulator=true: El canal debe tener allow_emulator=true
   • Si is_emulator=falseEl canal debe tener allow_device=true
3. Verificación del tipo de construcción:
   • Si is_prod=trueEl canal debe tener allow_prod=true
   • Si is_prod=falseEl canal debe tener allow_dev=true
4. Verificación de visibilidadEl canal debe ser 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
  })
}

Ejemplo de esquema de base de datos

Deberá almacenar configuraciones de canales y asignaciones de dispositivos:

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

Gestión de Errores

Gestionar escenarios de errores comunes:

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

Prácticas Recomendadas

1. Seguridad: Validar todas las asignaciones de canales contra sus reglas comerciales
2. Registro: Registrar todas las operaciones de canales para auditorías y depuración
3. Desempeño: Almacena configuraciones de canales de caché para reducir consultas de base de datos
4. Validación: Verifica la autenticidad de device_id y app_id
5. Límite de Tasa: Implementa límites de tasa para prevenir el abuso

Integración con Actualizaciones

Las asignaciones de canales funcionan en conjunto con tu Actualización API Endpoint. Cuando un dispositivo solicita una actualización, verifica su asignación de canal para determinar qué versión servir:

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

Esta crea un sistema de gestión de canales autónomo completo que le da control total sobre cómo se distribuyen las actualizaciones a sus usuarios.

Siga desde el punto final de canal API

Si está utilizando Punto final de canal API para planificar la ruta de canal y la implementación en etapas, conecte con Usando @capgo/capacitor-actualizador para la capacidad nativa en Usando @capgo/capacitor-actualizador, Canales para el detalle de implementación en Canales Canales para el detalle de implementación en Canales, Canales para los detalles de implementación en Canales, y Solución de Pruebas Beta para el flujo de trabajo del producto en Solución de Pruebas Beta.