<iframe>.
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.Récupérer les Informations d'Intégration
Avant de pouvoir afficher l’Le
<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 :- Détails de l’Outil: Le schéma, le nom, la description, etc.
- Jeton d’Accès: Un JSON Web Token (JWT) de courte durée que l’
<iframe>intégré utilisera pour s’authentifier.
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êteexternal_user_id à l’endpoint /embed-info.cURL
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.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
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.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 avecexternal_user_idpour 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 surtrue, 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 surtrue, un sélecteur de langue sera affiché, permettant aux utilisateurs de changer la langue d’affichage.
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.

