Automatización de la documentación en Google Tag Manager

En un proyecto de analítica, una de las cosas que personalmente más me cuesta, y que sospecho es algo común, es documentar. Da igual el qué, el hecho de documentar me cuesta. Ya sean queries simples, modelados de datos, un reporte con su diccionario de métricas y gráficos o, en el caso que nos ocupa, una guía de implementación.

Y en las guías de implementación en concreto sospecho que es algo común porque a lo largo de los años no han sido pocas las veces que me han faltado. Al entrar en un Google Tag Manager, para abordar una auditoría o al entrar en un proyecto o simplemente por hacer el favor, he tenido que estar las primeras horas montando un puzzle de etiquetas, activadores y variables. 

Qué se activa con qué y dónde en la web, por qué un evento se envía correctamente a GA4 pero varios parámetros están vacíos, propiedades de usuario que cambian cada vez que se navega a una nueva parte de la web, capas y capas de apaños unos sobre otros… Un infierno. Especialmente un infierno por el que yo también he hecho pasar a compañeros o he hecho pasar a mi yo del futuro.

Es por eso que en su día me puse a trastear con la API de Google Tag Manager para hacer más fácil la documentación. Y de ahí este artículo. Un proceso que yo creo sencillo pero que ahorra mucho tiempo y potenciales disgustos.

Requisitos previos

Voy a dar por hecho que se dominan ciertos conceptos básicos de Google Tag Manager. Como por ejemplo que son las etiquetas, variables y activadores. Los espacios de trabajo (workspaces). Las versiones de publicación. Y similares. No debería ser problema para aquellos que han tenido un contacto corto con la herramienta.

También voy a asumir ciertos conocimientos básicos de ingeniería de datos y sistemas. Como qué es una API, cómo moverse de forma básica por un proyecto de Google Cloud o que es una cuenta de servicio o un sistema de autenticación Oauth. Aquí sí que daré más explicaciones e iré enlazando a documentación relevante, porque es el tema central del artículo, pero puede que haya cosas que se den por supuestas.  Con todo, cualquier persona que haya trasteado algo con un proyecto de Cloud podrá seguir el hilo. Recomiendo que si no es el caso, antes de seguir leyendo se dedique un rato a crear un proyecto gratuito en GCP y visitar el área de APIs y servicios. 

Y para terminar, asumiré cierto conocimiento básico de Python o de otro lenguaje de programación que permita hacer los paralelismo con Python. El código que presento se podría crear con Javascript, con R, con Go, con Ruby, etc.

Google Tag Manager

Necesitaremos un contenedor de Google Tag Manager con al menos una etiqueta de evento de GA4 funcional (con su activador y un parámetro de evento y/o propiedad de usuario configurada). Es decir, que haya algo que merezca la pena documentar.

Este proceso se centra en eventos con parámetros personalizados, pero realmente el código puede adaptarse para abarcar eventos normales o incluso etiquetas que no sean de GA4. La única limitación parcial que hay sería si nuestras etiquetas están generadas a base de código JS personalizado, pero ahí ya entiendo que es un requisito tener un código bien documentado de antemano y en mejores formatos (como por ejemplo en un repo de GitHub).

Google Cloud

Necesitaremos un proyecto de Google Cloud funcional y mejor si tiene activa la facturación. Si estás leyendo esto pero no quieres tener que exponer una tarjeta de crédito u otros fondos, siempre puedes crear de cero un proyecto en GCP y beneficiarte de sus 300$ de fondos de regalo. En todo caso el consumo es potencialmente nulo o muy bajo.

Necesitaré que actives la API de Google Tag Manager (Tag Manager API v2) y verifiques si tienes activas las API de Google Sheets (Sheets API v4) y la de Google Drive (Google Drive API v3), en principio deberían venir activadas por defecto pero mejor comprobarlo.

Finalmente necesitaré que crees un cliente de Oauth 2.0 que sea de aplicación web (puedes generar uno de escritorio, dependiendo de cómo decidas ejecutar los códigos). Y que ese cliente tenga un sistema de obtención de tokens de acceso y refresco, si no sabes cómo crearlos Google tiene guías sobre cómo realizar el proceso (y por todo internet tienes a su vez guías más de andar por casa). La razón de no hacerlo es que cada sistema es un mundo y mi código para facilitar la documentación está en Google Colab, que tiene capadas las conexiones OOB y hay que montar un arco de iglesia. 

También puedes evitarte el lío de Oauth y usar una cuenta de servicio. Pero en si misma es una potencial brecha de seguridad y consume a la larga más tiempo (rotado de claves, actualización de permisos, darla de baja cuando deja de ser necesaria para un proyecto, etc). Oauth es mucho más conveniente, porque puede usarlo cualquier persona con acceso al Google Tag Manager y con un Google Drive.

Google Colab

El código está montado en Colab por conveniencia, y porque me gusta como herramienta. Para acceder sólo necesitas una cuenta de gmail y ya deberías poder verlo en el siguiente enlace. Mi consejo es que copies o descargues el archivo, ya que solo os he dado permisos de lectura.

Si quieres puedes ir directamente al código e ignorar el resto, solo te advierto que tienes que modificarlo para añadir tu token de acceso y refresco, tu propio GTM y la ruta en donde quieras de tu Drive que se genere la guía. Si tratas de ejecutar el código tal cual te dará error hasta que hagas esos cambios. 

