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, qui peut ensuite transmettre le access_token de courte durée et les détails de l’outil au client.
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.
  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 obtenu depuis l’endpoint /tools/{tool_id}/embed-info. C’est la méthode recommandée pour l’authentification côté client.
  • 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
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.