Référence SDK

@askdialog/dialog-sdk est le SDK core pour embedder Dialog dans des stacks custom. Il gère la communication avec l’API Dialog, le cycle de vie de l’assistant, le tracking, et expose tout ce dont vous avez besoin pour construire une UI autour.

Install

Depuis npm :

npm install @askdialog/dialog-sdk
# ou
pnpm add @askdialog/dialog-sdk
# ou
yarn add @askdialog/dialog-sdk

Depuis CDN (sans bundler) :

<script src="https://d2m6yt8rnm4dos.cloudfront.net/dialog-sdk.X.Y.Z.min.js"></script>

Chargé via CDN, le SDK est exposé en window.DialogSDK.

Instancier

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

const client = new Dialog({
  apiKey: 'YOUR_PUBLIC_API_KEY',
  locale: 'fr',
  callbacks: {
    addToCart: async ({ productId, quantity, variantId, currency }) => {
      // Ajoutez le produit au panier et refresh votre UI
    },
    getProduct: async (productId, variantId): Promise<SimplifiedProduct> => {
      // Récupérez le produit depuis votre backend et renvoyez-le au format SimplifiedProduct
    },
  },
})

Options du constructor

Option	Type	Requis	Description
`apiKey`	`string`	Oui	Votre clé API publique Dialog.
`locale`	`string`	Oui	Locale active (ex. `'en'`, `'fr'`, `'es'`).
`callbacks.addToCart`	`(params) => Promise<void>`	Oui	Appelée quand l’utilisateur clique sur add-to-cart dans l’assistant. Vous gérez la mutation panier et le refresh UI.
`callbacks.getProduct`	`(productId, variantId?) => Promise<SimplifiedProduct>`	Oui	Appelée pour afficher les cards produit dans l’assistant. Renvoyez votre produit au format `SimplifiedProduct`.
`theme`	`Theme`	Non	Override du thème visuel (couleurs, polices, forme des CTA).
`userId`	`string`	Non	ID stable de visiteur. Si omis, Dialog en génère un automatiquement et le persiste.
`product`	`{ id: string; variantId?: string }`	Non	Le produit de la page courante. Ancre les questions sans produit propre (bookmark flottant, reprise, champ libre) sur le produit consulté. Voir Déclarer le produit courant.
`disableAddToCart`	`boolean`	Non	Masque l’add-to-cart Dialog pour cette instance/session du widget (défaut `false`). Voir « Désactiver l’add-to-cart » ci-dessous.

Désactiver l’add-to-cart

Mets disableAddToCart: true pour désactiver l’add-to-cart Dialog sur une session précise : par exemple une boutique B2B qui masque les actions d’achat quand un client B2B est connecté. Évalue ta propre condition à l’initialisation :

const client = new Dialog({
  apiKey: 'YOUR_PUBLIC_API_KEY',
  locale: 'fr',
  disableAddToCart: isB2BCustomerLoggedIn, // par session
  callbacks: { /* ... */ },
})

Quand c’est activé :

l’assistant masque le CTA add-to-cart sur les cards de recommandation et les cards produit conversationnelles ;
callbacks.addToCart n’est jamais appelé et aucun événement add-to-cart n’est tracké ;
les liens produit et la navigation des recommandations restent disponibles.

Omets-le (ou mets false) pour garder le comportement actuel. Le flag est lu à l’initialisation : il s’applique pour toute la durée de vie de l’instance du widget (un changement d’état de connexion prend effet au rechargement suivant).

Déclarer le produit courant

Sur les pages produit, le paramètre product indique à l’assistant quel produit le visiteur regarde. Les questions posées sans produit explicite — depuis le bookmark flottant, la reprise de conversation ou le champ libre — sont alors répondues dans le contexte de ce produit, y compris après une navigation d’une page produit à une autre :

const client = new Dialog({
  apiKey: 'YOUR_PUBLIC_API_KEY',
  locale: 'fr',
  product: { id: 'product-123', variantId: 'variant-456' }, // variantId optionnel
  callbacks: { /* ... */ },
})

