Integración con JavaScript Puro (Vanilla)

En esta sección explicaremos cómo puedes integrar tu sitio web embebiendo el script de Metricalp en tu página web. Todas las demás bibliotecas de integración utilizan este método internamente.

Primero que todo, necesitas tu tid (también conocido como Tracker ID). Puedes obtenerlo desde la pantalla Configuración del Tracker / Insertar & Compartir.

Después de obtener tu tid, estás listo para insertar el script de Metricalp en tu página web. Debes colocar el siguiente fragmento de código en la parte superior de cada página. No olvides reemplazar YOUR_TID con tu tid.

<script src="https://cdn.metricalp.com/event/metricalp.js" data-allow-localhost="true" data-tid="YOUR_TID" defer></script>

Eso es todo. Metricalp comenzará automáticamente a recopilar eventos de tu sitio web después de esta línea de código. ¿Qué tan genial es eso, verdad? 🫡

Ahora profundicemos en los detalles. El script anterior tiene el atributo `defer`, lo que significa que el script no bloqueará la carga de la página, pero la ejecución del script ocurrirá antes que cualquier otro script en la página que venga después de este script. Sin embargo, si deseas cargar el script de manera asíncrona, puedes eliminar el atributo `defer` y cambiarlo por el atributo `async`. En este caso, aunque el script se cargará de manera asíncrona, podría haber un problema si deseas desencadenar un evento inmediatamente después de la carga de la página, ya que es posible que la carga del script no se complete antes de que se dispare el evento. Para solucionar esto y hacer que todo el proceso sea más fluido, podemos agregar una línea más justo encima de nuestro script:

<script>window.metricalp = window.metricalp || {queue: [], event: function(e){this.queue.push(e)}}</script>
<script src="https://cdn.metricalp.com/event/metricalp.js" data-allow-localhost="true" data-tid="YOUR_TID" async></script>

Ahora hemos reemplazado `defer` con `async` y hemos agregado una línea más justo encima de la línea de nuestro script. Garantizamos que cada evento se agregará a la cola independientemente del tiempo de carga de nuestro script principal. Porque ahora estamos recopilando nuestros eventos en una cola hasta que nuestro script se carga, y luego dispara todos los eventos en la cola. Por lo tanto, puedes disparar eventos inmediatamente después de cargar una página. Recomendamos este segundo fragmento de código en general (lo usamos en nuestras bibliotecas de integración) porque es más eficiente, seguro y ligero para la carga de la página.

Al proporcionar el atributo data-tid, hemos proporcionado otro atributo de datos data-allow-localhost="true" porque de manera predeterminada Metricalp nunca recopila eventos desde localhost (127.0.0.1) para ahorrar en tu cuota de uso. Sin embargo, si estás integrando por primera vez, puedes permitir eventos de localhost con fines de prueba. Una vez que termines tu integración, puedes eliminar este atributo antes de publicar tu sitio web en producción. Puedes encontrar información detallada en permitir localhost & excluirme docs.

Hay algunas opciones más para personalizar los comportamientos del script de Metricalp, puedes encontrar todas en la referencia de la API.

De forma predeterminada, Metricalp comienza automáticamente a recopilar eventos de screen_view (puede deshabilitarse con la opción data-disable-auto-route-catch, consulta la referencia de la API para más detalles). Sin embargo, si deseas disparar un evento manualmente (screen_view o cualquier evento personalizado), puedes usar la función window.metricalp.event o atributos de datos personalizados. Aprenderás más sobre esto en la sección Eventos Personalizados & Props. Si estás disparando eventos personalizados, tu script debe estar cargado antes de que dispares el evento. Generalmente, este es el caso en los dos fragmentos de código anteriores. Pero, en el primer escenario, si disparas el evento antes de la llamada al script con defer, puede haber un fallo. Aunque esto es muy raro, puedes usar el segundo fragmento de código para estar 100% seguro.

Además, a veces es posible que desees adjuntar automáticamente algunas propiedades personalizadas a algunos (o todos) los eventos. Puedes configurar esto con el segundo enfoque y definir estas propiedades que se adjuntan automáticamente en el objeto sharedCustomProps como:

<script>
      window.metricalp = window.metricalp || {
          queue: [],
          sharedCustomProps: {
            _global: { custom_prop1: "Test1" },
            screen_view: {
              logged_in: 'not_logged_in',
              custom_prop2: "Test2",
            }
          },
          event: function(e){this.queue.push(e)}
      }
</script>
<script src="https://cdn.metricalp.com/event/metricalp.js" data-allow-localhost="true" data-tid="YOUR_TID" async></script>

_global es una clave especial para adjuntar algunas propiedades a todos los eventos. Ten en cuenta que, si adjuntas una propiedad personalizada mediante un alias, ese alias debe definirse para los eventos objetivo en la Configuración del Tracker; de lo contrario, se ignorará para ese evento. Siempre puedes usar la sintaxis de custom_prop1 para cualquier evento. Nuevamente, puedes obtener información más detallada sobre sharedCustomProps en la sección Eventos Personalizados & Props. Si estás utilizando la biblioteca React para integrar Metricalp con React / NextJS, puedes consultar la documentación de React y NextJS para aprender cómo puedes configurar sharedCustomProps en tu aplicación React / NextJS.