Application embarquée

L’application embarquée, c’est l’assistant Dialog packagé pour les conseillers de vente : une page que votre propre application charge dans une iframe. Le conseiller discute avec l’assistant, scanne ou parcourt le catalogue, tient des listes de favoris et construit un pré-panier que Dialog transforme en commande provisoire Shopify envoyée au client par e-mail.

Cette page s’adresse à l’équipe qui développe l’application conseiller. Ce n’est pas une intégration vitrine : pour votre site, voyez le SDK et les composants.

Comment ça s’articule

Votre application conseiller (page)         Dialog
  iframe ─────────────────────────────────▶ application assistant
  ◀── dialog:ready
  ──▶ dialog:auth { token }     (signé par votre backend)
  ──▶ dialog:shopper { email }
  ◀── dialog:pre-cart-sent      (commande provisoire créée ; invoiceSent dit si elle a été envoyée par e-mail)

Votre backend détient une clé privée. Pour chaque conseiller connecté, il signe un token de courte durée qui le nomme ; votre page le transmet à l’iframe. Dialog le vérifie avec la moitié publique que vous avez enregistrée, et rattache favoris et pré-panier à ce conseiller.

Configurer dans le tableau de bord

Dans le tableau de bord Dialog, allez dans Sur votre boutique → Application embarquée.

Adresse à intégrer : l’URL de l’iframe, avec votre clé API publique déjà incluse. Copiez-la.
Origines autorisées : ajoutez l’origine de la page qui intègre l’application, par exemple https://conseillers.example.com. Uniquement des origines https://, plus http://localhost pour le développement. 20 au maximum. L’application ignore les messages de toute autre origine.
Clés de signature : cliquez sur Générer une clé. La paire est créée dans votre navigateur ; Dialog conserve la moitié publique et affiche la clé privée une seule fois. Rangez-la avec les secrets de votre backend, avec l’identifiant de clé (kid). Vous pouvez aussi Importer une clé publique à vous : une clé ES256 (P-256), en PEM ou en JWK.

Les clés tournent sans interruption : ajoutez une clé, déployez-la, puis révoquez l’ancienne. Une clé révoquée est refusée immédiatement.

Intégrer l’application

<iframe
  id="dialog-assistant"
  src="https://assistant-app.askdialog.com/?apiKey=VOTRE_CLE_API_PUBLIQUE&locale=fr-FR"
  allow="camera"
></iframe>

Paramètre	Requis	Description
`apiKey`	oui	Votre clé API publique. Incluse dans l’adresse fournie par le tableau de bord.
`locale`	non	Une locale BCP 47 (`fr-FR`, `en-GB`). Fixe la langue et le marché dont viennent les prix. Par défaut, celle du navigateur.
`countryCode`	non	Pays sur deux lettres, quand le marché diffère de la région de la locale.

allow="camera" permet au conseiller de scanner les QR codes produit. L’application est pensée pour un téléphone : donnez à l’iframe une taille portrait, ou réduisez-la à l’échelle.

Vous développez une application Android native ? Chargez l’application dans une WebView : voyez Application embarquée sur Android.

Sans token, l’application répond aux questions et parcourt le catalogue. Favoris et pré-panier apparaissent une fois le conseiller authentifié.

Messages

Tous les messages passent par postMessage. Postez vers l’origine exacte de l’iframe, et n’acceptez que les messages dont l’origin est cette même origine et dont la source est la fenêtre de l’iframe.

De l’application vers votre page

Message	Contenu	Quand
`dialog:ready`	aucun	L’application est chargée et écoute. Répondez par `dialog:auth`, puis `dialog:shopper` si vous le connaissez.
`dialog:token-expiring`	aucun	Environ 60 secondes avant l’expiration du token, ou après un refus de Dialog. Répondez par un nouveau `dialog:auth`.
`dialog:pre-cart-sent`	`{ draftOrderName, invoiceUrl, invoiceSent }`	Le pré-panier est envoyé : le nom de la commande provisoire (`#D1`) et le lien de paiement. `invoiceSent` vaut `false` quand Shopify n’a pas pu l’envoyer par e-mail ; la commande provisoire existe quand même, et le lien est le moyen pour le client d’y accéder.

De votre page vers l’application

Message	Contenu	Rôle
`dialog:auth`	`{ token }`	Le token conseiller. Envoyez-le sur `dialog:ready` et à chaque `dialog:token-expiring`.
`dialog:shopper`	`{ email?, customerId? }`	Le client que le conseiller sert. L’e-mail pré-remplit le formulaire du pré-panier ; `customerId` (un GID client Shopify) rattache la commande provisoire à ce compte client. Renvoyez-le quand le conseiller change de client.

const frame = document.getElementById('dialog-assistant')
const appOrigin = new URL(frame.src).origin

window.addEventListener('message', async event => {
  if (event.origin !== appOrigin || event.source !== frame.contentWindow) return

  if (event.data.type === 'dialog:ready' || event.data.type === 'dialog:token-expiring') {
    const { token } = await fetch('/api/dialog-token').then(r => r.json())
    frame.contentWindow.postMessage({ type: 'dialog:auth', token }, appOrigin)
  }
  if (event.data.type === 'dialog:pre-cart-sent') {
    console.log(event.data.draftOrderName, event.data.invoiceUrl, event.data.invoiceSent)
  }
})

Le token conseiller

Un JWT signé en ES256 par votre backend, jamais dans le navigateur. Votre route /api/dialog-token en signe un pour le conseiller connecté, et seulement pour lui.

Claim	Valeur
`kid` (en-tête)	L’identifiant de clé affiché dans le tableau de bord.
`iss`	Le slug de votre organisation, tel qu’il apparaît dans l’URL du tableau de bord.
`aud`	`dialog-assistant-app`
`sub`	L’identifiant du conseiller dans votre système. Opaque pour Dialog ; il indexe ses favoris et son pré-panier.
`store`	Optionnel : l’identifiant du point de vente.
`iat`, `exp`	Au plus 15 minutes d’écart. Dialog tolère 30 secondes de dérive d’horloge.

Avec jose en Node :

import { importPKCS8, SignJWT } from 'jose'

const privateKey = await importPKCS8(process.env.DIALOG_PRIVATE_KEY, 'ES256')

const token = await new SignJWT({ store: 'paris-01' })
  .setProtectedHeader({ alg: 'ES256', kid: process.env.DIALOG_KEY_ID })
  .setIssuer('slug-de-votre-organisation')
  .setAudience('dialog-assistant-app')
  .setSubject(advisor.id)
  .setIssuedAt()
  .setExpirationTime('15m')
  .sign(privateKey)

Un token est refusé quand sa clé est inconnue ou révoquée, que sa signature ou son audience est fausse, ou qu’il vit plus de 15 minutes. L’application demande alors un nouveau token à votre page avec dialog:token-expiring.

Pour aller plus loin

Application embarquée sur Android : une application conseiller Android native.
Référence SDK : l’assistant sur votre propre site.
Intégration du catalogue : le catalogue que parcourt l’application embarquée.