Das Widget erweitern

Von Haus aus antwortet der Assistent und ruft Ihre API auf. Über window.syncanix registriert, kann er mehr: eigene Komponenten im Chat rendern, Aktionen auf der aktuellen Seite ausführen und Live-Daten zeigen, die sich selbst aktuell halten.

Ihre Komponenten im Chat rendern

registerComponent gibt dem Assistenten eine Komponente an die Hand, die er als Teil einer Antwort rendern darf — eine Bestellkarte, ein Diagramm, ein Formular. Sie liefern eine Id, die Komponente und ein Zod-Schema für die Props; die optionale Beschreibung sagt dem Modell, wann sie zu verwenden ist.

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' },
});

Vom Modell gelieferte Props werden vor jedem Rendern gegen Ihr Schema validiert: Eine Abweichung wird laut zurückgewiesen, statt etwas halb Richtiges zu rendern.

Geben Sie Komponenten den Kontext Ihrer App

Registrierte Komponenten rendern im Widget und haben daher standardmäßig nicht die Provider Ihrer App. registerProviders umhüllt jede gerenderte Komponente mit Ihrem eigenen Wrapper — Datenclient, Router, Theme — sodass sie sich genau wie überall sonst in Ihrer App verhalten.

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

Lassen Sie den Assistenten auf der Seite handeln

registerAction stellt eine Funktion bereit, die der Assistent auf der aktuellen Seite aufrufen kann: irgendwohin navigieren, eine Tabelle neu laden, ein Panel öffnen. Fügen Sie ein Zod-Parameterschema hinzu, wenn die Aktion Argumente nimmt.

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',
});

Begrenzen Sie Aktionen auf die Seite: beim Einhängen der Oberfläche registrieren, beim Aushängen deregistrieren — der Assistent sieht so nur, was gerade verfügbar ist. Für Aktionen mit echter Wirkung übergeben Sie confirm: true, damit der Nutzer vor der Ausführung zustimmt.

Live-Daten anbinden

Mit registerDataSource zeigt der Assistent Daten, die aktuell bleiben: Statt einen Schnappschuss in die Antwort zu backen, referenziert er Ihre Quelle, und das Widget ruft Ihren Fetcher beim Rendern auf. Setzen Sie pollMs (mindestens 1000) für automatische Aktualisierung.

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

Sagen Sie dem Assistenten, wo der Nutzer ist

setContext speist die aktuelle Seite, den Tarif, den Warenkorb oder beliebigen anderen App-Zustand in den nächsten Zug ein, damit Antworten widerspiegeln, was der Nutzer gerade sieht. Rufen Sie es bei Navigation erneut auf: Der letzte Wert gewinnt.

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

Kein React? Nutzen Sie Web Components

Wenn Ihre App nicht auf React aufbaut, umhüllt die Brücke @syncanix/web-components jedes native Custom Element, sodass es in denselben registerComponent-Ablauf passt:

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);

Seitenaktionen automatisch erkennen

exposePageActions kann Aktionen in einem von Ihnen definierten, ausdrücklichen Rahmen entdecken — eine Routenkarte für Navigation und mit data-syncanix-action markierte Elemente — statt jede von Hand zu registrieren. Die Funktion liegt hinter dem Labs-Schalter auto-detect-actions, und jede entdeckte Aktion wird zur Prüfung an Ihr Dashboard gemeldet, bevor sie aufrufbar wird: Navigation ist bestätigungsfrei, markierte Elemente bestätigen immer.

Nächste Schritte