Sur une boutique single-page, mettre la déclaration à jour à chaque navigation côté client :

client.setCurrentProduct('product-456', 'variant-789') // variantId optionnel
client.clearCurrentProduct() // sortie vers une page non-produit

L’id doit correspondre à l’ID produit du flux catalogue Dialog. Sans produit déclaré, les questions posées hors d’un clic produit sont répondues sans contexte produit.

Envoyer des messages

Avec contexte produit

client.sendProductMessage({
  question: 'Est-ce que ce top taille petit ?',
  productId: 'product-123',
  productTitle: 'Top col V en lin',
  selectedVariantId: 'variant-456', // optionnel
})

Sans contexte produit

client.sendGenericMessage({
  question: 'Quelle est votre politique de retour ?',
})

Récupérer des suggestions

Récupère la liste de suggestions générées par l’IA pour un produit donné. Utile si vous construisez une UI de suggestions custom sur votre PDP plutôt que d’utiliser notre composant DialogProductBlock.

const suggestions = await client.getSuggestions('product-123')
// {
//   questions: [{ question: '...' }, ...],
//   assistantName: 'Your expert',
//   inputPlaceholder: 'Posez votre question...',
//   description: 'Posez n'importe quelle question sur ce produit'
// }

Informations de locale

const info = client.getLocalizationInformations()
// { countryCode: 'FR', formatted: 'fr-FR', language: 'French', locale: 'fr' }

Tracking

Le SDK auto-tracke les interactions avec l’assistant (open / close / message / add-to-cart depuis l’assistant). Utilisez les méthodes ci-dessous pour les events qui se passent en dehors de l’assistant.

Add-to-cart et checkout manuels

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

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

Appelez ces méthodes à chaque fois que le client ajoute au panier ou termine son checkout sans passer par l’assistant Dialog, pour que le dashboard puisse attribuer la conversion correctement. Voir Tracking : SDK custom pour les détails.

Écouter les events de l’assistant

const unsubscribe = client.onAssistantEvent((event) => {
  // event.type, event.payload
})

// Plus tard
unsubscribe()

Types d’events disponibles (guide complet dans Tracking : SDK custom) :

userOpenedAssistant
userClosedAssistant
userSentMessage
userClickedOnProductCard
userOpenedRecommendation
userAddedToCart
userSendPositiveFeedback
userSendNegativeFeedback

Theme

Passez un objet theme à la construction :

const client = new Dialog({
  apiKey: 'YOUR_PUBLIC_API_KEY',
  locale: 'fr',
  theme: {
    backgroundColor: '#ffffff',
    primaryColor: '#000000',
    ctaTextColor: '#ffffff',
    ctaBorderType: 'rounded', // 'straight' | 'rounded'
    capitalizeCtas: false,
    fontFamily: 'Inter, sans-serif',
    highlightProductName: true,
  },
  callbacks: { /* ... */ },
})

Les clés title, description et content du theme ne s’appliquent qu’aux composants Vue / React. Le SDK vanilla ne rend pas ces zones : c’est vous qui le faites.

Format SimplifiedProduct

Votre callback getProduct doit renvoyer ce format :

interface SimplifiedProduct {
  id: string
  title: string
  handle: string
  descriptionHtml?: string
  url?: string
  totalInventory: number
  featuredImage?: { url?: string } | null
  variants: SimplifiedProductVariant[]
  options?: SimplifiedProductOption[]
}

interface SimplifiedProductVariant {
  id: string
  displayName?: string
  inventoryQuantity?: number
  price: string                       // string, ex. '29.99'
  currencyCode: string                // code ISO, ex. 'EUR'
  compareAtPrice?: string | null
  url?: string
  selectedOptions?: { name: string; value: string }[]
  image?: { url?: string } | null
}

interface SimplifiedProductOption {
  id: string
  name: string
  position: number
  values: string[]
}

Étapes suivantes

Composants React : UI drop-in avec le SDK.
Composants Vue : pareil, pour Vue 3.
Tracking SDK custom : guide complet de tracking côté SDK.
Problèmes d’ajout au panier : patterns de sync UI courants.