Architecture : actions, widgets, commerce

Les trois piliers du Apps SDK

Le ChatGPT Apps SDK s’articule autour de trois composants fondamentaux qui, ensemble, permettent de construire des applications complètes. Comprendre cette architecture est essentiel avant d’écrire la moindre ligne de code.

Chaque pilier répond à un besoin distinct : les Actions connectent votre backend, les Widgets créent l’interface utilisateur, et le Commerce gère les transactions financières.

Actions : connecter votre backend

Les Actions sont le mécanisme par lequel votre app communique avec le monde extérieur. Le modèle ChatGPT décide quand appeler une action en fonction du contexte de la conversation.

Comment ça fonctionne

1. Vous définissez un schéma OpenAPI (ou un manifest simplifié) décrivant vos endpoints
2. Le modèle analyse la conversation et décide d’appeler une action
3. Le SDK envoie une requête HTTP à votre serveur
4. Votre serveur traite la requête et renvoie une réponse
5. Le modèle intègre la réponse dans la conversation

// Exemple de définition d'action
const actions = {
  getWeather: {
    description: "Récupère la météo pour une ville donnée",
    parameters: {
      city: { type: "string", description: "Nom de la ville" },
      units: { type: "string", enum: ["celsius", "fahrenheit"] }
    },
    handler: async ({ city, units }) => {
      const data = await fetchWeatherAPI(city, units);
      return { temperature: data.temp, conditions: data.desc };
    }
  }
};

Types d’actions

• Actions serveur — appels HTTP vers votre API (le plus courant)
• Actions locales — logique exécutée côté client dans le navigateur
• Actions composées — chaînes de plusieurs appels avec logique conditionnelle

Widgets : interfaces dans ChatGPT

Les Widgets transforment une conversation textuelle en une expérience interactive. Au lieu de décrire un graphique en texte, vous l’affichez directement.

Composants disponibles

Le SDK fournit une bibliothèque de composants prêts à l’emploi :

• Formulaires — champs texte, sélecteurs, cases à cocher, boutons
• Visualisations — graphiques en barres, lignes, camemberts
• Médias — images, cartes géographiques, lecteurs audio/vidéo
• Données — tableaux triables, listes paginées
• Navigation — onglets, accordéons, menus

// Exemple de widget simple
const widget = {
  type: "card",
  title: "Résultat de recherche",
  content: [
    { type: "text", value: "Vol Paris → Tokyo" },
    { type: "metric", label: "Prix", value: "€487" },
    { type: "button", label: "Réserver", action: "bookFlight" }
  ]
};

Rendu et interaction

Les widgets sont rendus nativement par ChatGPT. L’utilisateur interagit avec eux (clics, saisie, sélection) et ces interactions déclenchent des actions ou mettent à jour l’état de la conversation.

Commerce : vendre dans ChatGPT

Le pilier Commerce permet d’intégrer des transactions financières directement dans le flux conversationnel, sans rediriger l’utilisateur vers un site externe.

Modèles supportés

• Achat ponctuel — l’utilisateur paie une fois pour un produit ou service
• Abonnement — paiements récurrents avec gestion automatique
• Freemium — fonctionnalités gratuites avec options payantes
• Essai gratuit — période d’essai avant engagement

Flux de paiement

Le SDK gère le tunnel de paiement de manière sécurisée. OpenAI se charge du traitement des paiements (via Stripe en backend) et vous recevez votre part après commission.

Le cycle de vie d’une requête

Quand un utilisateur interagit avec votre app, voici ce qui se passe :

1. L’utilisateur envoie un message dans ChatGPT
2. Le modèle identifie que votre app peut répondre
3. Il appelle les Actions nécessaires pour récupérer les données
4. Il génère un Widget pour afficher le résultat
5. Si l’utilisateur achète, le module Commerce traite le paiement
6. Le modèle confirme la transaction dans la conversation

Points clés à retenir

• Le Apps SDK repose sur trois piliers complémentaires : Actions, Widgets, Commerce
• Les Actions connectent votre backend via des requêtes HTTP sécurisées
• Les Widgets affichent des interfaces interactives dans la conversation
• Le Commerce permet les paiements sans redirection externe
• Le modèle orchestre intelligemment les appels entre ces trois composants