Tracking SDK custom

Quand Dialog est installé via le SDK, les composants React ou les composants Vue, les events dans l’assistant sont trackés automatiquement. Les events side-cart et checkout qui se passent en dehors de l’assistant, eux, ne le sont pas — tu les câbles en appelant deux méthodes SDK.

Utilisateurs React et Vue : ça vous concerne

Les packages composants React et Vue wrappent le même SDK. Tu dois quand même appeler client.registerAddToCartEvent et client.registerSubmitCheckoutEvent depuis ton code storefront — utiliser les composants ne les auto-tracke pas.

Si tu préfères ne pas appeler de méthodes SDK depuis ton code, l’alternative est le bridge tracking GTM : si ton tagging GTM existant push déjà des events add_to_cart et purchase, forwarde-les depuis GTM à la place.

Ce que tu câbles toi-même

Deux events :

• user_added_to_cart — quand l’utilisateur ajoute un produit au panier en dehors de l’assistant (par ex. depuis tes boutons PDP).
• user_submitted_checkout — quand l’utilisateur termine le checkout, qu’il ait utilisé Dialog ou non.

Les deux sont nécessaires pour que le dashboard calcule ta vraie baseline de add-to-cart rate, le checkout / conversion rate, et l’attribution revenue. Voir pourquoi ça compte.

registerAddToCartEvent

Appelle-le depuis l’endroit où ton site ajoute un produit au panier — typiquement le click handler de ton bouton “Add to cart”, ou juste après le retour OK de ton API de mutation panier.

client.registerAddToCartEvent({
  productId: 'product-123',
  quantity: 1,
  currency: 'EUR',
  variantId: 'variant-456',
  price: 29.99,
})

Paramètres

Champ	Type	Requis	Description
productId	string	Oui	L’ID du produit, matchant ton catalogue.
quantity	number	Oui	Nombre d’unités ajoutées.
currency	string	Non	Code ISO devise, ex. 'EUR'.
variantId	string	Non	ID de variante si applicable.
price	number	Non	Prix unitaire.

registerSubmitCheckoutEvent

Appelle-le une fois par commande complétée, depuis ta page de confirmation de commande (ou n’importe où tu sais que le checkout a réussi). Passe le total de la commande dans orderValue — c’est ce que lit le KPI « Revenus générés » du dashboard.

client.registerSubmitCheckoutEvent({
  orderValue: 59.98,
  currency: 'EUR',
  transactionId: 'order-789',
  items: [
    { productId: 'product-123', quantity: 1, price: 29.99, variantId: 'variant-456' },
    { productId: 'product-456', quantity: 1, price: 29.99 },
  ],
})

Paramètres

Champ	Type	Requis	Description
orderValue	number	Oui	Le total de la commande. C’est à partir de ça que les revenus sont calculés.
currency	string	Non	Code devise ISO, ex. 'EUR'.
transactionId	string	Non	ID de commande. Utilisé pour dédupliquer si la page de confirmation est rechargée. Fortement recommandé.
items	array	Non	Lignes de commande, pour l’attribution produit uniquement. Les revenus ne sont jamais sommés à partir de ces lignes — ils viennent de orderValue.

Appelle-le une fois par commande, avec le total

N’appelle pas cette méthode une fois par ligne du panier, et ne passe pas le price d’une seule ligne comme montant. Sans total dans orderValue, le dashboard affiche 0 revenu pour ta boutique.

onAssistantEvent — forwarder vers tes propres analytics

Abonne-toi aux events émis par l’assistant et forwarde-les où tu veux — GA4, Segment, Mixpanel, ton warehouse.

const unsubscribe = client.onAssistantEvent((event) => {
  switch (event.type) {
    case 'userAddedToCart':
      analytics.track('dialog_conversion', {
        productId: event.payload.productId,
        variantId: event.payload.variantId,
        timestamp: event.payload.date,
      })
      break

    case 'userSendNegativeFeedback':
      console.warn('Dialog negative feedback at:', event.payload.url)
      break
  }
})

// Plus tard, à l'unmount / au changement de route SPA
unsubscribe()

Types d’events

• userOpenedAssistant
• userClosedAssistant
• userSentMessage
• userClickedOnProductCard
• userOpenedRecommendation
• userAddedToCart
• userSendPositiveFeedback
• userSendNegativeFeedback

Format du payload

interface AssistantEvent {
  type: string
  payload: {
    date: string        // timestamp ISO
    locale: string      // locale courante
    url: string         // URL de la page courante
    userId?: string     // présent quand connu
    productId?: string  // présent pour les events scopés produit
    variantId?: string  // présent pour les events scopés variante
  }
}

Exemple bout en bout

Un setup minimal, applicable à React, Vue ou vanilla :

import { Dialog } from '@askdialog/dialog-sdk'

const client = new Dialog({
  apiKey: 'YOUR_PUBLIC_API_KEY',
  locale: 'fr',
  callbacks: {
    addToCart: async ({ productId, quantity, variantId, currency }) => {
      await fetch('/api/cart', {
        method: 'POST',
        body: JSON.stringify({ productId, variantId, quantity }),
      })
      window.dispatchEvent(new CustomEvent('cart:updated'))
    },
    getProduct: async (productId, variantId) => {
      const res = await fetch(`/api/products/${productId}?variant=${variantId ?? ''}`)
      return res.json()
    },
  },
})

// Add-to-cart side-cart (bouton hors assistant)
document.querySelector('#pdp-add-to-cart')!.addEventListener('click', async () => {
  await addToCart({ productId, variantId, quantity: 1 })
  client.registerAddToCartEvent({
    productId,
    variantId,
    quantity: 1,
    price: 29.99,
    currency: 'EUR',
  })
})

// Page de succès checkout — une fois par commande, avec le total
client.registerSubmitCheckoutEvent({
  orderValue: 59.98,
  currency: 'EUR',
  transactionId: orderId,
  items: [{ productId, variantId, quantity: 1, price: 59.98 }],
})

Suite

• Vue d’ensemble du tracking — automatique vs manuel par chemin d’install.
• Bridge tracking GTM — chemin alternatif si ton GTM fire déjà ces events.
• Référence SDK — le reste de l’API SDK.