Tutoriel étape par étape : Créer une application Optimizely Connect Platform (OCP)

Prérequis

Avant de commencer, assurez-vous d'avoir les éléments suivants en place :

Environnement de développement

• Node.js 18 ou plus récent installé
• Un éditeur de code avec support TypeScript (VS Code fonctionne bien)
• Git pour le contrôle de version
• Accès au terminal pour les commandes CLI

Accès Optimizely

• Un compte développeur OCP (demandez l'accès en envoyant un courriel à l'équipe de développement OCP listée dans la documentation d'Optimizely)
• Le CLI OCP installé et configuré avec vos identifiants
• Accès à au moins un compte OCP où vous pouvez installer des applications

Services externes

• Un espace de travail Slack où vous pouvez créer des webhooks entrants
• Une URL webhook Slack pour les tests (créez-en une sur api.slack.com sous Incoming Webhooks)

Connaissances techniques

• Familiarité de base avec TypeScript
• Compréhension des API REST et des webhooks
• Expérience avec la gestion de paquets npm

Si vous n'avez pas encore de compte développeur OCP, c'est l'élément qui prend le plus de temps à obtenir. Optimizely traite généralement les demandes en quelques jours ouvrables.

Étape 1 : Installer et configurer le CLI OCP

Le CLI OCP gère tout, de la création de la structure de votre application jusqu'à sa publication dans le répertoire d'applications. Commencez par l'installer globalement :

npm install -g @optimizely/ocp-cli

Après l'installation, authentifiez-vous avec vos identifiants de développeur :

ocp auth login

Cela ouvre une fenêtre de navigateur pour l'authentification Opti ID. Une fois authentifié, vérifiez votre configuration :

ocp auth status

Vous devriez voir les informations de votre compte développeur et les permissions associées.

Étape 2 : Enregistrer votre application

Chaque application OCP nécessite un identifiant unique enregistré auprès d'Optimizely avant de pouvoir la développer. Exécutez la commande d'enregistrement :

ocp app register

Le CLI vous demande plusieurs informations :

• App ID : Utilisez le format snake_case, comme slack_notifier. Cet identifiant doit être unique globalement.
• Display Name : Nom lisible par les humains, comme « Slack Notifier »
• Target Product : Sélectionnez « Connect Platform »
• Visibility : Choisissez « private » pour le développement (vous pourrez changer ça plus tard)

L'enregistrement réserve votre identifiant d'application et crée les enregistrements backend nécessaires au développement.

Étape 3 : Créer la structure de l'application

Avec votre application enregistrée, générez la structure du projet :

ocp app init

Le CLI demande des détails supplémentaires :

• Name : Pré-rempli depuis l'enregistrement
• App ID : Pré-rempli depuis l'enregistrement
• Version : Commencez avec 1.0.0-dev.1 pour le développement
• Summary : Description brève comme « Envoie des notifications Slack pour les événements OCP »
• Support URL : Votre page de documentation ou de support
• Support Email : Courriel de contact pour les utilisateurs
• Category : Choisissez quelque chose d'approprié (évitez les catégories réservées comme Commerce Platform ou Content Management)
• Template : Sélectionnez « Empty Project » pour ce tutoriel

La création génère cette structure :

slack-notifier/
├── app.yml
├── package.json
├── tsconfig.json
├── src/
│   ├── functions/
│   ├── jobs/
│   └── schema/
└── node_modules/

Naviguez dans votre nouveau projet et installez les dépendances :

cd slack-notifier
npm install

Étape 4 : Définir le formulaire de paramètres

Les utilisateurs ont besoin d'un moyen de configurer votre application après l'installation. OCP gère ça via un formulaire de paramètres défini dans votre fichier app.yml. Ouvrez-le et ajoutez une section settings :

id: slack_notifier
name: Slack Notifier
version: 1.0.0-dev.1
summary: Sends Slack notifications for OCP events

settings:
  - id: slack_webhook_url
    type: string
    label: Slack Webhook URL
    description: The incoming webhook URL from your Slack workspace
    required: true
    sensitive: true
  - id: notification_channel
    type: string
    label: Channel Override
    description: Optional channel name to override the webhook default
    required: false
  - id: include_timestamp
    type: boolean
    label: Include Timestamp
    description: Add timestamp to notification messages
    default: true

Le paramètre sensitive: true indique à OCP de masquer ce champ dans les journaux et l'interface utilisateur. Utilisez toujours ceci pour les clés API, les jetons et les URL webhook.

Notre expérience montre que fournir des valeurs par défaut sensées et des descriptions claires dans les paramètres réduit considérablement les demandes de support. Les utilisateurs apprécient de savoir exactement ce que chaque champ fait sans avoir besoin de consulter une documentation externe.

Étape 5 : Créer la fonction de notification

Les fonctions sont le cœur des applications OCP : elles gèrent les requêtes entrantes et exécutent votre logique métier. Créez un nouveau fichier à src/functions/notify.ts :

import * as App from '@zaiusinc/app-sdk';

interface NotificationPayload {
  title: string;
  message: string;
  severity?: 'info' | 'warning' | 'error';
  metadata?: Record<string, string>;
}

export class Notify extends App.Function {
  public async perform(): Promise<App.Response> {
    // Get configuration from app settings
    const webhookUrl = this.app.settings.slack_webhook_url;
    const channelOverride = this.app.settings.notification_channel;
    const includeTimestamp = this.app.settings.include_timestamp;

    if (!webhookUrl) {
      this.logger.error('Slack webhook URL not configured');
      return new App.Response(500, {
        error: 'Slack webhook URL not configured'
      });
    }

    // Parse incoming request
    let payload: NotificationPayload;
    try {
      payload = this.request.body as NotificationPayload;
    } catch (err) {
      this.logger.error('Invalid request payload', { error: err });
      return new App.Response(400, {
        error: 'Invalid request payload'
      });
    }

    // Build Slack message
    const slackMessage = this.buildSlackMessage(
      payload,
      includeTimestamp,
      channelOverride
    );

    // Send to Slack
    try {
      const response = await fetch(webhookUrl, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(slackMessage)
      });

      if (!response.ok) {
        throw new Error(`Slack returned ${response.status}`);
      }

      this.logger.info('Notification sent successfully', {
        title: payload.title
      });

      return new App.Response(200, {
        success: true,
        message: 'Notification sent'
      });
    } catch (err) {
      this.logger.error('Failed to send Slack notification', { error: err });
      return new App.Response(500, {
        error: 'Failed to send notification'
      });
    }
  }

  private buildSlackMessage(
    payload: NotificationPayload,
    includeTimestamp: boolean,
    channelOverride?: string
  ) {
    const colorMap = {
      info: '#36a64f',
      warning: '#ff9800',
      error: '#dc3545'
    };

    const attachment: any = {
      color: colorMap[payload.severity || 'info'],
      title: payload.title,
      text: payload.message,
      fields: []
    };

    // Add metadata as fields
    if (payload.metadata) {
      for (const [key, value] of Object.entries(payload.metadata)) {
        attachment.fields.push({
          title: key,
          value: value,
          short: true
        });
      }
    }

    // Add timestamp if configured
    if (includeTimestamp) {
      attachment.ts = Math.floor(Date.now() / 1000);
    }

    const message: any = {
      attachments: [attachment]
    };

    if (channelOverride) {
      message.channel = channelOverride;
    }

    return message;
  }
}

