Scripts en la tienda

​

Qué es y qué no es

• Es código tuyo, servido desde tu dominio, que se carga en las páginas públicas de la tienda: inicio, catálogo, ficha de producto, carrito, búsqueda, páginas y contacto.
• No es una forma de tocar el checkout. Nunca cargamos scripts de apps en el checkout ni en la confirmación de la compra, en «Mi cuenta», en el login ni el registro, en la recuperación de clave, en el botón de arrepentimiento, ni en la vista previa del editor de la tienda. Ver «Rutas excluidas».
• No es una API: no recibís datos de clientes ni podés escribir en Commercy desde la tienda. Lo que sabe tu script es lo que ve el visitante, más el contexto de window.Commercy (más abajo).
• En esta versión sólo se aceptan scripts necesarios para la función que el comercio instaló. Ver la sección «Qué cuenta como necesario».

​

Las tres llaves

1. Commercy habilitó los scripts en tu app. La capacidad la prende el equipo de Commercy al aprobar tu app, y la puede apagar en cualquier momento.
2. El comercio concedió el scope storefront_scripts al instalar tu app (ver Scopes y permisos). El comercio ve un aviso destacado: «Agregar código a tu tienda online».
3. La declaración está aprobada. Si tu app ya está publicada, lo que cambiás pasa por revisión y mientras tanto sigue corriendo la versión aprobada.

​

Cómo declarar un script

{
  "storefrontScripts": [
    {
      "handle": "chat-widget",
      "name": "Botón de chat",
      "src": "https://cdn.tuapp.com/widget.v3.js",
      "integrity": "sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC",
      "loading": "interaction",
      "consent": "necessary"
    }
  ]
}

​

Dónde puede vivir el archivo

• Tiene que ser https.
• Tiene que estar en el mismo dominio que la URL de tu app (appUrl): cdn.tuapp.com sirve si tu app está en app.tuapp.com. Si tu appUrl no tiene un dominio propio, no podemos validar el script.
• No puede ser un dominio de Commercy ni el dominio de una tienda.
• No puede llevar usuario ni contraseña en la URL, ni usar un puerto menor a 1024, ni apuntar a una IP privada.

​

Hash SRI

echo "sha384-$(openssl dgst -sha384 -binary widget.v3.js | openssl base64 -A)"

​

El archivo se sirve así

• Sin redirects. Una respuesta 301 o 302 rompe la verificación y es una forma de cambiar el contenido sin que nos enteremos. La src tiene que responder 200 directo.
• Con CORS. La respuesta lleva Access-Control-Allow-Origin: *. Sin ese header, el navegador no ejecuta el script (cargamos con crossorigin="anonymous").
• Con Content-Type: text/javascript.

​

Cómo actualizar sin romper

1. Publicá el archivo nuevo en una URL nueva (widget.v4.js).
2. Dejá vivo el archivo viejo (widget.v3.js): las tiendas siguen cargándolo hasta que se apruebe el cambio.
3. Calculá el hash del nuevo, y cambiá src e integrity en el portal. Si tu app está publicada, el cambio pasa por revisión y se aplica al aprobarlo.
4. Cuando el cambio esté aprobado y pasaron unos minutos, ya podés retirar el archivo viejo.

​

Cuándo se carga

• interaction (por defecto): después de la primera interacción del visitante (un toque, una tecla, un scroll o un movimiento de la rueda). Si el visitante no interactúa, el script no se carga. Es lo mejor para el rendimiento de la tienda.
• idle: cuando termina de cargar la página y el navegador está libre. Se puede usar, pero la revisión te va a pedir que justifiques por qué no alcanza con interaction.

​

Qué cuenta como necesario

​

window.Commercy

​

Eventos

​

Ejemplo

// commercy-script-example
(function () {
  'use strict';
  if (!window.Commercy) return;
  var C = window.Commercy;

  function send(name, data) {
    // Mandá lo que necesites a tu backend. Acá sólo lo mostramos.
    console.log('[mi-widget]', name, data);
  }

  C.on('page_viewed', function (p) {
    send('page', { type: p.type, path: p.path, store: C.store.domain });
  });

  C.on('product_viewed', function (p) {
    send('product', { id: p.productId, price: p.price, currency: p.currency });
  });

  C.on('product_added_to_cart', function (p) {
    send('add', { id: p.productId, quantity: p.quantity });
  });

  C.on('checkout_started', function (cart) {
    send('checkout', { items: cart.itemCount, total: cart.subtotal, currency: cart.currency });
  });
})();

​

Rutas excluidas

​

Política de comportamiento

• Prohibido leer campos de formularios, y leer o escribir el localStorage o las cookies de Commercy (auth-storage, cart-id).
• Prohibido leer o modificar el DOM de las rutas excluidas.
• Prohibido pedir credenciales o datos de pago.
• Obligatorio envolver tu código en un closure (como en el ejemplo), no depender de jQuery ni del JavaScript del tema de la tienda, y no usar document.write.
• Cargá lo mínimo: la revisión mide el Lighthouse mobile de una tienda y tu script no puede empeorarlo en más de 10 puntos.

​

Cómo probar

1. Declará el script y pedí el scope storefront_scripts.
2. Pedile a soporte que habilite los scripts en tu app, para poder probarlos en borrador. Pasale el id de tu app.
3. Instalá la app en tu tienda de desarrollo aceptando el scope.
4. Abrí la tienda, interactuá con la página (un scroll alcanza) y mirá la consola.

​

Errores de validación

​

Ejemplos

• whatsapp-widget-script: un widget de WhatsApp para la tienda.
• installments-banner-script: un banner de cuotas para la tienda.