Google Tag Manager (GTM) es una de las formas recomendadas para desplegar el script de tracking de Positive User en tu sitio web. Una vez que GTM entrega el script, Positive User empieza a rastrear a los visitantes, crea perfiles de contacto y te permite enriquecer esos perfiles con la data que importa para tu negocio.
Esta guía cubre tres aspectos:
La instalación del script de implementación básico;
La identificación de los contactos mediante un Contact ID;
La ampliación de la configuración con datos adicionales del contacto y callbacks.
Un workspace activo de Positive User.
La clave del workspace y la información del subdominio (desde «configuración del espacio de trabajo» → «API & Integrations» → sección «Setup & Integrations»).
Acceso al contenedor de GTM instalado en tu sitio web.
Una estrategia de cookies/consentimiento ya definida.
Si tu sitio utiliza una Content Security Policy, asegúrate de que los dominios de Positive User están en la lista blanca.
El script de implementación define un objeto de configuración (window.civchat) y luego carga «widget.js». Añadirlo mediante GTM significa que puedes desplegarlo, actualizarlo o pausarlo sin volver a tocar el código del sitio web.
Obtén la clave del workspace y el subdominio
En tu workspace de Positive User, ve a «configuración del espacio de trabajo» → «API & Integrations» → «Setup & Integrations» para encontrar la clave del workspace, y anota el subdominio de tu workspace (por ejemplo, yourapp.user.com).
Crea la etiqueta HTML personalizada en GTM
Inicia sesión en tu contenedor de GTM y ve a «Tags» → «New» → «Tag Configuration» → «Custom HTML» y pega el script de abajo. Reemplaza YOUR_KEY con la clave del workspace del paso 1, y yourapp.user.com con el subdominio de tu workspace:
<script data-cfasync="false" type="text/javascript">
window.civchat = {
apiKey: 'YOUR_KEY'
};
</script>
<script data-cfasync="false" src="https://yourapp.user.com/widget.js"></script>
Configura el Activador en el contenedor de GTM
En «Triggering», elige el activador que se ajuste a tu configuración de consentimiento; normalmente es un evento «cookie_consent_update» (o su equivalente). De esta forma, el script solo se carga después de que el visitante haya aceptado las cookies. Si no tienes una capa de consentimiento, «All Pages» sirve como punto de partida.
Guarda, previsualiza, publica
Nombra la etiqueta (por ejemplo, «Positive User - Tracking Script»), haz clic en «Save» y luego ejecuta el modo «Preview» de GTM para confirmar que la etiqueta se activa y el widget se carga. Una vez verificado, envía y publica el contenedor de GTM.
Consejo: para comprobar si el script está completamente cargado en una página, abre la consola del navegador y ejecuta
typeof UE === 'object' && typeof userengage === 'function'. Si devuelve true, Positive User está listo.
De forma predeterminada, Positive User rastrea a los visitantes de manera anónima mediante una cookie (__ca__chat). Para convertir a un visitante anónimo en un contacto identificado —y mantener su historial coherente entre dispositivos y sesiones— pasa un Contact ID a través del campo (atributo) «user_id» en «window.civchat».
Cómo elegir el Contact ID adecuado
El valor que uses como Contact ID depende de cómo tu negocio identifique a las personas. No hay una única elección correcta; debe ser un identificador estable y único que puedas pasar de forma coherente en todos los puntos de contacto. Las tres opciones más habituales son:
ID interno de base de datos: la opción más estable, ya que no cambia nunca aunque el contacto actualice su email. Es la que se usa en los ejemplos de este artículo.
Email en minúsculas: sencillo de implementar y legible en el workspace, pero está vinculado a la dirección de email actual del contacto.
Hash SHA-256 del email en minúsculas: la misma unicidad que el email, pero sin que pasen datos personales sin procesar por GTM ni por las variables del navegador.
Lee más sobre los IDs en nuestro artículo. [LINK]
Elige una estrategia y mantenla en todo tu sitio y en todos los entornos. Cambiar el formato del Contact ID más adelante puede provocar perfiles de contacto duplicados o una pérdida de continuidad en el tracking.
El Contact ID debe estar disponible cuando se define «window.civchat», es decir, antes de que se cargue «widget.js». El enfoque estándar es leerlo del dataLayer que tu sitio rellena para los contactos con sesión iniciada, y luego asignarlo al objeto «civchat» de forma condicional.
Localiza el Contact ID en tu dataLayer
En la mayoría de las plataformas de e-commerce (Magento, Shopify, WooCommerce, PrestaShop, etc.), el dataLayer ya está rellenado con información sobre el cliente con sesión iniciada, incluyendo un ID de cliente, email y campos básicos del perfil. No necesitas escribir JavaScript por tu cuenta; solo necesitas saber qué clave del dataLayer contiene el valor que quieres usar como Contact ID.
Para comprobar qué está disponible:
Abre GTM y haz clic en «Preview» en la parte superior derecha.
Introduce la URL de tu sitio web e inicia sesión como cliente de prueba en la ventana de previsualización.
En el Tag Assistant de GTM, abre la pestaña «Data Layer» en cualquier evento.
Revisa las entradas buscando un objeto que contenga información del cliente o del usuario. Nombres de clave habituales son «visitorId», «user_id», «customerId» o similares.
Si el Contact ID no está en tu DataLayer: contacta con tu desarrollador o con el administrador de la plataforma y pídeles que envíen un identificador de cliente estable al dataLayer para los usuarios con sesión iniciada. Es un cambio pequeño del lado de la plataforma y es un requisito habitual para cualquier herramienta de tracking o personalización integrada mediante GTM.
Crea o reutiliza una variable dataLayer en GTM
En GTM, ve a «Variables» y comprueba si ya existe una variable para tu ID de cliente; en contenedores configurados por una agencia o para una integración de analítica existente, suele estar. Busca variables del tipo «Data Layer Variable» que apunten a claves como «customer_id» o «user_id». Si ya hay una, puedes reutilizarla y saltar al siguiente paso.
Si aún no existe, ve a «Variables» → «New» → «Data Layer Variable» y crea una. En el campo «Data Layer Variable Name», introduce el nombre exacto de la clave que encontraste en tu dataLayer (por ejemplo, «customer_id»). Nombra la variable con algo reconocible, como «DLV - user_id».
Actualiza la etiqueta
Edita la etiqueta Custom HTML y asigna el Contact ID de forma condicional, de manera que solo se añada cuando el visitante haya iniciado sesión realmente:
<script data-cfasync="false" type="text/javascript">
var civchatConfig = {
apiKey: 'YOUR_KEY'
};
if ({{DLV - user_id}}) {
civchatConfig.user_id = {{DLV - user_id}};
}
window.civchat = civchatConfig;
</script>
<script data-cfasync="false" src="https://yourapp.user.com/widget.js"></script>
Cuando «user_id» está presente, Positive User lo utiliza como identificador principal. Si el ID ya existe en tu workspace, el tracking se cambia al perfil de ese contacto; si no, el ID se asigna a la sesión anónima actual y se crea un nuevo contacto.
Una vez identificado el contacto, puedes enriquecer su perfil con atributos adicionales, es decir, los campos de data almacenados en el perfil de contacto. Pasa esos valores en el nivel raíz del objeto de configuración civchat, junto a «user_id»:
<script data-cfasync="false" type="text/javascript">
var civchatConfig = {
apiKey: 'YOUR_KEY'
};
if ({{DLV - user_id}}) {
civchatConfig.user_id = {{DLV - user_id}};
civchatConfig.email = {{DLV - user_email}};
civchatConfig.first_name = {{DLV - user_first_name}};
civchatConfig.last_name = {{DLV - user_last_name}};
civchatConfig.phone_number = {{DLV - user_phone}};
// Custom attributes go at the same level
civchatConfig.plan_type = {{DLV - user_plan}};
}
window.civchat = civchatConfig;
</script>
<script data-cfasync="false" src="https://yourapp.user.com/widget.js"></script>
Algunas cosas a tener en cuenta:
Atributos estándar vs. personalizados: los atributos estándar (como «Email», «Phone number», «Gender», «Status») los reconoce Positive User automáticamente. Los atributos personalizados (como «Plan type») deben existir ya en el workspace; créalos con antelación. (Consulta «Cómo crear un atributo personalizado»)
El formato importa: elige siempre un tipo de atributo adecuado, ya que define las posibilidades de filtrado posteriores. Para la lista completa de reglas de formato, consulta la documentación para desarrolladores o el artículo «Qué es un atributo».
Los valores sobrescriben los datos existentes: cualquier atributo que pases aquí reemplazará el valor ya almacenado en el perfil de contacto. Pasa atributos solo cuando tengas un valor real; por eso los mantenemos dentro del bloque «if» anterior.
Los callbacks permiten que tu código reaccione a lo que ocurre dentro del widget de Positive User; por ejemplo, cuando el widget termina de cargarse o cuando llega un nuevo mensaje de chat. Se definen como funciones dentro del mismo objeto de configuración «civchat», junto a «apiKey» y «user_id».
Callbacks disponibles
El SDK de Positive User expone los siguientes callbacks:
onLoad: se ejecuta una vez que el script del widget y sus recursos han terminado de cargarse. Útil para secuenciar otras etiquetas de GTM que dependan de que Positive User esté listo.
onMessage: se ejecuta cada vez que se recibe un mensaje de chat. El objeto «message» incluye una flag «isAdmin» que indica si el mensaje proviene de un miembro del equipo/automatización (true) o del contacto (false).
onOpen / onClose: se ejecutan cuando el widget de chat se expande o se minimiza.
onPayloadReceived: se ejecuta cuando el widget recibe un payload del módulo de automatización «Send Code».
Para la referencia completa, consulta la documentación para desarrolladores.
El script de abajo muestra una configuración completa que combina todo lo visto en esta guía: el callback onLoad, el Contact ID, el email y datos adicionales del contacto. Esta es la versión que puedes usar como punto de partida en producción:
<script data-cfasync="false" type="text/javascript">
var civchatConfig = {
apiKey: 'YOUR_KEY',
// Notify GTM once the widget is fully loaded
onLoad: function() {
dataLayer.push({ event: 'Positive User - Widget Ready' });
}
};
// Identify the contact and pass their data only when logged in
if ({{DLV - user_id}}) {
civchatConfig.user_id = {{DLV - user_id}};
civchatConfig.email = {{DLV - user_email}};
civchatConfig.first_name = {{DLV - user_first_name}};
civchatConfig.last_name = {{DLV - user_last_name}};
civchatConfig.phone_number = {{DLV - user_phone}};
civchatConfig.plan_type = {{DLV - user_plan}};
}
window.civchat = civchatConfig;
</script>
<script data-cfasync="false" src="https://yourapp.user.com/widget.js"></script>
En GTM, puedes crear después un activador «Custom Event» que escuche «Positive User - Widget Ready» y usarlo en cualquier etiqueta que necesite que el SDK de Positive User esté disponible.
GTM es cómodo, pero añade una capa adicional entre tu sitio web y Positive User. Si el script no parece activarse:
Comprueba el modo «Preview» de GTM para confirmar que la etiqueta se ejecuta realmente en la página.
Asegúrate de que el contenedor de GTM está publicado, no solo guardado.
Revisa la consola del navegador en busca de errores de JavaScript que puedan impedir la ejecución del script.
Confirma que los bloqueadores de anuncios, las herramientas de gestión del consentimiento o tu CSP no están bloqueando GTM ni el dominio de Positive User.
Verifica que las variables del dataLayer se resuelven correctamente en el modo Preview; si una variable está vacía, el campo correspondiente en «civchat» también lo estará.
Cómo configurar un widget de chat [LINK]
Concepto de IDs [LINK]