El código y lo que hace

El archivo con el código se puede consultar en el siguiente enlace. Cómo suele suceder con el código, la facilidad con la que se puede decir lo que hace es inversamente proporcional al número de líneas de código final; pero he intentado dejar anotaciones dentro para que se pueda leer de forma autónoma; o también puedes seguir leyendo, claro.

Lo he dividido en tres partes: la conexión a GTM, la extracción y formateo de parámetro y la creación y mantenimiento de la guía en Drive.

La conexión a GTM

Una de las ventajas de utilizar Oauth es que permitimos que un servicio de terceros (en este caso nuestro código) nos impersone con los límites que impongamos. Es decir, a la hora de ejecutar el código y para la cuenta con la que se lo permitamos, podremos tener acceso a los mismos recursos. 
En el caso de GTM es poder tener acceso a todos los contenedores, por lo que cualquier persona de nuestro equipo puede realizar sus propias guías sin necesidad de pasar por crear una cuenta de servicio. El proceso es el mismo por el que hemos pasado todos cientos de veces, se nos abre una pantalla nueva en el navegador en el que confirmaremos los accesos:

Y como en mi caso he estado probando este código con este cliente de Oauth 2.0 varias veces estos días pasados, en mi caso ya tiene cacheados los accesos concedidos:

Eso sí, a la hora de realizar la conexión necesitaremos aprovisionar un token de acceso y refresco válido (revisa la parte de requisitos previos para más información).

Una vez hecha la conexión, podemos por ejemplo listar todos los contenedores a los que tenemos acceso. Como yo lo he hecho desde una cuenta pensada para cuando doy clases y formaciones, tengo muchos contenedores pero poco interesantes:

De ahí hacemos foco en uno en concreto:

Y de ese nos centraremos en su Default Workspace, asumiendo que aunque podamos tener varios espacios de trabajo, el Default es donde tendremos el estado del etiquetado actualmente publicado. Si no es el caso entonces solo se re ajustan las variables y listo.

La lista de eventos y sus parámetros

Una vez tenemos el foco a nivel workspace, podemos consultar cualquier recurso. En mi caso empezamos por una lista de etiquetas, cuyo formato es horrible, y que se re formatea a una lista más legible para verificar que estamos donde queremos. Por poder, este listado se puede incluir como índice de la guía, aunque en mi caso lo dejo solo a forma de comprobación: 

Yo me voy a centrar solo en los eventos de GA4, pero como veis se puede ampliar el código a cualquier etiqueta. Incluyendo aquellas generadas por plantillas.

El objeto que define una etiqueta contiene mucha información, en la guía me voy a centrar solo en los parámetros de evento personalizados y las propiedades de usuario que en mi experiencia son los más farragosos de documentar. Pero se puede ampliar a cualquier configuración posible de la etiqueta. Por ejemplo, una evento del listado anterior:

Si de cada evento extraemos y formateamos en limpio sus parámetros, nos queda una lista simplificada sobre la que construir la documentación. Por ejemplo estos serían todos los parámetros de evento personalizados de todas las etiquetas, y de paso un buen momento para recordar que este es un contenedor reciclado de pruebas y no de verdad (es decir, no me juzguéis muy duramente por las convenciones de nombrado):

Como nota, si una etiqueta carece de parámetros de evento y/o propiedades de usuario, no saldrá en su lista respectiva; como es lógico.

Creación y mantenimiento de la guía de etiquetado

Una vez tenemos las listas de parámetros de evento y propiedades de usuario el transformarlo un documento en Drive es relativamente sencillo. Una vez indicada la carpeta y el nombre del archivo, verifica si ya existe una guía de etiquetado (utilizando el nombre) y si no hace una primer volcado. Luego, en sucesivas revisiones compara el documento con el estado actual, y si hay algún cambio actualiza dicha fila.

La columna de retrieval_date nos indica la primera vez que ese evento /parámetro (o propiedad) fue detectado; así que sirve como marca de tiempo de creación. En el caso de ejemplo se puede comprobar como el 23 de febrero se produce el primer volcado, y el 26 de febrero aparece un evento nuevo con sus respectivos parámetros extras.

Posibles siguientes pasos

Desde aquí podemos proceder de varias formas, por ejemplo con Cloud Scheduler podemos crear un job que actualice al final del día la guía; o irlo ejecutando bajo demanda. 

Se puede añadir una columna adicional de Descripción a rellenar de forma manual para dar más contexto. O se puede utilizar el documento y conectarlo a un Lookerstudio de QA, en el que por el cruce de nombres se puedan ver los números totales de eventos con esos parámetros con el conector de GA4 o de BigQuery.

También se puede modificar el código para incluir etiquetas que no sean de GA4 e incluso de aquellas generadas por plantillas. O ampliarlo para incluir la documentación de activadores y variables, o formatear todo en un mismo objeto que por cada etiqueta te provea todo el contexto actualizado.

El objetivo al final es ahorrar tiempo, documentar me resulta tremendamente laborioso incluso cuando son cosas triviales por lo que cualquier cosa que me evite procrastinar esa tarea para mi tiene un gran impacto. Espero que os sea tan útil como a mí.