Événements (Relay)

Réagissez dans le navigateur lorsque vos clients interagissent avec le devis.

La passerelle de messages

L’iframe de Cord Elements est conçue pour ne jamais isoler votre site web de ce qui se passe à l’intérieur. Grâce à une passerelle bidirectionnelle via window.postMessage, Cord relaie (« relay ») les événements de la carte directement vers votre environnement window parent.

C’est particulièrement utile pour déclencher des pixels d’analyse (comme Meta Pixel ou Google Analytics), lancer une animation de confettis lorsqu’une proposition est approuvée, ou rediriger l’utilisateur vers une page de remerciement après un paiement réussi.

Écouter les événements

Vous pouvez écouter les événements de façon native en attachant un addEventListener au nœud DOM de l’élément intégré :

const container = document.querySelector('[data-cord-token]');

container.addEventListener('cord:approved', (event) => {
  console.log('The quote was approved!');
  console.log('Approved by:', event.detail.signed_by);
});

Dictionnaire des événements

Tous les événements portent le préfixe cord: pour éviter les collisions de noms avec d’autres bibliothèques. Le detail de chaque événement inclut toujours token (le jeton public du devis) et folio (par ex. "COT-0148"), en plus des champs propres à chaque événement listés ci-dessous.

Cycle de vie du composant

cord:ready : déclenché à l’instant précis où le SDK termine le rendu du contenu, le calcul de la hauteur finale et le chargement des polices.
cord:resize : émis en continu chaque fois que la hauteur de l’iframe change (utile uniquement si vous écrivez votre propre conteneur et n’utilisez pas embed.js).
cord:viewed : déclenché en même temps que cord:ready, dès que le devis termine son rendu dans l’iframe — c’est le signal que le contenu est désormais visible pour votre page hôte. L’enregistrement officiel en base de données indiquant que le client a consulté le devis passe par un mécanisme interne distinct, qui exige que l’onglet soit réellement visible (afin de ne pas compter comme « consultation » l’aperçu du commercial sur son propre lien) ; ne supposez pas que les deux se produisent au même instant.

Interaction commerciale

cord:approved : émis à l’instant où l’utilisateur approuve les conditions de la proposition commerciale. Renvoie dans le detail des données utiles comme le hash de validation et le signataire (signed_by).
cord:signed : déclenché au MÊME instant que cord:approved, avec le même detail (signed_by, hash) — dans Cord, approuver et signer sont une seule et même action du client, et non deux étapes distinctes dans le temps. Écoutez celui qui est le plus clair sémantiquement pour votre code ; n’attendez pas que l’un arrive « après » l’autre.
cord:pay : émis lorsque l’utilisateur clique sur le bouton qui lance son parcours de paiement en ligne (carte, virement bancaire ou les autres moyens de paiement activés par l’entreprise). Le detail contient l’url absolue de la page de paiement. Cord l’ouvre déjà dans sa propre fenêtre (le paiement ne s’exécute jamais dans l’iframe) : ne faites pas naviguer votre page vers cette URL, utilisez-la uniquement pour votre analyse.
cord:rejected : déclenché si le client marque explicitement la proposition comme déclinée. Le detail inclut le comentario qu’il a laissé, le cas échéant.
cord:message : se déclenche chaque fois que le client laisse un commentaire général ou une contre-proposition dans la discussion du devis.
cord:item_comment : déclenché lorsque l’utilisateur laisse un commentaire sur une ligne précise (ligne de produit) du devis, avec l’item_id correspondant dans le detail.

État

cord:updated : le devis a changé alors qu’il était ouvert (le commercial a modifié des lignes, des montants ou des conditions). Le devis s’est déjà redessiné de lui-même ; utilisez cet événement pour actualiser ce que votre page affiche autour.
cord:status_changed : le statut a changé (sent, viewed, approved, rejected, paid, expired…). Le detail contient le nouveau status (et saldo pour la facture).
cord:paid : uniquement sur <cord-invoice> : la facture a été soldée. Le detail contient folio, moneda et saldo.

cord:ready contient aussi status, moneda et total, pour que votre page puisse dessiner son propre récapitulatif sans autre appel.

Mode lecture seule

Si votre organisation n’a aucun domaine autorisé dans Paramètres › Générateur de devis intégrable, ou si la page hôte ne figure pas dans cette liste, le devis s’affiche en lecture seule : il ne propose ni d’approuver, ni de signer, ni de payer, ni d’écrire, et son bouton ouvre le lien public du devis dans un nouvel onglet. Dans ce mode, les événements arrivent sans detail : une page qui ne figure pas dans votre liste ne reçoit ni le signataire, ni les montants, ni l’URL de paiement.

Barre de débogage

Avec debug activé, Elements dessine sur votre site un panneau avec les événements de l’iframe, chaque requête à l’API avec son request_id et les avertissements de configuration (par exemple, les valeurs d’appearance que Cord a écartées).

<cord-quote token="a1b2c3d4e5f60718" debug></cord-quote>
<!-- ou avec embed.js -->
<div data-cord-token="a1b2c3d4e5f60718" data-cord-debug></div>

En React, <CordProvider debug>. Le panneau n’apparaît qu’avec une clé pk_test_ ; avec pk_live_, il se limite à un avertissement dans la console. Sans clé (Web Component ou embed.js), il n’apparaît que sur localhost ou si l’URL contient ?cord_debug=1, afin qu’un attribut oublié ne l’affiche jamais à vos clients.