Acciones de página

Registra una acción del sitio#

Las acciones de página permiten que el sitio web abra su propia interfaz o navegue a una página aprobada. Instala el embed actual y ejecuta el registro después de que se haya cargado el script. Mantén los controladores (handlers) en tu aplicación; el agente recibe sus nombres, descripciones y definiciones de parámetros, pero nunca el código del controlador.

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

Ambos métodos devuelven un valor booleano que indica si se aceptó el registro o la eliminación. Los nombres usan letras minúsculas, dígitos y guiones bajos, empiezan con una letra y tienen entre 2 y 40 caracteres. Hay nueve espacios de registro personalizados, además de la acción integrada open_page. Cada definición admite cinco parámetros de tipo cadena; todos los parámetros declarados son obligatorios, con valores de hasta 200 caracteres. Las descripciones están limitadas a 200 caracteres. Un controlador puede devolver una cadena o un valor serializable en JSON de hasta 2 KB en un plazo de 10 segundos.

Aprueba las acciones en el panel#

Abre el sitio web donde has instalado el embed para que informe de los nombres y las descripciones de sus acciones; después, abre Agente → Acciones → Acciones de página. Activa la función y permite cada acción que quieras habilitar. Las descripciones reportadas son metadatos del sitio web no verificados; detectar una acción no aprueba nada. Los ajustes se guardan automáticamente.

El agente solo puede proponer acciones que estén registradas en ese momento y además permitidas. El cliente ve una tarjeta antes de la ejecución. Se requiere confirmación a menos que el propietario marque la acción como segura; confirm: true en el código del sitio siempre exige un toque del cliente. confirm: false por sí solo no omite la política del propietario. Reserva el modo seguro para cambios inofensivos en la interfaz.

La acción integrada open_page no necesita controlador. Permítela en el panel; acepta una ruta relativa o una URL HTTP(S) dentro de los orígenes de sitio web permitidos del agente. Las rutas relativas también requieren que el origen actual del sitio web esté permitido. No puede navegar a un destino externo arbitrario.

Informa de un evento con track#

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

Llama a estas funciones después de que se cargue el embed y cuando el evento correspondiente ocurra realmente. Configura un nombre de evento equivalente en Seguimientos. Los nombres siguen el mismo formato de 2 a 40 caracteres; los datos opcionales deben ser un objeto JSON de como máximo 1 KB. No envíes valores de campos, credenciales ni datos de pago. Las reglas coinciden por evento, ruta y retraso; los metadatos no se almacenan, no se envían al modelo ni se usan como prueba de conversión. Un retorno true significa que el cargador aceptó el evento, no que se haya mostrado un mensaje.

Seguridad y verificación#

Las acciones de página funcionan en el widget del sitio web en producción, no en los canales de mensajería, ni en los ensayos del propietario, ni en la voz en vivo. El cargador y el marco comprueban el origen, la fuente, el slug y los ID de solicitud pendientes. Los resultados vuelven al chat como datos del navegador no confiables, no como prueba de que se haya modificado un registro en el servidor. Mantén la autenticación y la autorización en tus propios controladores o backend; usa Acciones de cambio para escrituras de negocio con consecuencias.

Un tiempo de espera agotado no cancela el controlador ni demuestra que no haya ocurrido nada. No reintentes automáticamente una acción cuyo resultado sea incierto. Cancela el registro de los controladores cuando el componente de su página deje de mostrarse. Los embeds almacenados en caché necesitan la versión actual del cargador, 20261014-page-actions, para usar esta API.

Esta API no gestiona pagos ni ofrece un conector de Shopify.