Maintenant, enregistrez cette fonction dans votre app.yml :

functions:
  - id: notify
    entry_point: src/functions/notify.ts
    description: Receives notification requests and sends them to Slack

Étape 6 : Ajouter une tâche planifiée de vérification de santé

Les tâches (jobs) s'exécutent selon des horaires plutôt qu'en réponse à des requêtes HTTP. Elles sont utiles pour les synchronisations périodiques, les tâches de nettoyage ou les vérifications de santé. Créez src/jobs/health-check.ts :

import * as App from '@zaiusinc/app-sdk';

export class HealthCheck extends App.Job {
  public async perform(): Promise<void> {
    const webhookUrl = this.app.settings.slack_webhook_url;

    if (!webhookUrl) {
      this.logger.warn('Health check skipped: webhook not configured');
      return;
    }

    try {
      // Send a simple test message
      const response = await fetch(webhookUrl, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          text: '✅ OCP Slack Notifier health check: Connection verified'
        })
      });

      if (response.ok) {
        this.logger.info('Health check passed');
      } else {
        this.logger.error('Health check failed', {
          status: response.status
        });
      }
    } catch (err) {
      this.logger.error('Health check error', { error: err });
    }
  }
}

Enregistrez la tâche dans app.yml :

jobs:
  - id: health_check
    entry_point: src/jobs/health-check.ts
    description: Verifies Slack webhook connectivity
    schedule: 0 9 * * 1  # Every Monday at 9 AM

