Étendre le widget

D’origine, l’assistant répond et appelle votre API. Enregistré via window.syncanix, il va plus loin : afficher vos propres composants dans le chat, effectuer des actions sur la page courante et montrer des données en direct qui restent fraîches.

Affichez vos composants dans le chat

registerComponent confie à l’assistant un composant qu’il peut afficher dans une réponse : une carte de commande, un graphique, un formulaire. Vous fournissez un id, le composant et un schéma Zod pour ses props ; la description facultative indique au modèle quand l’utiliser.

import { z } from 'zod';
import { OrderCard } from './OrderCard';

const OrderCardProps = z.object({ orderId: z.string() });

window.syncanix?.registerComponent('OrderCard', OrderCard, OrderCardProps, {
  description: 'Shows an order summary',
  propDescriptions: { orderId: 'Which order to show' },
});

Les props fournies par le modèle sont validées contre votre schéma avant tout affichage : une divergence est rejetée bruyamment plutôt que d’afficher quelque chose d’à moitié juste.

Donnez à vos composants le contexte de votre app

Les composants enregistrés s’affichent dans le widget, ils n’ont donc pas par défaut les providers de votre app. registerProviders enveloppe chaque composant affiché dans votre propre wrapper — client de données, routeur, thème — pour qu’ils se comportent exactement comme ailleurs dans votre app.

window.syncanix?.registerProviders(({ children }) => (
  <ApolloProvider client={apolloClient}>
    <ThemeProvider theme={theme}>{children}</ThemeProvider>
  </ApolloProvider>
));

Laissez l’assistant agir sur la page

registerAction expose une fonction que l’assistant peut appeler sur la page courante : naviguer quelque part, recharger un tableau, ouvrir un panneau. Ajoutez un schéma Zod de paramètres quand l’action prend des arguments.

window.syncanix?.registerAction('refetch_orders', () => ordersQuery.refetch(), {
  description: 'Reload the orders table with the latest data',
});

window.syncanix?.registerAction('go_to_invoice', ({ id }) => navigate(`/invoices/${id}`), {
  parameters: z.object({ id: z.string() }),
  parameterDescriptions: { id: 'The invoice id to open' },
  description: 'Navigate to a specific invoice',
});

Limitez les actions à la page : enregistrez-les au montage de la surface et désenregistrez-les au démontage, l’assistant ne voit ainsi que ce qui est disponible à l’instant. Pour les actions à effet réel, passez confirm: true afin que l’utilisateur approuve avant l’exécution.

Liez des données en direct

registerDataSource permet à l’assistant d’afficher des données toujours à jour : au lieu de figer un instantané dans sa réponse, il référence votre source, et le widget appelle votre fetcher au moment de l’affichage. Définissez pollMs (au moins 1000) pour activer l’actualisation automatique.

window.syncanix?.registerDataSource(
  'open_orders',
  async (params) => ({ rows: await api.orders({ status: 'open', ...params }) }),
  { description: 'Current open orders', pollMs: 30000 },
);

Dites à l’assistant où se trouve l’utilisateur

setContext transmet au tour suivant la page courante, le forfait, le panier ou tout autre état de votre app, pour que les réponses reflètent ce que l’utilisateur regarde. Rappelez-le à chaque navigation : la dernière valeur l’emporte.

window.syncanix?.setContext({
  user: { id: 'u_1', plan: 'pro' },
  page: { path: '/checkout' },
});

Pas de React ? Utilisez les web components

Si votre app n’est pas construite sur React, la passerelle @syncanix/web-components enveloppe n’importe quel custom element natif pour le brancher sur le même circuit registerComponent :

npm install @syncanix/web-components

import { defineSyncanixComponent } from '@syncanix/web-components';
import { z } from 'zod';

const StatusBadge = defineSyncanixComponent(
  'status-badge',
  StatusBadgeElement, // your HTMLElement subclass
  z.object({ label: z.string(), tone: z.string() }),
);

window.syncanix?.registerComponent('status-badge', StatusBadge, StatusBadge.propsSchema);

Détection automatique des actions

exposePageActions peut découvrir des actions dans un périmètre explicite que vous définissez — une carte des routes pour la navigation et des éléments marqués data-syncanix-action — plutôt que de tout enregistrer à la main. La fonction est derrière l’indicateur Labs auto-detect-actions, et chaque action découverte est signalée à votre tableau de bord pour revue avant de devenir appelable : la navigation est sans confirmation, les éléments marqués confirment toujours.

Étapes suivantes