Personnaliser l’interface du widget
data-* de la balise de chargement. Vous pouvez ainsi adapter l’apparence sans modifier le code du widget. Son Shadow DOM isole ses éléments internes des sélecteurs CSS habituels du site.Comment fonctionne la personnalisation ?
Le widget externe REDA AI s’affiche dans un Shadow DOM. Les sélecteurs CSS de votre page n’atteignent pas directement ses éléments internes. Utilisez les attributs data-* de la balise <script> pour les options prises en charge ; certaines propriétés héritées, comme les polices, restent liées à l’environnement de la page.
Ajouter une règle CSS visant une classe interne du widget dans la feuille de style du site ne permet pas de la personnaliser directement. Utilisez les attributs data-* documentés ci-dessous et testez le résultat dans le thème de votre site.
Réglages de la définition de l’agent
Le message d’accueil et l’image peuvent provenir de l’agent dans Salesforce. Le titre et l’ouverture du panneau possèdent aussi des options d’intégration distinctes :
| Réglage | Où le configurer | Description |
|---|---|---|
| Message d’accueil | Définition de l’agent → Message de bienvenue externe | Message ajouté à la conversation lors de son initialisation. |
| Image de mascotte | Définition de l’agent → Image de mascotte | Avatar utilisé par le widget lorsque sa propre configuration n’en fournit pas déjà un. |
| Nom et titre affichés | Définition de l’agent → Nom d’affichage ; balise → data-title | Pour le widget externe décrit ici, renseignez data-title afin de définir le titre de l’en-tête et la valeur de {title} dans l’accueil. Ne supposez pas que le nom de l’agent remplace automatiquement cette option. |
| Accueil proactif et ouverture du panneau | Définition de l’agent → Démarrage sur le chargement ; balise → data-open-on-load | Démarrage sur le chargement concerne l’accueil proactif du composant sur une page d’enregistrement. Pour ouvrir le widget externe au chargement de la page, utilisez data-open-on-load. L’ouverture du panneau n’est pas une demande d’analyse automatique d’un enregistrement. |
Attributs obligatoires
| Attribut | Description |
|---|---|
data-api-key |
Clé API externe publique de votre agent REDA AI. |
data-endpoint |
URL du point d’accès de l’API du chatbot, correspondant à votre site Salesforce. |
Style du bouton de lancement
Le visiteur ouvre le chatbot avec ce bouton flottant. Il peut être rond, par défaut, ou allongé avec un texte.
| Attribut | Valeurs | Valeur par défaut | Description |
|---|---|---|---|
data-bubble-style |
circle | pill |
circle |
Forme du bouton flottant. |
data-bubble-label |
Texte libre | Aucun | Texte du bouton allongé, par exemple « Contacter l’assistance ». Renseignez-le avec le style pill. |
data-bubble-size |
Nombre (px) | 60 |
Diamètre du bouton rond ; cette dimension ne règle pas le bouton allongé. |
data-bubble-style="pill"
data-bubble-label="Ask REDA AI"Cet exemple affiche un bouton arrondi avec une icône et le texte « Ask REDA AI ». Remplacez ce texte par « Demander à REDA AI » pour votre site français. Une image de mascotte configurée remplace l’icône par défaut.
Style de l’en-tête
L’en-tête apparaît au sommet du panneau. Choisissez une présentation colorée ou minimale, puis vérifiez le contraste dans le thème retenu.
| Attribut | Valeurs | Valeur par défaut | Description |
|---|---|---|---|
data-header-style |
colored | minimal |
colored |
Style de fond de l’en-tête. |
data-header-bg |
Couleur hexadécimale | Couleur principale | Couleur du fond de l’en-tête, pour le style colored uniquement. |
data-header-style="minimal"Le style minimal utilise une présentation sobre avec un texte contrasté et une bordure discrète. L’attribut data-header-bg ne règle pas son fond.
Zone d’accueil
La zone d’accueil présente un avatar ou une icône, un titre et un texte secondaire facultatif. Elle est distincte du message de bienvenue ajouté à la conversation.
| Attribut | Valeurs | Valeur par défaut | Description |
|---|---|---|---|
data-show-welcome-hero |
true | false |
true |
Affiche ou masque la zone d’accueil. |
data-welcome-heading |
Texte libre | « How can [titre du widget] help? » | Titre d’accueil. La variable {title} reprend le titre du widget. Exemple français : « Comment {title} peut-il vous aider ? ». |
data-welcome-subtext |
Texte libre | Aucun | Texte facultatif sous le titre d’accueil. |
data-welcome-heading="How can {title} help?"
data-welcome-subtext="Ask me anything about your properties"La variable {title} est remplacée par le titre configuré du widget et peut reprendre la couleur principale. Une image de mascotte configurée apparaît dans l’avatar d’accueil. Traduisez les valeurs textuelles de l’exemple selon votre public.
Couleurs
| Attribut | Valeur par défaut | Description |
|---|---|---|
data-primary-color |
#0176D3 |
Couleur principale : bouton, en-tête coloré, messages utilisateur et éléments d’accentuation. |
data-header-bg |
Couleur principale | Fond de l’en-tête pour le style colored uniquement. |
data-user-msg-bg |
Couleur principale | Fond des messages de l’utilisateur. |
data-user-msg-text-color |
#ffffff |
Couleur du texte des messages de l’utilisateur. |
data-bg-color |
Selon le thème | Fond du panneau. |
data-bg-secondary-color |
Selon le thème | Fond des messages de l’assistant et de l’indicateur de saisie. |
data-text-color |
Selon le thème | Couleur principale du texte. |
data-border-color |
Selon le thème | Couleur des bordures et séparateurs. |
data-primary-color="#1B5E20"
data-user-msg-bg="#2E7D32"
data-bg-color="#FAFAFA"Cet exemple utilise deux nuances de vert pour les éléments principaux et les messages utilisateur, avec un fond de panneau gris clair. Vérifiez la lisibilité de chaque combinaison de couleurs.
Disposition et position
| Attribut | Valeurs / type | Valeur par défaut | Description |
|---|---|---|---|
data-display-mode |
bubble | docked-right | docked-left |
bubble |
Ouverture sous forme de carte flottante ou de panneau latéral pleine hauteur. Consultez Mode d’affichage ci-dessous. |
data-position |
bottom-right | bottom-left |
bottom-right |
Coin où apparaît le bouton de lancement. Ce réglage est indépendant du mode d’affichage : le bouton peut rester à gauche tandis que le panneau s’ouvre à droite. |
data-panel-width |
Nombre (px) | 400 |
Largeur de la carte flottante. Mode bubble uniquement : utilisez data-dock-width pour un panneau latéral. |
data-panel-height |
Nombre (px) | 550 |
Hauteur de la carte flottante. Mode bubble uniquement : le panneau latéral utilise la hauteur disponible. |
data-dock-width |
Nombre en pixels ou largeur CSS, par exemple 30vw. |
Adaptée à l’écran | Largeur du panneau latéral, uniquement pour les modes docked. Sans cette option, sa largeur s’adapte à l’écran selon les bornes prévues par le widget. |
data-border-radius |
Nombre (px) | 12 |
Arrondi des angles du panneau et du bouton, selon leur présentation. |
data-z-index |
Nombre | 999999 |
Ordre de superposition CSS du widget. Ajustez-le si un autre élément le recouvre, sans masquer les commandes essentielles du site. |
data-title |
Texte | AI Assistant |
Titre affiché dans l’en-tête ; remplacez la valeur anglaise par le nom souhaité. |
Mode d’affichage
Le mode d’affichage règle l’ouverture du panneau. Le bouton de lancement reste disponible dans les trois modes ; le visiteur l’utilise pour afficher l’assistant.
| Mode | Ce que voit le visiteur | Usage adapté |
|---|---|---|
bubble(par défaut) |
Une carte flottante s’ouvre au-dessus du bouton, en laissant une grande partie de la page visible. | Sites de présentation ou de contenu, lorsque la conversation reste une aide complémentaire. |
docked-right |
Un panneau pleine hauteur apparaît depuis le bord droit. | Conversations longues, comparaisons et consultation des résultats pendant la navigation. |
docked-left |
Le même panneau pleine hauteur s’ouvre depuis le bord gauche. | Sites dont les commandes ou le contenu principal occupent déjà le côté droit. |
Un panneau latéral offre davantage de place pour les cartes, les photos ou les comparaisons. Vérifiez qu’il laisse accessibles les commandes de votre site.
data-display-mode="docked-right"
data-dock-width="420"data-position règle le coin du bouton. Sans attribut data-display-mode, le widget utilise le mode bubble par défaut.data-panel-width et data-panel-height concernent la carte flottante et sont ignorés dans les modes docked. L’attribut data-dock-width concerne le panneau latéral. Si une dimension semble sans effet, vérifiez le mode actif. Sans data-dock-width, le panneau utilise sa largeur adaptative.Thème
| Attribut | Valeurs | Valeur par défaut | Description |
|---|---|---|---|
data-theme |
light | dark |
light |
Thème clair ou sombre. Le thème sombre utilise des fonds foncés et du texte clair ; contrôlez aussi les couleurs personnalisées que vous avez définies. |
Typographie
| Attribut | Type | Valeur par défaut | Description |
|---|---|---|---|
data-font-family |
Liste de polices CSS | Polices système | Police personnalisée, par exemple 'Poppins', sans-serif. Elle doit être chargée par la page et autorisée par sa configuration réseau. |
data-font-size |
Nombre (px) | 14 |
Taille de base du texte des messages et de la zone de saisie. |
Comportement sur mobile
| Attribut | Valeurs / type | Valeur par défaut | Description |
|---|---|---|---|
data-mobile-breakpoint |
Nombre (px) | 640 |
Largeur d’écran sous laquelle le comportement mobile est activé. |
data-mobile-fullscreen |
true | false |
true |
Lorsque cette option est activée, le panneau utilise le plein écran sur les petits appareils. |
Comportement
| Attribut | Valeurs / type | Valeur par défaut | Description |
|---|---|---|---|
data-open-on-load |
true | false |
false |
Ouvre automatiquement le panneau au chargement de la page. |
data-enable-voice |
true | false |
true |
Affiche le bouton de dictée dans les navigateurs compatibles. La valeur false le masque. La disponibilité dépend aussi des autorisations et du service de reconnaissance du navigateur. Consultez Saisie vocale. |
data-typing-speed |
Nombre | 25 |
Vitesse de révélation du texte, en mots par seconde. Ce réglage ne modifie pas le temps de traitement du modèle. |
data-cache-ttl-minutes |
Nombre (minimum 1) | 5 |
Durée de la tranche de cache utilisée pour l’URL du script au prochain chargement du chargeur, en minutes. Ce n’est pas un rafraîchissement automatique périodique d’une page déjà ouverte. |
Textes et internationalisation
Les attributs suivants remplacent les textes correspondants du widget. La colonne des valeurs par défaut conserve les chaînes anglaises réellement fournies : renseignez vos propres traductions françaises. Cela ne traduit pas automatiquement les réponses de l’agent ni tous les messages renvoyés par le serveur ; vérifiez le parcours complet et la langue configurée de l’agent.
| Attribut | Valeur par défaut | Description |
|---|---|---|
data-input-placeholder |
Type a message... | Exemple de saisie. Valeur française possible : « Saisissez un message… ». |
data-aria-open |
Open chat | Libellé accessible du bouton fermé : « Ouvrir la conversation ». |
data-aria-close |
Close chat | Libellé accessible du bouton ouvert : « Fermer la conversation ». |
data-aria-send |
Send message | Libellé accessible du bouton d’envoi : « Envoyer le message ». |
data-aria-typing |
Assistant is typing | Annonce accessible de saisie : « L’assistant prépare sa réponse ». |
data-error-rate-limited |
Please wait a moment before sending again. | Message de limitation de débit : « Patientez un instant avant de réessayer. ». |
data-error-max-messages |
This conversation has reached its limit. Please start a new one. | Message de limite de conversation : « Cette conversation a atteint sa limite. Commencez-en une nouvelle. ». |
data-error-session-expired |
Session expired. Reconnecting... | Message d’expiration : « Session expirée. Reconnexion en cours… ». |
data-error-generic |
Something went wrong. Please try again. | Erreur générale : « Une erreur s’est produite. Veuillez réessayer. ». |
data-error-connect |
Unable to connect. Please refresh and try again. | Échec de connexion : « Connexion impossible. Actualisez la page et réessayez. ». |
Exemples complets
Intégration minimale : valeurs par défaut
<script
src="https://<org>.my.salesforce-sites.com/chat/resource/redaai__REDAAILoader"
data-api-key="your-api-key"
data-endpoint="https://<org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1">
</script>Utilise le bouton rond, l’en-tête coloré, la zone d’accueil, le thème clair et la position en bas à droite. Remplacez les exemples de domaine, de chemin et de clé par les valeurs de votre installation.
Bouton allongé et en-tête minimal
<script
src="https://<org>.my.salesforce-sites.com/chat/resource/redaai__REDAAILoader"
data-api-key="your-api-key"
data-endpoint="https://<org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1"
data-bubble-style="pill"
data-bubble-label="Ask REDA AI"
data-header-style="minimal"
data-welcome-heading="How can {title} help?"
data-welcome-subtext="Ask me anything about your properties">
</script>Panneau latéral ancré
<script
src="https://<org>.my.salesforce-sites.com/chat/resource/redaai__REDAAILoader"
data-api-key="your-api-key"
data-endpoint="https://<org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1"
data-display-mode="docked-right"
data-dock-width="420"
data-bubble-style="pill"
data-bubble-label="Ask REDA AI"
data-welcome-subtext="Ask me anything about your properties">
</script>Le panneau apparaît à droite lorsque le visiteur utilise le bouton. Supprimez data-dock-width pour employer la largeur adaptative ou choisissez docked-left pour l’autre côté. Les attributs data-panel-width et data-panel-height ne règlent pas ce mode ; data-dock-width en définit la largeur.
Couleurs de marque et thème sombre
<script
src="https://<org>.my.salesforce-sites.com/chat/resource/redaai__REDAAILoader"
data-api-key="your-api-key"
data-endpoint="https://<org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1"
data-theme="dark"
data-primary-color="#6C63FF"
data-title="Support Agent"
data-position="bottom-left">
</script>En-tête coloré sans zone d’accueil
<script
src="https://<org>.my.salesforce-sites.com/chat/resource/redaai__REDAAILoader"
data-api-key="your-api-key"
data-endpoint="https://<org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1"
data-bubble-style="pill"
data-bubble-label="Chat with us"
data-show-welcome-hero="false"
data-primary-color="#D32F2F">
</script>Internationalisation : exemple en espagnol
<script
src="https://<org>.my.salesforce-sites.com/chat/resource/redaai__REDAAILoader"
data-api-key="your-api-key"
data-endpoint="https://<org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1"
data-title="Asistente"
data-bubble-style="pill"
data-bubble-label="Pregunte"
data-input-placeholder="Escribe un mensaje..."
data-welcome-heading="¿Cómo puede {title} ayudarte?"
data-welcome-subtext="Pregúntame sobre tu cuenta"
data-aria-open="Abrir chat"
data-aria-close="Cerrar chat"
data-aria-send="Enviar mensaje"
data-error-generic="Algo salió mal. Inténtalo de nuevo.">
</script>Tester les personnalisations
- Ajoutez ou modifiez les attributs
data-*de la balise d’intégration. - Actualisez la page. Un rechargement forcé avec Ctrl+Maj+R ou Cmd+Maj+R peut aider à contourner le cache du navigateur.
- Vérifiez l’apparence du bouton, de l’en-tête et de l’accueil.
- Testez sur des largeurs d’ordinateur, de tablette et de téléphone.
- Testez dans les navigateurs pris en charge par votre site, notamment Chrome, Firefox, Safari et Edge.
- Envoyez un message de test et vérifiez la réponse, les erreurs et les textes accessibles dans la langue attendue.
Au chargement, le chargeur ajoute à l’URL du script un identifiant calculé par tranches de cinq minutes, réglables avec data-cache-ttl-minutes. Il ne recharge pas automatiquement le widget toutes les cinq minutes sur une page restée ouverte. Si un changement n’apparaît pas, rechargez la page et vérifiez aussi les caches de votre site.
Questions fréquentes
Les sélecteurs CSS de votre site ne ciblent pas directement les éléments internes du Shadow DOM. Utilisez les attributs data-* pour les personnalisations prévues et testez les propriétés héritées, comme la police, dans votre environnement.
Chargez la police sur votre site, puis renseignez data-font-family="'Your Font', sans-serif" en remplaçant Your Font par son nom. Le navigateur doit pouvoir charger cette ressource. Vérifiez la police de repli et le contraste sur les différents appareils.
Une image carrée en PNG avec transparence convient à de nombreux avatars ; JPEG peut aussi être utilisé. Une définition de 200 × 200 pixels constitue un point de départ, pas une exigence du champ. Configurez Image de mascotte sur l’agent, puis vérifiez son chargement comme visiteur et sa lisibilité aux différentes tailles.
Renseignez Message de bienvenue externe sur la définition de l’agent. Le titre et le texte secondaire de la zone d’accueil sont distincts : ils utilisent data-welcome-heading et data-welcome-subtext dans la balise.
Chargez sa balise uniquement sur les pages concernées. Dans une application monopage, vérifiez aussi son cycle de vie : un widget déjà créé peut rester présent après un changement de route.
Le style colored utilise la couleur principale ou celle de l’en-tête. Le style minimal adopte une présentation sobre adaptée au thème. Dans ce second mode, data-header-bg n’est pas utilisé pour le fond de l’en-tête.
Étapes suivantes
Consultez Configurer le widget externe pour son installation ou Configurer un agent communautaire pour un portail Experience Cloud.