Architecture : actions, widgets, commerce

Les trois piliers du Apps SDK

Le ChatGPT Apps SDK s’articule autour de trois composants fondamentaux qui, assemblés, forment une application complète. Prenez le temps de comprendre cette architecture avant d’écrire la moindre ligne de code : la plupart des erreurs de conception viennent d’une confusion entre ce qui relève du serveur, de l’affichage et de la transaction.

La répartition est nette. Les Actions connectent votre backend et vont chercher la donnée. Les Widgets la mettent en forme dans la conversation. Le Commerce encaisse quand l’utilisateur décide d’acheter. Un même parcours — chercher un vol, le voir affiché, le réserver — traverse les trois.

Actions : connecter votre backend

Les Actions sont le mécanisme par lequel votre app communique avec le monde extérieur. Point essentiel et souvent mal compris : ce n’est pas vous qui décidez du déclenchement, c’est le modèle ChatGPT, en fonction du contexte de la conversation. Vous décrivez ce que sait faire votre serveur, il choisit quand le solliciter.

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

Trois familles d’actions coexistent. Les actions serveur, de loin les plus courantes, effectuent un appel HTTP vers votre API — c’est le cas de getWeather ci-dessus. Les actions locales exécutent leur logique côté client, dans le navigateur, ce qui évite un aller-retour réseau pour un simple calcul. Les actions composées, enfin, enchaînent plusieurs appels avec une logique conditionnelle : vérifier un stock, puis réserver seulement si l’article est disponible.

Widgets : interfaces dans ChatGPT

Les Widgets transforment une conversation textuelle en expérience interactive. Plutôt que de décrire un graphique de ventes en trois phrases, vous l’affichez ; plutôt que d’énumérer des options, vous présentez des boutons cliquables.

La bibliothèque fournie couvre l’essentiel des besoins. Vous y trouvez des formulaires (champs texte, sélecteurs, cases à cocher, boutons), des visualisations en barres, en lignes ou en camembert, des médias comme les images, les cartes géographiques et les lecteurs audio et vidéo. Côté données, des tableaux triables et des listes paginées ; côté structure, des onglets, des accordéons et des menus pour organiser un affichage dense.

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

Le rendu est assuré nativement par ChatGPT : vous ne livrez pas du HTML, vous décrivez une structure. Quand l’utilisateur clique, saisit ou sélectionne, ces interactions déclenchent une action ou mettent à jour l’état de la conversation — le bouton « Réserver » ci-dessus appellera l’action bookFlight.

Commerce : vendre dans ChatGPT

Le troisième pilier intègre la transaction financière dans le flux conversationnel, sans redirection vers un site externe. Quatre modèles sont supportés : l’achat ponctuel, où l’utilisateur paie une fois pour un produit ou un service ; l’abonnement, avec paiements récurrents gérés automatiquement ; le freemium, qui laisse une partie des fonctionnalités gratuites et réserve le reste aux clients payants ; et l’essai gratuit, période de découverte avant engagement. Le SDK prend en charge le tunnel de paiement de manière sécurisée — OpenAI traite les paiements via Stripe en backend et vous reverse votre part après commission.

Le cycle de vie d’une requête

Ces trois piliers ne s’utilisent presque jamais isolément. L’enchaînement démarre avec un message de l’utilisateur dans ChatGPT ; le modèle y reconnaît une intention que votre app sait traiter et appelle les Actions nécessaires pour récupérer les données. Il génère ensuite un Widget pour afficher le résultat, et si l’utilisateur décide d’acheter, le module Commerce prend le relais et traite le paiement. Le modèle referme la boucle en confirmant la transaction dans la conversation.

Rien de tout cela n’est visible pour l’utilisateur, qui a simplement l’impression d’avoir posé une question et obtenu une réponse actionnable. Gardez ce cycle en tête pendant tout le cours : chaque leçon technique qui suit approfondit l’une de ces étapes.

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