@bacano/sdk 1.1.20 → 1.2.2

package/README.md

@@ -945,6 +945,10 @@ contains only browser-safe media metadata and a public Storage URL.
 
 GA4, Meta, and Microsoft Clarity are configured per website in Bacano and are
 disabled by default.
+An optional Google Tag Manager web container is also supported via
+`marketing.destinations.gtm.containerId`. It adds `bacano_*` browser events to
+the data layer without replacing native destinations or server conversions.
+See [GTM setup, limitations and duplication safeguards](./STOREFRONT_MARKETING.md#google-tag-manager-contenedor-web-opcional).
 The existing public-config request returns only active public destination IDs;
 provider secrets never reach the SDK. The runtime remains a no-op outside the
 website's canonical production domain.

package/STOREFRONT_FORMS.md

@@ -1,5 +1,12 @@
 # Formularios de websites
 
+Desde SDK 1.2.0, `BacanoForm` instrumenta interacciones mediante el provider
+global de marketing. Para modales montados ocultos, pasar `visible={open}`.
+Renderers personalizados usan `useBacanoFormTracking`. Leer la sección de
+interacciones en [STOREFRONT_MARKETING.md](./STOREFRONT_MARKETING.md) y los
+[ejemplos de migración](./skills/bacano-web/references/interactions.md).
+No añadir un segundo listener ni convertir aperturas en leads.
+
 Los formularios públicos de Bacano son definiciones tipadas y versionadas. El
 storefront decide dónde se muestran y cómo lucen; Bacano controla su estructura,
 estado y validaciones. La definición nunca contiene HTML ni JavaScript arbitrario.

package/STOREFRONT_MARKETING.md

@@ -6,9 +6,65 @@ identificadores, adaptadores ni llamadas directas a proveedores.
 
 ## Regla principal
 
+### Google Tag Manager (contenedor web opcional)
+
+En Bacano, la tarjeta Google Tag Manager permite guardar un ID `GTM-…`, validar
+que el script publicado sea accesible y activar o pausar la integración por sitio.
+Validar no comprueba propiedad del contenedor, etiquetas, consentimiento ni
+recepción de eventos: comprobar esto en Tag Assistant con el administrador del
+contenedor. No se solicitan secretos, HTML ni URLs de scripts personalizados.
+
+Requiere desplegar API/migración y actualizar `@bacano/sdk` en el storefront.
+El contrato público añade `marketing.destinations.gtm.containerId`; SDKs anteriores
+lo ignoran. Un sitio con configuración estática debe reconstruirse para incorporar
+cambios. No se modifica ni se publica automáticamente ningún contenedor de Google.
+
+El mismo `BacanoMarketingProvider` carga `gtm.js` una sola vez, conserva la cola
+`window.dataLayer` existente y respeta las barreras de dominio, preview y
+`measurementAllowed`, además de la carga diferida. No instalar otro snippet.
+Esta versión requiere JavaScript; no incorpora un iframe `noscript` ni GTM server-side.
+Pausar evita nuevas cargas con la configuración actualizada; no puede deshacer
+etiquetas de terceros ya ejecutadas en pestañas abiertas. Recargar para comprobar.
+
+Los eventos oficiales de navegador se publican con prefijo `bacano_`:
+
+```js
+{ event: "bacano_add_to_cart", bacano: {
+  schema_version: 1, event_name: "add_to_cart", event_id: "…",
+  currency: "COP", value: 50000,
+  items: [{ item_id: "product-variant-id", item_name: "Producto", quantity: 1 }]
+} }
+```
+
+Configurar activadores de evento personalizado `bacano_*` y variables de capa de
+datos como `bacano.event_name`, `bacano.value` y `bacano.items`. El objeto `bacano`
+se limpia antes de cada evento para no arrastrar artículos ni parámetros anteriores.
+Incluye URL saneada, parámetros de comercio e identificadores técnicos de
+interacciones; no copia datos de clientes, valores de formularios, atribución,
+títulos de página ni texto libre de búsqueda. Los eventos `search` no llevan el término.
+No emitir desde GTM `purchase`, `refund` u `order_placed` basándose en la página de
+gracias: siguen siendo autoritativos del servidor y no se publican en este puente.
+
+GA4, Meta y Clarity nativos permanecen sin cambios. **No repetir esos destinos o
+conversiones dentro del contenedor**. Esta fase no es un modo alternativo completo
+de medición ni realiza deduplicación entre proveedores y etiquetas configuradas
+externamente. El administrador de GTM puede ejecutar scripts con acceso a la página:
+otorgar acceso solo a personas de confianza y revisar cada publicación.
+El aviso de cookies informativo de Bacano no es un CMP y no autoriza las etiquetas;
+el responsable del contenedor debe configurar el consentimiento aplicable.
+
+CSP: permitir `https://www.googletagmanager.com` en `script-src`. Los destinos
+adicionales y Tag Assistant requieren revisar sus propios permisos de CSP; no
+habilitar comodines ni `unsafe-eval` globalmente para acomodar un contenedor.
+
+Referencias: [configuración de GTM](https://support.google.com/tagmanager/answer/14842164)
+y [contrato dataLayer](https://developers.google.com/tag-platform/tag-manager/datalayer).
+
+### Eventos comunes
+
 El storefront expresa hechos mediante `useMarketing().track()`. El SDK decide
-si la medición está activa, sanea la URL y adapta el evento a GA4, Meta y
-Microsoft Clarity. Nunca
+si la medición está activa, sanea la URL y adapta el evento a GA4, Meta,
+Microsoft Clarity y, si se configuró, GTM. Nunca
 se debe llamar directamente a `gtag`, `dataLayer`, `fbq`, Measurement Protocol
 o Conversions API.
 Clarity también se carga desde este runtime; no se instala su snippet de forma
@@ -120,8 +176,6 @@ Valores de `contactPlacement`:
 - `header`
 - `footer`
 - `contact_page`
-- `checkout`
-- `other` únicamente cuando ninguna ubicación canónica describe el contacto
 
 El campo es opcional, no acepta textos visibles ni valores libres y el runtime
 lo ignora cuando el evento no es `contact`. Una ubicación nueva debe añadirse
@@ -276,9 +330,9 @@ Antes de declarar un storefront listo:
 ## Checklist corto para agentes
 
 - [ ] Leí este contrato antes de instrumentar.
-- [ ] Uso únicamente `useMarketing().track()`.
+- [ ] Uso el runtime oficial mediante `track`, `useBacanoCta` y los formularios oficiales.
 - [ ] Uso `product_variant_id` como `itemId`.
-- [ ] Emito eventos después del éxito, no antes.
+- [ ] Cada evento representa su hecho: un intento no se presenta como éxito.
 - [ ] Instrumenté todos los contactos con método y ubicación.
 - [ ] Los contactos de producto incluyen item, cantidad y valor.
 - [ ] No emito conversiones autoritativas desde el navegador.
@@ -289,3 +343,104 @@ Antes de declarar un storefront listo:
 La guía de gobierno, persistencia y eventos autoritativos vive en
 `docs/websites/MARKETING_MEASUREMENT_STOREFRONTS_CHECKLIST.md` dentro del
 repositorio Bacano. Este archivo es el contrato distribuible para storefronts.
+
+## Interacciones y formularios — SDK 1.2.0
+
+Aplicable también a webs informativas y de servicios. No exige checkout ni
+configurar un proveedor ausente. Esta versión agrega instrumentación; no crea
+un dashboard de embudos dentro de Bacano ni publica configuraciones remotas.
+
+| Evento Bacano | GA4 | Meta | Clarity | Propietario y condición |
+| --- | --- | --- | --- | --- |
+| `cta_click` | `cta_click` | personalizado `cta_click` | `cta_click` | CTA pulsado, no hover |
+| `form_open` | `form_open` | personalizado `form_open` | `form_open` | Formulario pasa a estar presentado; no implica inicio |
+| `form_start` | `form_start` | personalizado `form_start` | `form_start` | Primera respuesta introducida/seleccionada por la persona |
+| `form_step_complete` | `form_step_complete` | personalizado `form_step_complete` | `form_step_complete` | Paso validado y avance, una vez por paso/diligenciamiento |
+| `form_submit_attempt` | `form_submit_attempt` | personalizado `form_submit_attempt` | `form_submit_attempt` | Intento de envío final, incluso si la validación lo rechaza |
+| `form_submit_error` | `form_submit_error` | personalizado `form_submit_error` | `form_submit_error` | Fallo de ese intento; categoría segura |
+| `form_submit_success` | `form_submit_success` | personalizado `form_submit_success` | `form_submit_success` | Resultado oficial `accepted: true` y UUID de respuesta |
+
+GA4 y Meta reciben solamente `form_key`, `cta_id`, `placement`, `step_key`
+cuando corresponden y `error_category` para errores. Los identificadores son
+técnicos, estables, 1–64 caracteres, patrón `[a-z][a-z0-9_-]*`; no labels,
+respuestas, emails ni teléfonos. `cta_click` exige `ctaId`; los eventos de
+formulario exigen `formKey`; completar un paso exige `stepKey`. Categorías:
+`validation`, `network`, `rejected`, `unavailable`. Parámetros inválidos
+rechazan el evento completo. Clarity recibe solo el nombre, no esos parámetros.
+GA4 recibe además URL saneada, `event_id`, destino explícito y debug según
+configuración. Meta recibe la misma identidad mediante `eventID`, dirigida
+solo al píxel configurado, no a todos los píxeles de la página.
+
+`BacanoForm` instrumenta apertura, primera edición, pasos, intento y resultado.
+Un formulario montado dentro de un contenedor oculto necesita `visible={open}`;
+no se intenta adivinar CSS o extraer textos del DOM. Siempre visible significa
+presentado en la página, no una impresión garantizada dentro del viewport.
+Los cambios programáticos de `values` no cuentan como primera edición.
+Un renderer personalizado usa `useBacanoFormTracking` y conserva su propia UI.
+Los CTA usan `useBacanoCta`; no instrumentar el mismo clic también con `track`.
+Ver [ejemplos y migración](./skills/bacano-web/references/interactions.md).
+
+### Persistencia, antispam y conversiones
+
+`accepted: true, responseId: null` conserva el mensaje genérico de aceptación,
+pero **no** emite éxito. No revelar el motivo al visitante. Un `onSubmit`
+personalizado que devuelve `void` conserva su comportamiento visual, pero no
+demuestra persistencia para medición; devolver el resultado de
+`client.forms.submitResponse()` cuando se usa ese flujo.
+
+Una respuesta guardada no prueba que se haya creado un lead nuevo. Esta
+integración **no emite `generate_lead` ni `Lead`**, tampoco para `CAPTURE_LEAD`:
+la resolución de identidad pertenece al backend y su resultado no forma parte
+del contrato público. Una futura conversión autoritativa debe definirse ahí,
+con identidad compartida si se envía también por navegador; no inferirla de
+este evento de interacción. No duplicar la captura del lead por campaña.
+
+### Deduplicación y atribución
+
+- El runtime descarta repeticiones de `(eventName, eventId)` entre sus últimas
+  1.000 identidades. No es una garantía entre recargas ni un acuse del proveedor.
+- CTA: el helper agrupa doble clic del mismo botón dentro de 400 ms, sin
+  impedir su acción. Un clic posterior es legítimo y recibe otra identidad.
+- Cerrar/reabrir genera otra apertura; no otro inicio mientras el formulario
+  permanezca montado. Desmontar/montar inicia otro diligenciamiento. Un render
+  o la repetición de efectos de Strict Mode no equivalen a reabrir.
+- Un envío pendiente no acepta otro simultáneo. Un reintento tras error genera
+  otro intento analítico, pero conserva la `idempotencyKey` de persistencia.
+  Éxito usa el UUID de respuesta para no duplicarlo dentro del runtime.
+- Se reutiliza la atribución existente: `utm_content` se conserva como
+  `content`, junto a las demás UTM. Cada interacción recaptura la ubicación
+  usando ese mismo almacenamiento; navegación sin UTM no borra el origen.
+  No se copian click IDs de un proveedor a parámetros personalizados de otro.
+- Las respuestas conservan atribución en Bacano; CTA/aperturas se envían a los
+  proveedores, no se guardan como una secuencia propia en Bacano. No prometer
+  seguimiento completo entre dispositivos, navegadores o bloqueadores.
+
+GA4 puede medir formularios automáticamente. Al adoptar este contrato, revisar
+y desactivar **Form interactions** de Enhanced Measurement para que `form_start`
+no tenga dos propietarios. El SDK no cambia esa configuración de la cuenta.
+No tratar el `form_submit` automático como evidencia de guardado.
+[Referencia oficial de GA4](https://support.google.com/analytics/answer/9216061?hl=en).
+
+### Privacidad y diagnóstico
+
+El único `BacanoMarketingProvider` acepta `measurementAllowed={false}` cuando
+el gestor de consentimiento del sitio todavía no permite medir. No carga
+scripts, no captura atribución nueva ni emite eventos en ese estado. Este
+interruptor no sustituye el gestor de consentimiento, no borra almacenamiento
+previo ni descarga scripts de terceros que ya estaban cargados. Tampoco
+autoriza publicidad por el hecho de aceptar términos de compra.
+
+Config desactivada, dominio distinto, preview o proveedores ausentes son no-op.
+Diagnósticos: `MARKETING_DISABLED`, `MEASUREMENT_NOT_ALLOWED`,
+`DOMAIN_NOT_ALLOWED`, `PROVIDER_NOT_CONFIGURED`, `PREVIEW_DISABLED`,
+`PUBLIC_CONFIG_UNAVAILABLE`, `INVALID_INTERACTION`, `INVALID_EVENT`,
+`SCRIPT_LOAD_FAILED`, `EVENT_DISPATCH_FAILED`, `EVENT_DISPATCHED`.
+Un fallo de descarga no permite distinguir por sí solo bloqueador, CSP o red.
+`EVENT_DISPATCHED` significa únicamente pasado al adaptador; no recepción
+externa. Ni un callback de diagnóstico que falle puede bloquear el formulario.
+
+No incluir PII en rutas ni en valores UTM: sanear una URL no identifica toda la
+información personal que el sitio pudiera introducir en su ruta. No evadir
+Core Setup/Protected Data Mode o consentimiento mediante campos alternativos.
+La coherencia entre píxel y CAPI se revisa del lado Bacano; no exponer tokens
+ni inventar un segundo destino público para intentar corregirla en el sitio.