Código personalizado y scripts insertados

Un script insertado conecta una página construida en AppBO con código que corre en el navegador del visitante. De un lado está el paso del funnel, la página del sitio, el formulario o la encuesta tal como la renderiza el editor. Del otro está lo que sea con lo que hable el script: un recolector de analítica, un gestor de etiquetas, un widget de chat, un módulo de reservas insertado, un widget de reseñas, un gestor de consentimiento o unas cuantas líneas de tu propio JavaScript que ajustan un comportamiento que el editor no expone.

Recurres a esto cuando lo que necesitas vive en la página y no en los datos. La atribución es el caso más común. Un píxel tiene que dispararse en el navegador, en la página real y en el momento correcto, o la campaña no tiene un resultado medible. Los widgets de terceros son el segundo caso: un proveedor te da un fragmento de código y la página es el único lugar donde puede ir. El tercero son los ajustes reales de comportamiento: ocultar un campo según una condición, prellenar desde la query string, ajustar una etiqueta de texto, agregar una regla de validación.

También es la integración más riesgosa de esta biblioteca, porque corre con todos los privilegios de la página. Un script de terceros que se porta mal puede bloquear el renderizado, romper el envío de un formulario, filtrar datos personales a un proveedor que nadie aprobó o dejar de funcionar sin aviso después de una actualización de la plataforma. La disciplina que lo vuelve seguro es aburrida y no se negocia: saber qué hace cada script, cargarlo en el lugar correcto, acotar tus selectores y verificar en el navegador en lugar de confiar en que se guardó sin errores.

1. Antes de que el script se acerque a una página, establece qué hace realmente. Léelo o, como mínimo, conoce al proveedor, qué recolecta, a qué dominios llama y si crea cookies. Un fragmento pegado desde un ticket es una dependencia sin revisar.
2. Revisa las consecuencias de privacidad primero, no al final. Si el script envía datos del visitante a un tercero, confirma que esté cubierto por tu aviso de privacidad y tu mecanismo de consentimiento, sobre todo en cualquier página que maneje información de salud, financiera o sensible por otro motivo, donde muchas veces la respuesta correcta es no insertarlo en absoluto.
3. Decide el alcance. La plataforma ofrece código personalizado a nivel de página o de paso y un área más amplia de código de seguimiento a nivel de sitio o de cuenta; usa el alcance más estrecho que cumpla el objetivo. Un script de seguimiento que solo importa en un paso del funnel no tiene por qué estar en toda la cuenta.
4. Elige head o body a propósito. Los gestores de consentimiento y los gestores de etiquetas generalmente tienen que ir en el head y temprano. Todo lo demás es más seguro al final del body, donde no puede retrasar el renderizado.
5. Carga los scripts de terceros de forma asíncrona. Agrega async o defer a menos que el proveedor exija de forma explícita una ejecución síncrona, y ten presente que un script de terceros síncrono hace que tu página sea tan lenta como el peor día del proveedor.
6. Si tienes más de unos cuantos fragmentos, prefiere un solo gestor de etiquetas antes que muchos fragmentos individuales. Un contenedor revisado con un registro de cambios es mejor que ocho fragmentos agregados por seis personas a lo largo de dos años.
7. Envuelve tu propio código para que espere al DOM y no pueda correr antes de que existan los elementos que toca. El markup que renderiza el editor no está disponible en el momento del parseo.
8. Acota cada selector lo más que puedas y trata los nombres de clase que genera el editor como inestables. Prefiere un identificador o un atributo que tú mismo le pongas al elemento desde el editor antes que una clase generada que va a cambiar en la próxima republicación.
9. Pon un espacio de nombres a todo lo que declares. Usa un solo objeto o una función autoejecutable en lugar de variables y nombres de funciones globales sueltos, para no chocar con los scripts propios de la plataforma ni con otro script insertado.
10. Protégete contra la doble ejecución. Un script agregado tanto a nivel de página como de cuenta, o una página que vuelve a renderizar una sección, puede correr tu código dos veces. Define una bandera y sal de inmediato si ya está definida.
11. Nunca pongas un secreto en un script insertado. Todo lo que está en el JavaScript de la página es público: nada de API keys con acceso de escritura, nada de tokens, nada de endpoints privados. Si el navegador necesita datos privilegiados, debe llamar a un servidor que tú controles y que guarde la credencial.
12. Guarda y después vuelve a publicar el funnel o el sitio. Es común que el código personalizado no aparezca en la página en vivo hasta que se republica, y esa es la razón más frecuente por la que parece que un script insertado no se guardó.
13. Verifica en el navegador sobre la página en vivo, no en la vista previa del editor. Abre las herramientas de desarrollo: confirma que el script esté en el documento, que no haya errores en la consola, que se dispare la solicitud de red al proveedor y que el evento esperado aparezca en la vista en tiempo real del propio proveedor.
14. Prueba el camino crítico con el script activo: envía el formulario, agenda la cita, completa el pago. Un script de seguimiento que rompe el manejador de envío cuesta más de lo que mide.
15. Registra qué agregaste, dónde, por qué y quién es responsable. Después vuelve a verificar tras cualquier actualización de la plataforma o cambio de plantilla, porque los scripts insertados fallan sin avisar.

