Referencia de la llave

Todo lo que sabe hacer el script: atributos, eventos que mandas tú, eventos que manda solo y variantes.

Atributos del script

Todo se configura con atributos del propio <script>. No hay objeto de configuración ni fichero aparte.

Atributo	Obligatorio	Qué hace
`data-domain`	Sí	El dominio del piso. Admite una lista separada por comas para mandar el mismo evento a varios pisos.
`data-api`	No	Endpoint alternativo. Se usa cuando sirves el evento desde tu propio dominio.
`data-exclude`	No	Rutas que no se trackean, con comodines * y **. Se aplica a todos los eventos, no solo a los pageviews.Necesita la variante exclusions
`data-include`	No	Le da la vuelta: solo se trackea lo que casa con estas rutas.Necesita la variante exclusions
`data-file-types`	No	Reemplaza la lista de extensiones que cuentan como descarga.Necesita la variante file-downloads
`data-add-file-types`	No	Amplía la lista por defecto en vez de reemplazarla.Necesita la variante file-downloads
`data-event-*`	No	Cada data-event-<clave> se convierte en una prop de todos los pageviews.Necesita la variante pageview-props

Eventos custom

Un timbre es cualquier cosa que quieras contar: un alta, un click en «contactar», una compra. Hay dos formas de tocarlo.

Desde JavaScript

Pon la cola antes del <script src> y podrás llamar a pisito() desde el primer milisegundo, aunque la llave todavía no haya cargado.

<script>
  window.pisito = window.pisito || function () {
    (window.pisito.q = window.pisito.q || []).push(arguments);
  };
</script>
<script defer data-domain="example.com" src="https://pisi.to/js/llave.js"></script>

html

Llamar al timbre

El primer argumento es el nombre. Las props son opcionales: máximo 30 claves, y solo cadenas, números o booleanos.

window.pisito("Alta", { props: { plan: "pro" } });

// Con la variante revenue:
window.pisito("Compra", {
  props: { plan: "pro" },
  revenue: { currency: "EUR", amount: "29.90" },
});

Desde el HTML

Con la variante tagged-events puedes declarar el evento en las clases del elemento. La escucha va delegada en document, así que funciona con elementos que aparecen después. El + es un espacio.

<button class="pisito-event-name=Alta+pro pisito-event-plan=pro">
  Empezar
</button>

html

Los 404

Pon esta línea en tu plantilla de página no encontrada y sabrás qué enlaces rotos anda pisando la gente.

window.pisito("404", { props: { path: location.pathname } });

Nombres reservados

pageview y engagement los emite el script y la API pública los rechaza, para que nadie infle las métricas base sin querer. La excepción es la variante manual, donde pisito('pageview') es justo el punto de entrada. 404, Outbound Link: Click, File Download y Form: Submit sí se aceptan desde fuera.

Eventos automáticos

Estos los manda la llave sin que hagas nada, salvo que la variante diga lo contrario.

Evento	Cuándo	Variante
`pageview`	Al cargar la página, al cambiar de ruta en una SPA y al volver desde el bfcache.	Base
`engagement`	Cuando la pestaña se oculta o se cierra. Lleva el tiempo con la página visible y el scroll máximo.	`engagement`
`Outbound Link: Click`	Al pinchar un enlace a otro host. Prop: url.	`outbound-links`
`File Download`	Al pinchar un enlace con una extensión de la lista de descargas. Prop: url.	`file-downloads`

Variantes

Cada variante es un sufijo en el nombre del fichero, y se pueden combinar en este orden. La base pesa 873 B gzip; solo pagas lo que uses.

Sufijo	Qué añade	Tamaño gzip
`hash`	El fragmento cuenta como parte de la ruta y hashchange dispara pageview. Para routers de hash.	874 B
`outbound-links`	Evento «Outbound Link: Click» al pinchar un enlace a otro host.	1003 B
`file-downloads`	Evento «File Download» con 27 extensiones por defecto, configurables.	1146 B
`tagged-events`	Eventos declarados en las clases del HTML, con delegación en document.	1100 B
`manual`	Apaga todos los disparadores automáticos. Los pageviews los mandas tú.	743 B
`exclusions`	Activa data-exclude y data-include con comodines.	1052 B
`pageview-props`	Props fijas para todos los pageviews, declaradas en el propio script.	1004 B
`revenue`	Añade el campo de ingresos a los eventos custom.	885 B
`engagement`	Tiempo visible y scroll máximo al salir de la página.	1141 B

Combinarlas

Los sufijos van en el orden de la tabla. llave.hash.outbound-links.js existe, igual que las otras 511 combinaciones. script.js es un alias de llave.js por si buscas lo estándar.

<script defer data-domain="example.com"
        src="https://pisi.to/js/llave.hash.outbound-links.js"></script>

html