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 : vous les câblez en appelant deux méthodes SDK.

Utilisateurs React et Vue : ça vous concerne

Les packages composants React et Vue wrappent le même SDK. Vous devez quand même appeler client.registerAddToCartEvent et client.registerSubmitCheckoutEvent depuis votre code storefront : utiliser les composants ne les auto-tracke pas.

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

Ce que vous câblez vous-même

Deux events :

• user_added_to_cart : quand l’utilisateur ajoute un produit au panier en dehors de l’assistant (par ex. depuis vos 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 votre vraie baseline de add-to-cart rate, le checkout / conversion rate, et l’attribution revenue. Voir pourquoi ça compte.

registerAddToCartEvent

Appelez-le depuis l’endroit où votre site ajoute un produit au panier : typiquement le click handler de votre bouton “Add to cart”, ou juste après le retour OK de votre 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 votre 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

Appelez-le une fois par commande complétée, depuis votre page de confirmation de commande (ou n’importe où vous savez que le checkout a réussi). Passez 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.

Appelez-le une fois par commande, avec le total

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

onAssistantEvent : forwarder vers vos propres analytics

Abonnez-vous aux events émis par l’assistant et forwardez-les où vous voulez : GA4, Segment, Mixpanel, votre 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 votre GTM fire déjà ces events.
• Référence SDK : le reste de l’API SDK.