De la página de la plataforma al tercero

• Lo que el script esté diseñado para recolectar: URL de la página y referente, user agent, pantalla y viewport, comportamiento de clics y scroll, tiempo en la página.
• Los identificadores que el script crea o lee: sus propias cookies, entradas de almacenamiento local, identificadores publicitarios, identificadores de clic de los parámetros de URL de la campaña.
• Los eventos de conversión que disparas a propósito, con los parámetros que les agregues.
• Los valores de los campos de formulario, pero solo si el script está escrito para leerlos, que es justo el comportamiento que hay que auditar antes de insertar cualquier cosa en un formulario.

Del tercero a la página

• El markup renderizado de los widgets: paneles de chat, módulos de reservas insertados, carruseles de reseñas, banners de consentimiento.
• Configuraciones y asignaciones de experimentos que se obtienen en tiempo de ejecución.
• Más scripts, porque muchos fragmentos de proveedores son cargadores que traen código adicional, y por eso revisar solo el fragmento que pegaste no alcanza.

Dentro de la página

• Tu propio código leyendo y escribiendo elementos del DOM, prellenando campos desde los parámetros de la query string y agregando manejadores de eventos.

Lo que no se mueve

• Los datos de la plataforma del lado del servidor. Un script insertado no tiene acceso privilegiado a los contactos, conversaciones ni pipelines de la cuenta; solo ve lo que la página renderizó.
• El acceso autenticado a la API. Nada en el JavaScript de la página puede guardar una credencial de forma segura, así que no existe una lectura segura de los datos de la cuenta desde un script insertado.
• Los eventos del lado del servidor. Un script del navegador no puede reportar una conversión que ocurrió en la administración interna o después de un reembolso; para eso hace falta una llamada desde el servidor.
• Cualquier cosa de un visitante con JavaScript bloqueado, un bloqueador de anuncios activo o que rechazó el consentimiento.

Escenario: un funnel de generación de prospectos tiene que reportar una conversión a una plataforma de anuncios cuando se envía el formulario, prellenar el origen de la campaña en un campo oculto y cargar un banner de consentimiento antes de que se dispare cualquier seguimiento.

1. Revisas los tres fragmentos involucrados: el gestor de consentimiento, la etiqueta base de la plataforma de anuncios y la llamada de evento de la plataforma de anuncios. Confirmas qué recolecta cada uno y que el aviso de privacidad lo cubre.
2. En el área de código personalizado del funnel pones el gestor de consentimiento en el head, de forma síncrona, porque tiene que correr antes de que cualquier otra cosa pueda crear una cookie.
3. Pones la etiqueta base de la plataforma de anuncios también en el head, pero configurada para que solo se inicialice después de que el gestor de consentimiento indique que se otorgó el consentimiento de marketing. Sin ese filtro, la etiqueta se dispara sin importar el banner, y el banner queda de adorno.
4. En el código personalizado del final del body agregas tu propio fragmento, envuelto en una función autoejecutable con una bandera de protección para que no pueda correr dos veces si la sección se vuelve a renderizar.
5. Tu fragmento espera a que el DOM esté listo, lee los parámetros de la campaña de la query string de la URL y los escribe en un campo oculto del formulario que creaste en el editor, al que apunta mediante un atributo personalizado que le pusiste a ese campo, no mediante un nombre de clase generado.
6. Tu fragmento agrega un listener de envío al formulario, acotado a ese único formulario por su propio identificador y no a todos los formularios de la página.
7. Al enviar, el listener revisa el estado del consentimiento; si existe consentimiento de marketing, llama a la función de evento de la plataforma de anuncios con el nombre del evento de conversión y después deja que el envío siga sin interferir con él.
8. Guardas y vuelves a publicar el funnel, porque el código personalizado sin publicar no existe en la página en vivo.
9. Abres la URL en vivo con las herramientas de desarrollo. Aparece el banner de consentimiento, no se dispara ninguna solicitud de seguimiento antes de que aceptes y, después de aceptar, se carga la etiqueta base. El campo oculto se llena desde la query string.
10. Envías el formulario con un registro de prueba. La consola está limpia, la vista en tiempo real de la plataforma de anuncios muestra la conversión y el contacto llega a AppBO con el origen de la campaña en el campo personalizado.
11. Repites la prueba rechazando el consentimiento y confirmas que el formulario se sigue enviando y el contacto sigue llegando, sin ninguna solicitud de seguimiento. El camino del envío nunca debe depender del camino del seguimiento.
12. Tres meses después, un cambio de plantilla vuelve a publicar el funnel. Tu lista de verificación posterior a los cambios incluye recargar la página en vivo y confirmar que el script insertado se sigue disparando, lo que detecta la regresión antes de que la próxima campaña invierta un solo centavo.