Étape 7 : Tester localement avec l'outil de développement OCP

L'outil de test local, lancé en décembre 2025, vous permet de tester votre application sans la déployer. Démarrez-le avec :

ocp dev

Cela lance une interface web locale où vous pouvez :

Tester le formulaire de paramètres

Naviguez vers l'onglet Settings pour voir exactement comment votre formulaire s'affiche. Entrez votre URL webhook Slack et sauvegardez. L'outil valide les champs obligatoires et gère le masquage des données sensibles.

Tester les fonctions

Allez dans l'onglet Functions, sélectionnez votre fonction notify et envoyez un payload de test :

{
  "title": "Test Notification",
  "message": "This is a test from the OCP local dev tool",
  "severity": "info",
  "metadata": {
    "Source": "Local Testing",
    "Environment": "Development"
  }
}

Cliquez sur Execute et vérifiez à la fois la réponse dans l'outil et votre canal Slack pour le message.

Tester les tâches

Passez à l'onglet Jobs et déclenchez manuellement la vérification de santé. Examinez les journaux d'exécution pour vérifier qu'elle s'est complétée avec succès.

Examiner les journaux

Le panneau Logs affiche la sortie détaillée de toutes les exécutions de fonctions et de tâches, incluant vos messages de journal personnalisés. C'est inestimable pour le débogage.

Étape 8 : Valider et préparer la publication

Une fois les tests locaux réussis, validez la configuration de votre application :

ocp app validate

Cela vérifie votre app.yml, la compilation TypeScript et les définitions de schéma. Corrigez toute erreur avant de poursuivre.

Ensuite, préparez le paquet distribuable :

ocp app prepare

Cela regroupe votre code, vos définitions de paramètres et vos métadonnées dans un format prêt pour le répertoire d'applications.

Étape 9 : Publier dans le répertoire d'applications

Publiez votre application avec :

ocp directory publish [email protected]

Cela téléverse votre application dans le répertoire d'applications. Puisque vous l'avez enregistrée comme privée, seul votre compte peut la voir initialement.

Étape 10 : Installer et configurer dans un compte OCP

Pour installer votre application dans un compte OCP spécifique, vous avez besoin de l'identifiant tracker du compte. Trouvez-le dans l'interface OCP sous les paramètres du compte, puis exécutez :

ocp directory install [email protected] YOUR_TRACKER_ID

Après l'installation :

• Ouvrez l'interface OCP et naviguez vers le répertoire d'applications
• Trouvez votre application Slack Notifier
• Cliquez sur Configure et entrez votre URL webhook Slack de production
• Sauvegardez les paramètres

Votre fonction est maintenant en ligne et accessible à une URL comme :

https://connect.optimizely.com/slack_notifier/notify/[installation-uuid]

Utilisez cette URL comme point de terminaison webhook dans d'autres systèmes pour déclencher des notifications Slack.

Erreurs courantes à éviter

