Skip to main content
Los scripts personalizados te permiten ejecutar tu propio JavaScript sobre el carrito usando el Cart SDK. Agrégalos en el editor del carrito en Cart settings → Custom script, donde un menú desplegable alterna entre dos slots: Initialization y On cart update. Escribe JavaScript puro en estos editores, sin etiquetas <script>. On cart update tiene una acción Reset to default que restaura su plantilla inicial; Initialization no, así que guarda tu propia copia antes de borrarlo.
Mucho de lo que los comerciantes solían resolver con scripts ahora es una configuración integrada. Consulta primero Antes de escribir un script: una configuración sigue funcionando a través de rediseños del carrito, y tu script podría no hacerlo.

Qué slot usar

Initialization

El script de Initialization se ejecuta una vez cuando el carrito se carga. Es tu punto de entrada para configurar todo: configurar el comportamiento del carrito, suscribirte a eventos y registrar hooks. El SDK está disponible como window.aftersell.cart. Las llamadas de configuración que hagas aquí (configure(...), events.on(...), hooks.*) se pueden llamar con seguridad al inicio del script incluso antes de que el carrito haya arrancado por completo; se almacenan en búfer y se aplican una vez que lo hace. Las acciones que leen o cambian el carrito (como addItem o getCart) deben ejecutarse dentro de ready() o de un handler de eventos. El slot comienza con tres ejemplos comentados (abrir el drawer en cada agregado, reaccionar a cart_loaded y ocultar las líneas de regalo gratis), así que un script de Initialization sin tocar no hace nada. Descomenta uno para probarlo, o reemplázalos. La forma natural para este slot es un registro único sin eventos involucrados: registra el comportamiento una vez y deja que el carrito lo aplique a partir de entonces. Ocultar las líneas de regalo gratis del drawer, sin cambiar el total, es el ejemplo incluido de eso:
registerLineTransform se ejecuta para cada línea a medida que se renderiza, y setHidden es solo de visualización, así que la línea permanece en el carrito y sigue contando para el total, simplemente no se muestra en el drawer. Consulta Ocultar y reetiquetar líneas del carrito para ver más de lo que puede hacer una transformación. Las acciones que leen el carrito van dentro de ready():
Acceder al DOM del carrito requiere la misma espera, y necesita shadowRoot: el carrito se renderiza dentro de un shadow root, así que document.querySelector no puede ver nada dentro del drawer.
¿Necesitas ramificar según mercado, país o moneda antes de que el carrito se cargue? Lee context en su lugar. Está disponible de forma síncrona, sin necesidad de ready(), así que puedes omitir por completo el registro de handlers para compradores a los que una regla no aplica.

On cart update

El script de On cart update se ejecuta cada vez que el carrito cambia. Es un envoltorio bloqueado alrededor de una suscripción a cart_updated, así que solo editas el cuerpo, y tu código recibe el cart actualizado. Este slot es para reglas que deben reevaluarse en cada cambio del carrito. Un umbral de regalo gratis es el caso clásico (gasta $75 y obtén un tote gratis) porque la respuesta depende del contenido actual y nada más puede avisarte cuando cambia:

Mantener el carrito en un estado deseado

La línea if (shouldHaveGift === hasGift) return; es lo que hace esto seguro, y se generaliza a todo script que mantiene el carrito en un estado deseado. Este slot tanto reacciona a los cambios del carrito como los provoca, así que cada addItem o removeItem vuelve a entrar en él. Describe el estado que quieres, compáralo con el estado que tienes y retorna temprano cuando ya coinciden, de modo que el handler converja tras una sola pasada en lugar de entrar en bucle. Consulta las dos reglas para ver la versión sin protección que debes evitar y por qué el payload es de solo lectura. En una tienda más lenta también vale la pena mantener un flag de operación en curso a nivel de módulo, para que dos cambios rápidos no puedan iniciar ambos un add antes de que el primero termine.
cart_updated se dispara solo en cambios posteriores a la primera carga (temporización de eventos), así que un script en este slot no reconciliará un carrito que ya califica cuando la página se carga. Para una versión que maneja ambos casos, suscríbete a cart_loaded y cart_updated con la misma función desde el slot de Initialization. Consulta Agregar automáticamente un regalo gratis en un umbral.

Cuando un script falla

Cada slot se ejecuta en su propio sandbox, así que un script de Initialization roto no puede impedir que On cart update se ejecute, y ninguno puede romper el carrito en sí. Dentro de un slot, sin embargo, la ejecución se detiene en el primer error. Todo lo que está debajo de esa línea se omite, lo que significa que cualquier configure, events.on o hooks.register* más abajo nunca se registra. Esa es la explicación habitual de “mi handler nunca se dispara” cuando el código parece correcto. El carrito indica la línea que falla en la consola del navegador, y cada slot se ejecuta bajo su propio nombre de archivo (aftersell-cart-init.js y aftersell-cart-cart-update.js), así que puedes abrir cualquiera desde el panel Sources de DevTools y establecer breakpoints. Consulta Depuración para ver los mensajes exactos, y para el canal de depuración que captura fallos de hooks que se mantienen fuera de la consola. Como cart_loaded se reproduce para suscriptores tardíos, el orden de registro nunca importa. La estructura más segura es registrar todo primero y hacer el trabajo arriesgado dentro de los handlers, donde un throw queda aislado a ese handler.

Adónde ir después

  • Cart SDK: los scripts personalizados son la forma de ejecutar código del SDK. Consulta las referencias de configure, events, actions y hooks para ver la superficie completa, el objeto cart para la forma de lo que reciben los handlers, y los casos de uso para snippets listos para usar.
  • Bloques de código personalizado: para agregar marcado al carrito. Ten en cuenta que el modo HTML del bloque Custom code no ejecuta JavaScript; usa scripts personalizados (o el modo React del bloque) para la lógica.