Passer au contenu principal
L’intégration des outils UBIK dans votre propre application offre un moyen puissant d’étendre les capacités de votre produit. Ce guide vous guidera à travers le processus d’intégration sécurisée d’un outil à l’aide d’un <iframe>.
1

Configurer les Origines Autorisées

Pour empêcher les domaines non autorisés d’intégrer vos outils, vous devez d’abord configurer une liste d’Origines Autorisées pour votre clé API. C’est une étape de sécurité essentielle. Une “origine” est la combinaison d’un protocole, d’un domaine et d’un port (par exemple, https://votreapp.com).Vous pouvez définir les origines autorisées pour vos clés API sur la page des paramètres de votre compte dans le tableau de bord UBIK.

Accéder aux paramètres de la clé API

Pour le développement local, vous pouvez ajouter des origines comme http://localhost:3000. Pour la production, assurez-vous de n’ajouter que les domaines où votre application est hébergée.
2

Récupérer les Informations d'Intégration

Avant de pouvoir afficher l’<iframe>, le frontend de votre application doit récupérer les détails d’intégration depuis l’API UBIK. Pour ce faire, effectuez une requête GET vers l’endpoint /tools/{tool_id}/embed-info.Cet endpoint fournit deux informations cruciales :
  1. Détails de l’Outil: Le schéma, le nom, la description, etc.
  2. Jeton d’Accès: Un JSON Web Token (JWT) de courte durée que l’<iframe> intégré utilisera pour s’authentifier.
curl -X GET "https://app.ubik-agent.com/api/v1/tools/VOTRE_ID_OUTIL/embed-info" \
     -H "X-API-KEY: VOTRE_CLE_API"
Bonne Pratique de Sécurité: Votre clé API secrète UBIK ne doit jamais être exposée dans votre application frontend. L’appel à /embed-info doit être effectué depuis votre serveur backend.

Multi-Tenancy & Isolation des Utilisateurs

Si votre application sert plusieurs utilisateurs, vous souhaitez probablement vous assurer qu’un utilisateur ne peut pas voir les données d’un autre dans l’outil intégré.Vous pouvez y parvenir en passant le paramètre de requête external_user_id à l’endpoint /embed-info.
cURL
curl -X GET "https://app.ubik-agent.com/api/v1/tools/VOTRE_ID_OUTIL/embed-info?external_user_id=user_456" \
     -H "X-API-KEY: VOTRE_CLE_API"
Le access_token retourné sera automatiquement restreint à user_456. Lorsque vous passez ce jeton à l’iframe, toutes les actions (comme la sauvegarde de l’état ou l’accès aux fichiers) seront strictement isolées pour cet utilisateur.
Alternativement, vous pouvez générer des jetons scopés utilisateur via l’endpoint générique /auth/token. Voir le Guide Authentification & Sécurité pour les détails.
Important : Si vous ne fournissez pas d’external_user_id lors de la génération du jeton, l’outil intégré aura un accès complet à toutes les ressources (documents, exécutions précédentes) associées à votre clé API. Cela accorde effectivement des privilèges “Admin” dans l’iframe et ne devrait jamais être utilisé pour des intégrations destinées aux utilisateurs finaux.
3

Afficher l'iframe

Une fois que votre frontend dispose des informations d’intégration, vous pouvez construire l’URL de l’<iframe> et l’afficher. Le access_token de l’endpoint embed-info doit être passé comme paramètre de requête jwt à l’URL source de l’iframe.Voici un exemple simplifié avec React :
Exemple React
import React, { useState, useEffect } from 'react';

const EmbeddedTool = ({ toolId }) => {
  const [embedInfo, setEmbedInfo] = useState(null);

  useEffect(() => {
    // Dans une vraie application, ceci récupérerait les données depuis votre backend
    const fetchEmbedInfo = async () => {
      try {
        const response = await fetch(`/api/get-tool-embed-info?toolId=${toolId}`);
        const data = await response.json();
        setEmbedInfo(data);
      } catch (error) {
        console.error("Échec de la récupération des informations d'intégration:", error);
      }
    };

    fetchEmbedInfo();
  }, [toolId]);

  if (!embedInfo) {
    return <div>Chargement de l'outil...</div>;
  }

  // Ajoutez le jeton d'accès en tant que paramètre de requête.
  // Note : Si vous avez généré un jeton scopé utilisateur via /auth/token, utilisez-le ici à la place.
  const iframeSrc = `https://app.ubik-agent.com/embed/tools/${embedInfo.id}?jwt=${embedInfo.access_token}`;

  return (
    <iframe
      src={iframeSrc}
      title={embedInfo.name}
      width="100%"
      height="600px"
      frameBorder="0"
    />
  );
};

export default EmbeddedTool;
Utiliser une clé API directe : Pour les scénarios où vous préférez ne pas utiliser l’endpoint /embed-info (par exemple, le rendu côté serveur), vous pouvez également vous authentifier en passant votre clé API UBIK directement en tant que paramètre de requête apiKey.const iframeSrc = \https://app.ubik-agent.com/embed/tools/VOTRE_ID_OUTIL?apiKey=VOTRE_CLE_API\`;`Cependant, pour les applications côté client, il est fortement recommandé d’utiliser le access_token de courte durée pour éviter d’exposer votre clé API secrète.
4

Personnaliser l'Outil Intégré

Vous pouvez personnaliser l’apparence et le comportement de l’outil intégré en ajoutant des paramètres de requête à l’URL source de l’<iframe>.Voici une liste des paramètres disponibles :
  • jwt (string) : Un JSON Web Token de courte durée. Utilisez celui de /tools/{tool_id}/embed-info (optionnellement avec external_user_id pour l’isolation).
  • apiKey (string) : Votre clé API UBIK. Elle peut être utilisée pour l’authentification à la place d’un JWT, mais elle est moins sécurisée pour les applications côté client car elle peut exposer votre clé secrète.
  • theme (‘light’ | ‘dark’) : Définit le thème de couleur par défaut pour l’interface de l’outil. S’il n’est pas fourni, il s’adapte à la préférence système de l’utilisateur.
  • showThemeToggle (boolean) : Si défini sur true, un sélecteur de thème sera affiché dans l’en-tête de l’outil, permettant aux utilisateurs de basculer entre le mode clair et le mode sombre.
  • showLangToggle (boolean) : Si défini sur true, un sélecteur de langue sera affiché, permettant aux utilisateurs de changer la langue d’affichage.
Exemple d’URL avec personnalisation :
https://app.ubik-agent.com/embed/tools/VOTRE_ID_OUTIL?jwt=VOTRE_JWT&theme=dark&showThemeToggle=true
5

Gestion des Événements (Avancé)

L’iframe intégré gère tous les événements en temps réel, la gestion de l’état et les interactions utilisateur en interne. Vous n’avez pas besoin d’écrire de code supplémentaire pour gérer la progression ou les résultats de l’outil.Cependant, si vous avez besoin de construire une interface entièrement personnalisée qui réagit aux événements de l’outil par programmation (par exemple, pour une intégration profonde dans votre propre framework UI), vous devriez utiliser l’API directement au lieu de l’iframe.Pour plus de détails sur la consommation du flux d’événements brut, veuillez consulter le guide Obtenir des Résultats en Temps Réel avec SSE.
En suivant ces étapes, vous pouvez intégrer en toute sécurité les puissants outils d’UBIK directement dans votre application, créant une expérience transparente et intégrée pour vos utilisateurs.