> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ubik-agent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Guide : Intégrer UBIK avec un iframe

> Apprenez à intégrer en toute sécurité l'interface utilisateur d'un outil UBIK directement dans votre application web pour une expérience utilisateur transparente.

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>`.

<Steps>
  <Step title="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.

    <Card title="Accéder aux paramètres de la clé API" icon="key" href="https://app.ubik-agent.com/user/security" />

    <Note>
      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.
    </Note>
  </Step>

  <Step title="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.

    <CodeGroup title="GET /tools/{tool_id}/embed-info">
      ```bash cURL theme={null}
      curl -X GET "https://app.ubik-agent.com/api/v1/tools/VOTRE_ID_OUTIL/embed-info" \
           -H "X-API-KEY: VOTRE_CLE_API"
      ```

      ```python Python (Côté Serveur) theme={null}
      import requests

      api_key = "VOTRE_CLE_API"
      tool_id = "VOTRE_ID_OUTIL"

      headers = {"X-API-KEY": api_key}

      # Cet appel serait typiquement effectué depuis votre serveur, qui transmettrait
      # ensuite les informations d'intégration à votre client frontend.
      response = requests.get(
          f"https://app.ubik-agent.com/api/v1/tools/{tool_id}/embed-info",
          headers=headers
      )

      if response.status_code == 200:
          embed_info = response.json()
          print(embed_info)
          # Transmettez ces informations à votre frontend
      else:
          print(f"Erreur: {response.status_code}", response.text)
      ```

      ```javascript JavaScript (Côté Client) theme={null}
      // Cette fonction appellerait typiquement un endpoint sur VOTRE serveur,
      // qui effectuerait ensuite l'appel sécurisé à l'API UBIK avec votre clé API secrète.

      async function fetchEmbedInfoFromServer(toolId) {
        try {
          // Exemple : un endpoint sur votre propre backend
          const response = await fetch(`/api/get-tool-embed-info?toolId=${toolId}`);
          if (!response.ok) {
            throw new Error(`Erreur HTTP: ${response.status}`);
          }
          const embedInfo = await response.json();
          console.log(embedInfo);
          // Utilisez ces données pour afficher l'iframe
          return embedInfo;
        } catch (error) {
          console.error('Erreur lors de la récupération des infos d''intégration:', error);
        }
      }
      ```
    </CodeGroup>

    <Tip icon="shield-check">
      **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.
    </Tip>

    ### 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`.

    ```bash cURL theme={null}
    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.

    <Note>
      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é](/fr/guides/authentication) pour les détails.
    </Note>

    <Warning>
      **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.
    </Warning>
  </Step>

  <Step title="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 :

    ```jsx Exemple React theme={null}
    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;
    ```

    <Note>
      **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\\\`;\`](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.
    </Note>
  </Step>

  <Step title="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
    ```
  </Step>

  <Step title="Intégrer une Exécution Spécifique">
    En plus d'intégrer le formulaire de saisie de l'outil, vous pouvez également intégrer une **exécution existante** spécifique. C'est idéal pour partager des résultats avec des utilisateurs ou leur permettre de surveiller une tâche de longue durée initiée via l'API.

    Le processus est identique à l'intégration d'un outil, mais vous utilisez un chemin d'URL différent.

    **Format de l'URL :**
    `https://app.ubik-agent.com/embed/execution/VOTRE_ID_EXECUTION?jwt=VOTRE_JWT`

    **Ou avec une clé API (Rendu côté serveur uniquement) :**
    `https://app.ubik-agent.com/embed/execution/VOTRE_ID_EXECUTION?apiKey=VOTRE_CLE_API`

    **Cas d'utilisation :**

    * **Surveillance :** Rediriger un utilisateur vers cette vue après avoir démarré une tâche via l'API.
    * **Partage :** Permettre aux utilisateurs de voir les résultats d'une tâche terminée.

    La vue intégrée gérera automatiquement :

    * La connexion au flux d'événements en temps réel.
    * L'affichage de la progression et des étapes intermédiaires.
    * Le rendu des résultats finaux (texte, images, fichiers) une fois terminé.
  </Step>

  <Step title="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.

    Les événements principaux à surveiller sont :

    * `tool_update` : Progression générale.
    * `tool_partial_update` : Streaming de contenu.
    * `tool_input_required` : Demande d'interaction utilisateur.
    * `tool_end` (ou `final_result`) : Fin de l'exécution avec les résultats.
    * `error` : Erreur d'exécution.

    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](/fr/guides/streaming-results)**.
  </Step>
</Steps>

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.