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 tu as besoin pour construire une UI autour.

Tu utilises React ou Vue ?

N’utilise pas le SDK vanilla directement. Utilise @askdialog/dialog-react ou @askdialog/dialog-vue — ils embarquent un DialogProductBlock et DialogInput pré-construits par-dessus ce SDK. Sinon tu les réinventerais.

Cette page est pour Svelte, SolidJS, Lit, vanilla JS, frontends en templating server-side (Twig, Blade, ERB, etc.), ou tout autre framework sans package Dialog.

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 }) => {
      // Ajoute le produit au panier et refresh ton UI
    },
    getProduct: async (productId, variantId): Promise<SimplifiedProduct> => {
      // Récupère le produit depuis ton backend et renvoie-le au format SimplifiedProduct
    },
  },
})

Options du constructor

Option	Type	Requis	Description
apiKey	string	Oui	Ta 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. Tu gères la mutation panier et le refresh UI.
callbacks.getProduct	(productId, variantId?) => Promise<SimplifiedProduct>	Oui	Appelée pour afficher les cards produit dans l’assistant. Renvoie ton 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.

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 tu construis une UI de suggestions custom sur ta PDP plutôt que d’utiliser notre composant DialogProductBlock.

const suggestions = await client.getSuggestions('product-123')
// {
//   questions: [{ question: '...' }, ...],
//   assistantName: 'Your expert',
//   inputPlaceholder: 'Pose ta question...',
//   description: 'Pose 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). Utilise 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',
})

Appelle 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

Passe 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 toi qui le fais.

Format SimplifiedProduct

Ton 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.