Hace unos meses que mi compañero Miguel Angel C. nos proporcionaba un ejemplo, con códigomuy detallado, de medición de vídeos de Youtube, haciendo uso para ello de la API de YouTube para iframe.
En esta ocasión, sin embargo, nos centraremos en aspectos básicos de su funcionamiento, del funcionamiento propiamente dicho de la API, claves para entender y depurar cualquier código cuya finalidad sea recoger información acerca de las interacciones de usuario con cualquier vídeo insertado en mi página web.
Introducción
La API de YouTube para iframe nos permite insertar y controlar un reproductor de vídeo de YouTube. Su finalidad más clara es funcional. La que nos interesa a nosotros, análisis.
Una vez alcanzado un cierto desarrollo digital, y con una implementación mínima que te permita entender cómo interactúan tus usuarios con tu página web, es el momento de dar un paso más, añadir complejidad a la implementación, y por qué no, implementar el seguimiento de vídeos.
Así pues, nos ponemos manos a la obra…
Mi vídeo es un iframe
Entramos en la página y analizamos su contenido.
Una vez detectado el vídeo, inspeccionamos el contenido HTML, y para nuestra sorpresa, descubrimos que en realidad se trata de un iframe.
Que no nos engañe, no va a suponer ninguna dificultad técnica.
Una de las formas más comunes de insertar vídeos de YouTube es haciendo uso de su API, que nos permite publicar contenido (vídeos), en una etiqueta iframe de página. Sea o no el caso, dicha API está diseñada específicamente para tratar con iframes, existen versiones específicas de la misma para Flash y para JavaScript.
Parámetros del reproductor: enablejsapi y origin
A la hora de insertar un vídeo en página haciendo uso de la API de YouTube para iframe, podemos indicarle una serie de parámetros que nos permitirán personalizar la experiencia del usuario, habilitando por ejemplo la reproducción automática, o haciendo que el vídeo se reproduzca en bucle.
En nuestro caso, nos centraremos en dos parámetros clave para nuestra finalidad, analítica.
Uno de estos parámetros es el ‘enablejsapi’, que habilita el uso de la API de YouTube sobre el elemento. En caso contrario, no podremos utilizarla para controlar el vídeo.
Otro parámetro que puede aparecer y que es bastante importante cara a lo que nos preocupa es el ‘origin’.
En este caso, se trata de un parámetro opcional de seguridad, diseñado para evitar que terceros puedan tomar el control de tu reproductor y que debe contener por lo menos el protocolo y dominio completos de tu página web.
Las consecuencias de estos dos parámetros son bastante directas:
- Si no existe el parámetro ‘enablejsapi’, no podremos utilizar la API de YouTube para iframes.
- Si el parámetro ‘origin’ existe, pero está incorrectamente seteado, podría impedirnos tomar el control del vídeo, que a efectos prácticos es como si no pudiésemos utilizar la API.
Así pues, nuestro primer paso será comprobar cuántos vídeos existen en página y que su parametrización sea la correcta.
La librería, su carga y el callback onYouTubeIframeAPIReady
El siguiente paso será el de cargar la librería de YouTube, disponible en: https://www.youtube.com/iframe_api
Si lo hacemos de manera asíncrona para evitar que interfiera en la carga de nuestra página web, necesitaremos saber cuándo podemos empezar a usar los métodos que en ella hay definidos.
Es por ello que se nos provee con el método onYouTubeIframeAPIReady, que es ejecutado inmediatamente una vez que la librería ha terminado de descargarse y ejecutarse.
Una primera consideración aquí es, que si por alguna razón, dicha librería es cargada previamente en página, – normalmente para los fines que comentaba al inicio, y que no tienen nada que ver con la analítica -, es que, aunque nosotros la volvamos a cargar dicho método, no volverá a ejecutarse. Por lo que la manera de actuar aquí es comprobar la existencia de la misma. Caso de no existir se carga, y ella misma al terminar llamará a la función onYouTubeIframeAPIReady para indicárnoslo. En caso contrario simplemente llamamos nosotros manualmente a dicha función.
El objeto YT.Player, su definición, y cómo sobreescribir una primera inicialización
Una vez cargada la librería, y disponibles los métodos en ella expuestos, es el momento de construir un objeto YT.Player asociado a cada vídeo, y que representa nuestra interfaz con la API.
En su creación se especifican, entre otros, o el id del elemento HTML o el elemento del DOM en sí como referencias unívocas al vídeo, permitiendo hacer la asociación. También se especifican las funciones que se ligarán a los diferentes eventos, eventos que ocurren al interactuar con el vídeo y que se ejecutarán cuando estos ocurran. Nos estamos refiriendo a los eventos ‘onReady’, ‘onStateChange’ y ‘onError’.
Es en las funciones ligadas a esos eventos donde estará toda la lógica para medir los vídeos.
Un paso importante es revisar la variable en donde almacenamos dichos manejadores, pues podríamos no estar asociándolos correctamente.
También es importante analizar la carga de la página, pues si en la misma se apoyan en la API de YouTube para iframe para insertar el vídeo, cargándola, y construyendo el objeto previamente, cualquier intento de crear un nuevo manejador para el mismo vídeo resultará en errores en tiempo de ejecución al intentar acceder a los diferentes métodos disponibles, obteniendo el mensaje de error ‘is not a function’, que nos podría llevar a pensar de manera equivocada que no he cargado la librería.
Un ejemplo podría ser, al registrar una interacción – evento onStateChange -, intentar acceder al valor de tiempo de reproducción.
Para ello accedemos a la variable que almacena la instancia del objeto YT.Player y llamamos a la función getCurrentTime. En el caso expuesto, obteniendo el error <variable_que_almacena_el_manejador>.getCurrentTime is not a function at <cualesquiera_que_sea_la_funcion_ligada_al_onStateChange>.
La manera de actuar, en estos casos, en los que el objeto ha sido previamente construido, y en los que queremos asociar nuestra propia función, – función que incluye el código de seguimiento para vídeos -, cuando previamente se ha asociado otra función, o la función que se ha asociado no es la que queremos que se utilice es accediendo a la variable en donde se ha almacenado la instancia del objeto YT.Player y sobrescribiendo la función que ha sido asociada.
Básicamente, se traduce en llamar al método JavaScript addEventListener, asociando nuestra nueva función al evento en cuestión.
Es importante pues que el objeto, al crearlo, quede disponible para ser accedido desde un ámbito global, o al menos que nosotros podamos acceder al mismo.
Otra peculiaridad, y que también es importante tener en cuenta, es que si el objeto ha sido previamente construido sobreescribir la función en sí – su funcionamiento -, no sirve.
Por clarificar, supongámonos que en la creación he asociado una función custom, que he denomidado ‘onYoutubePlayerStateChange’, al evento ‘onStateChange’, y que dicha función lo único que hace es mostrarme un mensaje por pantalla. Si a posteriori redefiniera dicha función, sobrescribiéndola, sería completamente inútil. La versión de la función que se ejecutaría sería la primera.
Manejando varios objetos
Un tema importante, y sobre el que hemos pasado un poco por encima, es cómo gestionar los casos en dónde tenemos presencia de múltiples vídeos en página.
En este caso lo único que hay que tener en cuenta es que tendremos que crear un objeto de tipo YT.Player por cada vídeo, almacenándolo en un array de variables, y que tendremos que gestionar referenciando en cada momento el manejador correspondiente.
Ventanas modales
Una de las casuísticas más comunes es la de un vídeo que se muestra a través de una ventana modal que aparece de manera dinámica en pantalla.
Es importante tener en cuenta en estos casos que hasta que el elemento en cuestión, es decir, el vídeo, no exista en el DOM, no tendremos una referencia en la que apoyarnos, y por tanto no podremos crear el objeto YT.Player, tendremos que esperar, normalmente asociando un escuchador a la aparición de la ventana modal en la que se carga.
Otra problemática a tener en cuenta es, que cuando el usuario cierre el modal, perderemos la referencia al vídeo, referencia fijada mediante el objeto que habíamos creado previamente. Por lo que para futuras mediciones deberá volver a procederse como si de un vídeo nuevo se tratara.
Documentación oficial
Por último, quisiera referenciar la documentación oficial, de obligatoria lectura previo manejo de la API para iframes de YouTube.
