Installer et configurer le SDK

Préparer votre environnement de développement

Avant de coder votre première application, il faut installer le SDK et poser proprement votre espace de travail. Une demi-heure investie ici vous évitera des heures de débogage plus tard, car la moitié des problèmes rencontrés par les débutants viennent d’un manifest mal formé ou d’une variable d’environnement absente.

Prérequis techniques

• Node.js 20+ — le runtime JavaScript (vérifiez avec node --version)
• npm 10+ ou pnpm — le gestionnaire de paquets
• Git — pour le versioning
• Un éditeur de code — VS Code recommandé, avec l’extension OpenAI

Créer un compte développeur OpenAI

L’accès développeur ne s’active pas automatiquement avec un compte ChatGPT ordinaire : il faut le demander depuis le portail développeurs d’OpenAI, en quatre étapes.

1. Connectez-vous à votre compte OpenAI
2. Accédez à la section Apps Developer dans les paramètres
3. Acceptez les conditions d’utilisation du programme développeur
4. Générez une clé API Apps SDK (distincte de la clé API standard)

Cette dernière précision compte : la clé Apps SDK n’est pas votre clé API habituelle et ne l’interchange pas. Elle authentifie vos requêtes pendant le développement et les tests.

Installer le SDK

Le SDK existe en TypeScript, la version principale, et en Python. Ce cours utilise TypeScript. La séquence ci-dessous crée le projet, installe le paquet et ajoute les outils de développement.

# Créer un nouveau projet
mkdir mon-app-chatgpt
cd mon-app-chatgpt
npm init -y

# Installer le SDK
npm install @openai/apps-sdk

# Installer les dépendances de développement
npm install -D typescript @types/node tsx

Initialiser TypeScript

npx tsc --init

La configuration générée par défaut n’est pas adaptée : elle cible une version ancienne de JavaScript et n’active pas le mode strict, qui vous fera pourtant gagner beaucoup de temps sur les schémas de paramètres. Remplacez le contenu de tsconfig.json par celui-ci.

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "declaration": true
  },
  "include": ["src/**/*"]
}

Configurer le manifest de l’application

Chaque app ChatGPT exige un fichier chatgpt-app.json à la racine du projet. C’est sa carte d’identité : le Store y lit son nom, le runtime y trouve son point d’entrée, et la plateforme y vérifie les permissions demandées.

{
  "name": "Mon Application",
  "slug": "mon-application",
  "description": "Description courte de ce que fait votre app",
  "version": "1.0.0",
  "runtime": "node",
  "entry": "src/index.ts",
  "permissions": ["actions", "widgets"],
  "auth": {
    "type": "oauth2",
    "clientId": "${OAUTH_CLIENT_ID}"
  },
  "actions": "./src/actions/schema.json",
  "widgets": "./src/widgets/"
}

Quatre champs sont obligatoires et méritent votre attention.

Le slug est votre identifiant permanent : il figure dans l’URL de votre app et ne se change pas après publication. Choisissez-le comme vous choisiriez un nom de domaine. Quant aux permissions, déclarez uniquement les piliers que vous utilisez réellement — demander commerce alors que votre app ne vend rien ralentira la revue et inquiétera vos utilisateurs.

Configurer les variables d’environnement

Créez un fichier .env à la racine, et ne le commitez jamais.

# .env
OPENAI_APPS_API_KEY=sk-apps-xxxxxxxxxxxxx
OPENAI_APP_SLUG=mon-application
NODE_ENV=development

Ajoutez ensuite un .env.example aux valeurs vides. Ce second fichier, lui, est versionné : il documente pour vos collègues — et pour vous dans six mois — quelles variables l’application attend, sans jamais exposer les secrets.

# .env.example
OPENAI_APPS_API_KEY=
OPENAI_APP_SLUG=
NODE_ENV=development

Structure de projet recommandée

L’arborescence ci-dessous sépare les trois responsabilités que vous manipulerez sans arrêt : les actions dans leur dossier, les widgets dans le leur, les utilitaires à part. Adoptez-la dès le premier jour, même pour une app minuscule — le jour où vous en aurez dix, la migration coûterait cher.

mon-app-chatgpt/
├── src/
│   ├── index.ts          # Point d'entrée
│   ├── actions/
│   │   ├── schema.json   # Schéma OpenAPI des actions
│   │   └── handlers.ts   # Logique des actions
│   ├── widgets/
│   │   └── dashboard.ts  # Définitions de widgets
│   └── utils/
│       └── auth.ts       # Helpers d'authentification
├── chatgpt-app.json      # Manifest de l'app
├── tsconfig.json
├── package.json
└── .env

Vérifier l’installation

Ne passez pas à la suite sans avoir validé votre installation. Créez un src/index.ts minimal qui déclare une seule action triviale.

import { ChatGPTApp } from "@openai/apps-sdk";

const app = new ChatGPTApp({
  slug: process.env.OPENAI_APP_SLUG!,
});

app.action("hello", {
  description: "Retourne un message de bienvenue",
  handler: async () => {
    return { message: "Votre SDK est correctement installé !" };
  },
});

app.start();
console.log("App démarrée avec succès");

Lancez ensuite le serveur de développement.

npx tsx src/index.ts

Si le message de confirmation s’affiche, votre environnement est prêt et vous pouvez construire une vraie application. S’il ne s’affiche pas, vérifiez d’abord la présence du .env : une variable OPENAI_APP_SLUG manquante est de loin la cause la plus fréquente à ce stade.

Points clés à retenir

• Le SDK nécessite Node.js 20+ et un compte développeur OpenAI
• Le fichier chatgpt-app.json est le manifest obligatoire de votre app
• La structure du projet sépare actions, widgets et utilitaires
• Les variables d’environnement contiennent vos clés API — ne les commitez jamais
• Vérifiez l’installation avec un fichier index.ts minimal avant d’aller plus loin