@ourlu/assistant-sdk

SDK JavaScript pour intégrer le chatbot IA Ourlu sur les sites web de collectivités.

Installation

Copier-coller (recommandé)

Ajoutez ce snippet avant la balise </body> de votre site :

<script
  src="https://occe.ourlu.fr/v1/widget/runtime/loader.v1.js"
  data-tenant-id="votre-identifiant-mairie"
  data-widget-key="wpk_votre_cle_publique"
  data-api-base-url="https://occe.ourlu.fr"
  async
></script>

Le chatbot apparaît automatiquement en bas à droite de votre site.

npm (usage programmatique)

npm i @ourlu/assistant-sdk

import { bootstrapWidgetRuntime } from '@ourlu/assistant-sdk';

bootstrapWidgetRuntime({
  loaderUrl: 'https://occe.ourlu.fr/v1/widget/runtime/loader.v1.js'
});

Configuration

| Attribut | Requis | Description | |----------|--------|-------------| | data-tenant-id | ✅ | Identifiant de votre collectivité | | data-widget-key | ✅ | Clé publique du widget (fournie dans l'espace admin) | | data-api-base-url | ✅ | URL de la plateforme (https://occe.ourlu.fr) | | data-turnstile-site-key | ❌ | Clé Cloudflare Turnstile pour protection anti-bot |

Le thème (couleurs, mascotte, position, textes) est géré automatiquement depuis votre espace d'administration Ourlu. Aucune modification du code d'intégration n'est nécessaire après un changement de design.

Compatibilité

CMS & plateformes

WordPress, Drupal, SPIP, Joomla, TYPO3, Wix, Squarespace, Webflow, Shopify, et tout site acceptant un tag <script>.

Frameworks JavaScript

React, Vue, Svelte, Angular, Next.js, Nuxt, Astro, Remix, SvelteKit.

Sites statiques

HTML pur, Jekyll, Hugo, Eleventy, Cloudflare Pages, Netlify, Vercel, GitHub Pages.

Navigateurs supportés

• Chrome 66+
• Firefox 60+
• Safari 12+
• Edge 79+
• Mobile (iOS Safari, Chrome Android)

Fonctionnalités

• 💬 Chat textuel avec assistant IA en temps réel (streaming SSE)
• 🎙️ Entrée vocale avec transcription automatique
• 🎨 Thème personnalisable (couleurs, position, mascotte)
• 🌓 Mode sombre automatique (suit les préférences système)
• 🛡️ Protection anti-bot Cloudflare Turnstile (optionnelle)
• 🔒 Authentification JWT automatique
• ♿ Accessible (navigation clavier, échappement pour fermer)
• 📱 Responsive (mobile et desktop)

Protection anti-bot (optionnelle)

Pour activer Cloudflare Turnstile :

<script
  src="https://occe.ourlu.fr/v1/widget/runtime/loader.v1.js"
  data-tenant-id="votre-mairie"
  data-widget-key="wpk_..."
  data-api-base-url="https://occe.ourlu.fr"
  data-turnstile-site-key="0x4AAAAAAA..."
  async
></script>

Le captcha est invisible dans 99% des cas. Sans la clé Turnstile, le chatbot fonctionne normalement sans protection anti-bot.

API publique (ESM)

Pour une intégration programmatique avancée :

import {
  bootstrapWidgetRuntime,
  mountWidgetFromScript,
  sdkVersion
} from '@ourlu/assistant-sdk';

| Export | Description | |--------|-------------| | bootstrapWidgetRuntime(options) | Charge et initialise le widget | | mountWidgetFromScript(scriptTag) | Monte le widget depuis un élément script existant | | sdkVersion | Version du SDK ("v1") |

Options bootstrapWidgetRuntime

| Option | Description | Défaut | |--------|-------------|--------| | loaderUrl | URL du loader (résout automatiquement UI + engine) | — | | uiUrl | URL explicite du runtime UI | Auto | | engineUrl | URL explicite du runtime engine | Auto | | timeoutMs | Timeout de chargement en ms | 8000 |

Sécurité & RGPD

• Aucun cookie tiers installé
• Anonymisation native des données personnelles (PII masking)
• Compatible Content Security Policy (CSP) stricte
• Option auto-hébergement des fichiers JS
• Option reverse-proxy pour anonymisation IP

Support

• Documentation : espace admin Ourlu > Intégration
• Contact technique : [email protected]

Licence

Propriétaire — Ourlu SAS. Usage réservé aux collectivités clientes.