Endpoint de canal API

Les canaux sont un mécanisme essentiel pour gérer les mises à jour d'applications dans Capgo. En mode self-hosted, vous devez implémenter des endpoints de canal pour gérer l'assignation des appareils, les requêtes de canal et les opérations de gestion des canaux.

Comprendre les canaux

Les canaux vous permettent de :

• Contrôler la distribution des mises à jour: Assigner différentes versions de l'app à différents groupes d'utilisateurs
• Tests A/B: Test new features with specific user segments
• Déploiements progressifs: Gradually deploy updates to minimize risk
• Séparation des environnements: Séparer les mises à jour de développement, de staging et de production

Configuration

Configurez l'URL du point de terminaison du canal dans votre capacitor.config.json:

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

Opérations sur les canaux

Le plugin effectue différentes opérations de canal que votre endpoint doit gérer :

1. Lister les canaux compatibles (requête GET)

Lorsque le plugin appelle listChannels(), il envoie une requête GET pour récupérer tous les canaux compatibles avec l'appareil. Cela retourne les canaux correspondant à l'environnement de l'appareil (dev/prod, émulateur/appareil réel) et qui autorisent soit un accès public, soit une auto-assignation.

Format de la requête

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

Format de la réponse

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

Comprendre les types de canaux

La réponse inclut deux flags importants pour chaque canal :

• public: true: Il s'agit d'un canal par défaut. Les appareils ne peuvent pas s'y assigner via setChannel(). Au lieu de cela, si un appareil supprime son assignation de canal (en utilisant unsetChannel()), il recevra automatiquement les mises à jour de ce canal public s'il correspond aux conditions de l'appareil.

• allow_self_set: true: Il s'agit d'un canal auto-assignable. Les appareils peuvent s'assigner explicitement à ce canal en utilisant setChannel()C'est utile pour les tests bêta, l'A/B testing ou pour permettre aux utilisateurs de choisir des canaux de mise à jour spécifiques.

Remarque

Un canal peut être soit public OU allow_self_set, mais généralement pas les deux. Les canaux publics servent de repli par défaut, tandis que les canaux auto-assignables nécessitent une activation explicite.

2. Récupérer un canal (requête PUT)

Lorsque le plugin appelle getChannel(), il envoie une requête PUT pour récupérer l'assignation du canal actuel de l'appareil.

Format de la requête

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

Format de la réponse

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

3. Définir un canal (requête POST)

Lorsque le plugin appelle setChannel(), il envoie une requête POST pour assigner l'appareil à un canal spécifique.

Format de la requête

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

Format de la réponse

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

Cas d'erreur

Lorsqu'un appareil tente de s'assigner à un canal public (un canal avec public: true), votre endpoint doit renvoyer une erreur :

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

Lorsqu'un appareil tente de s'assigner à un canal qui n'autorise pas l'auto-assignation :

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

4. Dissocier le canal (requête DELETE)

Lorsque le plugin appelle unsetChannel(), il envoie une requête DELETE pour supprimer l'assignation du canal de l'appareil.

Format de la requête

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

Exemple d'implémentation

Voici un exemple JavaScript pour implémenter l'endpoint du 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"
  }
}

Configuration des canaux

Votre système de canaux doit prendre en charge ces options de configuration :

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
}

Logique de filtrage des appareils

Lorsque vous listez les canaux compatibles (requête GET), vous devez filtrer les canaux selon ces conditions :

1. Vérification de la plateforme: Le canal doit autoriser la plateforme de l'appareil (ios, android, ou electron)
2. Vérification du type d'appareil:
   • Si is_emulator=true: Le canal doit avoir allow_emulator=true
   • Si is_emulator=false: Le canal doit avoir allow_device=true
3. Vérification du type de build:
   • Si is_prod=true: Le canal doit avoir allow_prod=true
   • Si is_prod=false: Le canal doit avoir allow_dev=true
4. Vérification de la visibilité: Le canal doit être soit public=true OU 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
  })
}

Exemple de schéma de base de données

Vous devrez stocker les configurations des canaux et les affectations des appareils :

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

Gestion des erreurs

Gérez les scénarios d'erreur courants :

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

Bonnes pratiques

1. Sécurité: Validez tous les assignements de canaux selon vos règles métier
2. Logging: Loggez toutes les opérations de canaux pour l'audit et le débogage
3. Performance: Mettez en cache les configurations de canaux pour réduire les requêtes DB
4. Validation: Vérifiez l'authenticité du device_id et de l'app_id
5. Limitation de débit: Implémentez le rate limiting pour prévenir les abus

Intégration avec les mises à jour

Les assignements de canaux fonctionnent avec votre Endpoint de mise à jour API. Lorsqu'un appareil demande une mise à jour, vérifiez l'attribution de son canal pour déterminer quelle version lui 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
  }
}

Cela crée un système complet de gestion de canaux auto-hébergé qui vous donne un contrôle total sur la distribution des mises à jour à vos utilisateurs.

Continuer avec l'endpoint de canal API

Si vous utilisez Endpoint de canal API pour planifier le routage des canaux et le déploiement progressif, connectez-l’avec Utiliser @capgo/capacitor-updater pour la capacité native dans « Utiliser @capgo/capacitor-updater », Canaux pour les détails d'implémentation des canaux, Canaux pour les détails d'implémentation des canaux, Canaux pour les détails d'implémentation des canaux, et Solution de bêta-test pour le workflow produit dans la solution de tests bêta.