Channel API Endpoint

Copiez un prompt de configuration avec les étapes d'installation et la guide markdown complet pour ce plugin.

Les canaux sont un mécanisme de base pour gérer les mises à jour d'applications dans Capgo. Dans le mode auto-hébergé, vous devez mettre en œuvre des points de terminaison de canal pour gérer les affectations de dispositifs, les requêtes de canal et les opérations de gestion de canal.

Comprendre les canaux

Les canaux vous permettent de :

Gestion de mise à jour de distribution: Affecter différentes versions d'application à différents groupes d'utilisateurs
Test A/B: Tester de nouvelles fonctionnalités avec des segments d'utilisateurs spécifiques
Déploiement étape par étape: Déployer progressivement les mises à jour pour minimiser les risques
Séparation d'environnement: Séparer les mises à jour de développement, de pré-production et de production

Configuration

Copier dans le presse-papier capacitor.config.json:

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

Opérations de canal

Le plugin effectue différentes opérations de canal dont votre point de terminaison doit tenir compte :

1. Liste des canaux compatibles (requête GET)

Lorsque le plugin appelle listChannels(), il envoie une requête GET pour récupérer tous les canaux qui sont compatibles avec le dispositif. Cela retourne les canaux qui correspondent à l'environnement du dispositif (dev/prod, émulateur/appareil réel) et qui autorisent soit l'accès public soit l'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 canal

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

public: true : C'est un canal par défaut. Les appareils ne peuvent pas se désigner eux-mêmes à ce canal en utilisant setChannel() au lieu de cela, si un appareil supprime son affectation de canal (en utilisant unsetChannel()), il recevra automatiquement des mises à jour à partir de ce canal public si elles correspondent aux conditions de l'appareil.
allow_self_set: true : C'est un canal autorisant la désignation par l'appareil. Les appareils peuvent se désigner explicitement à ce canal en utilisant setChannel(). Cela est utile pour les tests de version bêta, les tests A/B ou pour permettre aux utilisateurs de s'abonner à des pistes d'actualisation spécifiques.

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

Lorsque le plugin appelle getChannel(), il envoie une requête PUT pour récupérer la mise à jour actuelle du canal du dispositif.

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 réponse

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

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

Lorsque le plugin appelle setChannel(), il envoie une requête POST pour affecter le dispositif à un canal spécifique.

Format de la demande

// 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 réponse

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

Cas d'erreur

Lorsqu'un appareil tente d'attribuer à lui-même un canal canal public (un avec public: true), votre point d'entrée devrait retourner 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 d'attribuer à lui-même un canal qui ne permet pas la réaffectation :

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

4. Canal non défini (requête DELETE)

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

Format de la demande

// 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 de mise en œuvre de 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 du canal

Votre système de canal doit supporter 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 de dispositif

Lors de la liste des canaux compatibles (requête GET), vous devez filtrer les canaux en fonction de ces conditions :

Vérification de plateforme: Le canal doit autoriser la plateforme du dispositif (ios, android, ou electron)
Vérification de type de dispositif:
- Si is_emulator=true: Le canal doit avoir allow_emulator=true
- Si is_emulator=falseLe canal doit avoir allow_device=true
Vérification du type de construction:
- Si is_prod=trueLe canal doit avoir allow_prod=true
- Si is_prod=falseLe canal doit avoir allow_dev=true
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

You devrez stocker les configurations de canal et les affectations de dispositif :

-- 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érer les scénarios d'erreurs 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"
}

Meilleures pratiques

Sécurité: Valider toutes les affectations de canal contre vos règles commerciales
Journalisation: Enregistrer toutes les opérations de canal pour le suivi et la débogage
Performances: Stocker les configurations du canal de cache pour réduire les requêtes de base de données
Validation: Vérifier l'authenticité de l'identifiant de l'appareil et de l'identifiant de l'application
Limitation de taux: Mettre en œuvre une limitation de taux pour prévenir les abus

Intégration avec les mises à jour

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

Cette création d'un système de gestion de canal autonome et complet vous donne un contrôle total sur la façon dont les mises à jour sont distribuées à vos utilisateurs.

Continuez de Channel API Endpoint

Si vous utilisez Channel API Endpoint pour planifier la mise en route des canaux et la mise en production étape par étape, connectez-le à En utilisant @capgo/capacitor-mises à jour pour la capacité native dans En utilisant @capgo/capacitor-mises à jour, Canaux pour le détail d'implémentation dans Canaux Canaux pour le détail d'implémentation dans Canaux, Canaux pour les détails d'implémentation dans Canaux, et Solution de test bêta pour le flux de travail du produit dans Solution de test bêta.