Oublier de marquer les champs sensibles

Utilisez toujours sensitive: true pour les identifiants. On a constaté que les applications qui échouent à la revue de sécurité oublient souvent ce simple paramètre sur un ou deux champs. C'est facile à négliger mais critique pour protéger les données des utilisateurs.

Coder en dur la configuration

Ne mettez jamais de clés API ou de valeurs spécifiques à l'environnement directement dans le code. Tout ce qui est configurable devrait passer par le formulaire de paramètres. Ça semble évident, mais ça devient tentant lors du débogage.

Ignorer les réponses d'erreur

Vos fonctions devraient toujours retourner des codes de statut HTTP appropriés. Une fonction qui retourne 200 pour chaque requête rend le débogage impossible pour les utilisateurs et les systèmes externes.

Sauter les tests locaux

L'outil ocp dev existe pour une raison. Déployer du code non testé et déboguer via le répertoire d'applications prend beaucoup plus de temps que l'itération locale.

Utiliser des catégories réservées

Lors de l'enregistrement de votre application, évitez les catégories comme « Commerce Platform », « Content Management » ou « Loyalty & Rewards ». Celles-ci sont réservées aux intégrations spécifiques de produits Optimizely.

Ne pas gérer les paramètres manquants

Les utilisateurs pourraient installer votre application avant de la configurer. Vos fonctions devraient gérer élégamment les paramètres obligatoires manquants plutôt que de lancer des erreurs incompréhensibles.

Vérifier votre déploiement

Après l'installation, vérifiez que tout fonctionne :

Tester le point de terminaison de la fonction

Utilisez curl ou Postman pour envoyer une requête de test :

curl -X POST https://connect.optimizely.com/slack_notifier/notify/[your-uuid] \
  -H "Content-Type: application/json" \
  -d '{"title": "Production Test", "message": "Hello from production!", "severity": "info"}'

Vérifier Slack

Confirmez que le message apparaît dans votre canal configuré avec le formatage approprié.

Examiner les journaux dans OCP

Naviguez vers votre application dans l'interface OCP et vérifiez les journaux d'exécution pour confirmer le succès.

Déclencher la tâche planifiée

Exécutez manuellement la tâche de vérification de santé depuis l'interface OCP pour vérifier que les tâches planifiées fonctionnent correctement.

Passer en production

Quand vous êtes prêt pour une distribution plus large :

Incrémenter la version

Mettez à jour votre version dans app.yml vers un numéro de production comme 1.0.0, puis exécutez à nouveau validate, prepare et publish.

Liste publique

Changez la visibilité de votre application à public et soumettez-la pour révision. Optimizely complète généralement les révisions en 1 à 2 jours ouvrables.

Documentation

Créez une documentation utilisateur couvrant l'installation, la configuration et le dépannage. Liez-la depuis votre URL de support dans app.yml.

Conclusion

Vous avez maintenant une application OCP fonctionnelle qui démontre les patrons de base : configuration des paramètres, implémentation de fonctions, tâches planifiées et le flux de travail complet du développement au déploiement. À partir d'ici, vous pouvez vous aventurer dans des territoires plus complexes : ajouter des définitions de schéma pour le stockage de données, construire des flux de synchronisation en plusieurs étapes ou intégrer des produits Optimizely supplémentaires.

Les équipes avec lesquelles on travaille rapportent que la courbe d'apprentissage initiale avec OCP vient de la compréhension du cycle de vie et des commandes CLI plutôt que du codage en tant que tel. Une fois que vous avez construit une application, les suivantes suivent les mêmes patrons.

Créer des intégrations OCP personnalisées demande d'équilibrer les conventions de la plateforme Optimizely avec vos exigences métier spécifiques. Si vous planifiez une application OCP pour usage en production, que ce soit un connecteur de synchronisation de données, une intégration d'outil Opal ou quelque chose de plus spécialisé, on peut vous aider à concevoir l'architecture et éviter les pièges courants qui ralentissent le développement.