Límites de rendimiento

Cada script de terceros es una dependencia de la disponibilidad y la latencia de otra empresa. Un script síncrono en el head bloquea el renderizado hasta que responde, así que un proveedor lento se convierte en tu página lenta. Carga de forma asíncrona, mantén pocos scripts insertados y mide la página antes y después de agregar uno. En conexiones móviles, la diferencia entre tres scripts y diez es la diferencia entre una landing page que convierte y una que se abandona.

Reintentos e idempotencia

Los eventos del navegador se disparan y se olvidan: si la solicitud falla, se bloquea o el visitante se va a mitad de camino, el evento simplemente se pierde, y no hay reintento que configurar. Al revés, el código que corre dos veces dispara el evento dos veces e infla tus cifras. Protégete con una bandera, dispara los eventos de conversión una sola vez por cada acción significativa y, para todo lo que tenga que ser exacto (ingresos, conversiones que afectan la facturación), repórtalo desde el servidor con un webhook en lugar de confiar en el navegador.

Trampas de selectores y mapeo

Los nombres de clase y la estructura del DOM que genera el editor no son una interfaz pública y pueden cambiar al republicar o después de una actualización de la plataforma. El código atado a ellos es código que se va a romper sin aviso. Ponle tu propio identificador o atributo data al elemento desde el editor y apunta a eso. Ten presente que el DOM se construye después del parseo, así que nunca consultes elementos al principio de un script del head, y espera que las secciones renderizadas de forma dinámica aparezcan después de que se agregó tu listener.

Ejecución duplicada

La causa clásica es el mismo fragmento presente a nivel de cuenta y a nivel de página, o un contenedor del gestor de etiquetas que también incluye la etiqueta que pegaste directamente. Audita los duplicados cada vez que las cifras de conversión se vean demasiado buenas.

Entorno de pruebas frente a producción

La vista previa del editor no es la página en vivo: tiene otra URL, a veces otro markup y un seguimiento que se comporta distinto. Verifica siempre en la URL publicada. Usa el modo de depuración o de vista previa del propio proveedor en lugar de adivinar, y deja el tráfico de prueba fuera de los reportes de producción filtrándolo en el proveedor, no acordándote de no hacer clic.

Consentimiento, privacidad y credenciales

Los scripts de seguimiento en páginas que recolectan información sensible son un riesgo real de cumplimiento, no uno teórico. Pon cada script no esencial detrás del consentimiento, mantén el gestor de consentimiento primero en el orden de carga y replantéate si un script de terceros debe estar siquiera en una página que maneja datos de salud o financieros. Nunca insertes una credencial: todo lo que está en el JavaScript de la página lo puede leer cualquier visitante.

Lo que suele romperse

• Código personalizado guardado, pero el funnel nunca se volvió a publicar.
• Una actualización de la plataforma o de la plantilla que cambia el markup debajo de un selector frágil.
• Un bloqueador de anuncios o un navegador de privacidad que descarta sin aviso la solicitud al proveedor, así que la medición parece rota cuando funciona tal como se diseñó.
• Un error de script al principio de la página que impide que corran los scripts posteriores, incluido el manejo del formulario.
• Choques de variables globales entre dos scripts insertados, o entre un script insertado y el código propio de la plataforma.
• Un cargador del proveedor que trae código nuevo sin aviso y cambia el comportamiento sin ningún cambio de tu lado.
• Seguimiento condicionado al consentimiento en un lugar y no en otro, lo que produce cifras que nadie puede conciliar.