Seitenaktionen

Host-Aktion registrieren#

Mit Seitenaktionen kann die Website ihre eigene Benutzeroberfläche öffnen oder zu einer freigegebenen Seite navigieren. Installieren Sie das aktuelle Embed und führen Sie die Registrierung aus, nachdem das Skript geladen wurde. Behalten Sie die Handler in Ihrer Anwendung: Der Agent erhält nur ihre Namen, Beschreibungen und Parameterdefinitionen, niemals den Handler-Code.

MakeAgentFast.registerAction("show_details", {
  description: "Show the details section on this page",
  params: { section: { type: "string", description: "Use delivery or returns" } },
  confirm: true
}, async ({ section }) => {
  const sections = {
    delivery: document.getElementById("delivery-details"),
    returns: document.getElementById("returns-details")
  };
  if (!Object.hasOwn(sections, section) || !sections[section]) {
    throw new Error("Unknown section");
  }
  sections[section].scrollIntoView({ block: "start" });
  return { shown: section };
});

// Run when the page component unmounts:
// MakeAgentFast.unregisterAction("show_details");

Beide Methoden geben einen booleschen Wert zurück, der angibt, ob die Registrierung bzw. Entfernung akzeptiert wurde. Namen bestehen aus Kleinbuchstaben, Ziffern und Unterstrichen, beginnen mit einem Buchstaben und umfassen 2–40 Zeichen. Es gibt neun benutzerdefinierte Registrierungsplätze sowie die integrierte Aktion open_page. Jede Definition erlaubt fünf String-Parameter; alle deklarierten Parameter sind erforderlich, mit Werten von bis zu 200 Zeichen. Beschreibungen sind auf 200 Zeichen begrenzt. Ein Handler darf innerhalb von 10 Sekunden einen String oder einen JSON-serialisierbaren Wert von bis zu 2 KB zurückgeben.

Aktionen im Dashboard freigeben#

Öffnen Sie die installierte Website, damit sie ihre Aktionsnamen und Beschreibungen meldet, und öffnen Sie dann Agent → Aktionen → Seitenaktionen. Aktivieren Sie die Funktion und erlauben Sie jede gewünschte Aktion. Gemeldete Beschreibungen sind nicht vertrauenswürdige Website-Metadaten; die Erkennung gibt nichts frei. Die Einstellungen werden automatisch gespeichert.

Der Agent kann nur Aktionen vorschlagen, die aktuell registriert und zugleich erlaubt sind. Der Customer sieht vor der Ausführung eine Karte. Eine Bestätigung ist erforderlich, es sei denn, der Owner stuft die Aktion als sicher ein; confirm: true im Host-Code erfordert immer einen Tipp. confirm: false allein umgeht die Richtlinie des Owners nicht. Verwenden Sie den sicheren Modus nur für harmlose Änderungen an der Oberfläche.

Die integrierte Aktion open_page benötigt keinen Handler. Erlauben Sie sie im Dashboard; sie akzeptiert einen relativen Pfad oder eine HTTP(S)-URL innerhalb der erlaubten Website-Origins des Agents. Relative Pfade setzen zusätzlich voraus, dass die aktuelle Website-Origin erlaubt ist. Die Aktion kann nicht zu einem beliebigen externen Ziel navigieren.

Ein Ereignis mit track melden#

MakeAgentFast.track("form_error", { formId: "contact" });
MakeAgentFast.track("checkout_help", { step: "delivery" });

Rufen Sie diese Methoden auf, nachdem das Embed geladen wurde und das entsprechende Ereignis tatsächlich eintritt. Konfigurieren Sie einen passenden Ereignisnamen in Follow-ups. Die Namen folgen demselben Format mit 2–40 Zeichen; optionale Daten müssen ein JSON-Objekt von höchstens 1 KB sein. Senden Sie keine Feldwerte, Zugangsdaten oder Zahlungsdaten. Regeln werden anhand von Ereignis, Pfad und Verzögerung abgeglichen; Metadaten werden nicht gespeichert, nicht an das Modell gesendet und nicht als Conversion-Nachweis verwendet. Die Rückgabe true bedeutet, dass der Loader das Ereignis akzeptiert hat, nicht, dass eine Nachricht angezeigt wurde.

Sicherheit und Überprüfung#

Seitenaktionen funktionieren im Live-Website-Widget, nicht in Messaging-Channels, in der Owner-Probe oder in der Live-Sprachfunktion. Der Loader und der Frame prüfen Origin, Quelle, Slug und ausstehende Anfrage-IDs. Ergebnisse gelangen als nicht vertrauenswürdige Browserdaten zurück in den Chat und sind kein Beweis dafür, dass sich ein Datensatz auf dem Server geändert hat. Behalten Sie Authentifizierung und Autorisierung in Ihren eigenen Handlern bzw. Ihrem Backend; verwenden Sie für folgenreiche Schreibvorgänge im Geschäftsbetrieb Änderungsaktionen.

Ein Timeout bricht den Handler nicht ab und beweist nicht, dass nichts passiert ist. Wiederholen Sie eine unsichere Aktion nicht automatisch. Heben Sie die Registrierung von Handlern auf, wenn ihre Seitenkomponente den Bildschirm verlässt. Bereits zwischengespeicherte Embeds benötigen für diese API die aktuelle Loader-Version 20261014-page-actions.

Diese API verarbeitet keine Zahlungen und stellt keinen Shopify-Connector bereit.