Demo: Feature experimentation

Este tutorial práctico para desarrolladores muestra cómo funciona la feature experimentation en la plataforma Kameleoon. Comenzará con una aplicación de ejemplo y seguirá las instrucciones paso a paso para configurar un conjunto de feature flags en la aplicación Kameleoon, activarlos en la aplicación de ejemplo y ver cómo afectan los feature flags a la página del visitante. El ejemplo está escrito en TypeScript, pero no necesita conocer TypeScript para completar este tutorial. La experiencia con cualquier lenguaje de programación moderno debería ser suficiente para entender los puntos importantes.

​

Requisitos previos

Antes de empezar, debe crear un par de cuentas:

• Regístrese para obtener una cuenta de prueba gratuita de 30 días de Kameleoon. Deberá completar este tutorial dentro de los 30 días posteriores a la solicitud de la cuenta, aunque el tutorial debería llevarle solo unos 30 minutos.
• Una cuenta de GitHub.

​

Ejecutar la aplicación de ejemplo

Puede ejecutar la aplicación de ejemplo en GitHub Pages o en su máquina local. Inicie sesión en su cuenta de GitHub antes de empezar cualquiera de las dos opciones.

​

Desplegar en GitHub Pages

Desplegar en GitHub Pages significa que no tiene que preocuparse de configurar un servidor web.

1. En el repositorio Bouncing ball en GitHub, haga clic en Fork. Siga las indicaciones para crear su propio fork de la aplicación de ejemplo en github.com/<your_username>/bouncing-ball. (Sustituya <your_username> en este tutorial por el nombre de su cuenta de GitHub.)
2. En su nuevo repositorio https://github.com/<your_username>/bouncing-ball en GitHub, haga clic en la pestaña Actions y pulse el botón para habilitar los workflows.
3. En la pestaña Settings, haga clic en Pages, despliegue el menú Source y seleccione GitHub Actions.
4. En la pestaña Actions, haga clic en Deploy static content to Pages > Run workflow > Run workflow.

Una vez que el proceso de build y deploy se complete (esto puede llevar uno o dos minutos), debería poder ver la aplicación demo en ejecución en un navegador en https://<your_username>.github.io/bouncing-ball. Debería verse algo así:

​

Ejecutar la aplicación localmente

También puede ejecutar la aplicación de ejemplo en su máquina local en lugar de desplegarla en GitHub Pages. Trabajar localmente facilita ver la salida de depuración en la consola del navegador a medida que avanza en este tutorial.

1. Clone su fork: git clone https://github.com/<your_username>/bouncing-ball.git.
2. Instale las dependencias: npm install.
3. Inicie el servidor de desarrollo local: npm run dev.
4. Abra la URL que muestra la terminal, por ejemplo http://localhost:5173.

Utilice esta URL local en lugar de https://<your_username>.github.io/bouncing-ball durante el resto de este tutorial, incluso como la URL del sitio al crear su proyecto de Kameleoon.

​

Reducir el intervalo de sondeo de la configuración

Para realizar los cambios del proyecto más rápido, el intervalo de actualización en el que el SDK comprueba los cambios de configuración en la cuenta de Kameleoon se puede ajustar de forma programática:

1. En su repositorio de GitHub, en la pestaña Code, abra el archivo src/main.ts.
2. Haga clic en el botón Edit this file (con el icono de lápiz).
3. Localice y edite el archivo /src/main.ts. Busque la siguiente línea:
   const client = new KameleoonClient({ siteCode });
   
   Sustitúyala por el siguiente código:
   const configuration = {   updateInterval: 1,};const client = new KameleoonClient({ siteCode, configuration });
   
   El nuevo código añade una configuración con un updateInterval de 1. Este valor reduce la frecuencia con la que el SDK sondea los cambios en la configuración a una vez por minuto (en lugar del valor por defecto de 60 minutos). Este sondeo tan frecuente no es recomendable para un entorno de producción debido a su impacto en el rendimiento, pero resulta útil para el tutorial. Kameleoon también ofrece una opción premium de streaming que envía inmediatamente al SDK los cambios de configuración.
4. Haga clic en Commit changes….

​

Configurar un proyecto de Kameleoon

Necesitará las credenciales de su cuenta de prueba de Kameleoon antes de comenzar esta sección.

1. Inicie sesión en la aplicación Kameleoon usando las credenciales de su cuenta de prueba.
2. En el menú de la izquierda, despliegue Admin y haga clic en Projects > New project.
3. En el cuadro de diálogo, haga clic en Site: Feature flags en el primer desplegable y pegue https://<your_username>.github.io/bouncing-ball (o su URL local, si ejecuta la aplicación localmente) como URL of site. Recuerde sustituir <your_username> por el nombre de su cuenta de GitHub. Haga clic en Add.
4. Copie el site code que aparece en la página siguiente.
   
5. En su repositorio de GitHub, en la pestaña Code, edite el archivo src/constants. Sustituya el valor de siteCode por el site code que acaba de copiar y haga clic en Commit changes.

Si vuelve a comprobar la aplicación en el navegador (https://<your_username>.github.io/bouncing-ball, o su URL local), debería ver que han desaparecido todos los círculos en movimiento. Esto se debe a que los círculos los añadía un feature flag de Kameleoon en otro proyecto. Acaba de cambiar el site code, por lo que el sitio ahora está controlado por su proyecto de Kameleoon, que aún no ha configurado por completo. No se preocupe, añadirá sus propios círculos a la aplicación con sus propios feature flags.

​

Configurar feature flags

Los feature flags permiten desplegar nuevas funcionalidades a un público limitado y probar su eficacia antes de un despliegue completo. La configuración puede gestionarla los desarrolladores u otros miembros del equipo. Comprender cómo se configuran los feature flags en la interfaz de Kameleoon ayuda a usar las variables de forma eficaz dentro de la aplicación.

1. En la aplicación Kameleoon, en el menú Activate, haga clic en Feature flags.
2. Haga clic en New feature flag.
3. Complete los campos con los siguientes valores:
   • Name: Bouncing ball demo
   • Project: {Seleccione su proyecto en el desplegable}
   • Flag type: Permanent
   • Feature key: bouncing_ball_demo Puede dejar vacíos los campos de etiquetas y descripción.
4. Haga clic en Validate.

​

Configurar variables

Las variables son valores de tipo string, número, booleano o JSON que se utilizan en el código de la aplicación para modificar su comportamiento. Sus valores cambian según la variación que Kameleoon asigne al visitante. Por ejemplo, para determinar si los visitantes permanecen más tiempo en un sitio cuando se les muestra una variación “Party time” frente a una variación “Hypnotize”, configure una variación para cada opción y ejecute un experimento.

1. En la nueva página que aparece, despliegue el menú Set Up y haga clic en Variables.

2. Use el botón + Add Variable para añadir 6 variables con los siguientes valores:

   Variable key	Type	Default value
   title_text	String	Default variation: 1 green ball
   randomize_on_bounce	Boolean	False
   balls_amount	Number	1
   ball_speed	Number	10
   ball_color	String	green
   ball_size	Number	20

   ¡Cuidado con las erratas! Los nombres y tipos de las variable keys deben coincidir exactamente. Si revisa el archivo src/main.ts en su repositorio de GitHub, verá por qué. El ejemplo de código utiliza estos nombres exactos de variable key para recuperar los valores de las variables según la variación que Kameleoon asigne al visitante.
3. Haga clic en Save.

Ya ha configurado un conjunto de variables con valores por defecto. Los valores por defecto son los que utiliza su aplicación cuando no hay campañas activas para el visitante. Si ahora activase los feature flags, vería la variación por defecto, con 1 bola verde rebotando lentamente. Esto se debe a que aún no se ha configurado ninguna variación.

​

Configurar variaciones

Las variaciones definen las posibles combinaciones de variables que controlan lo que ve un visitante en su aplicación. Kameleoon asigna a cada visitante una variación en su primera visita a la aplicación.

1. En Set Up, haga clic en Variations.
2. Use el botón + Add variation para añadir dos nuevas variaciones:
   • Name: Party time
     • ball_size: 50
     • ball_color: random
     • ball_speed: 75
     • balls_amount: 75
     • randomize_on_bounce: True
     • title_text: Hey! Get up and dance!
   • Name: Hypnotize
     • ball_size: 200
     • ball_color: blue
     • ball_speed: 2
     • balls_amount: 10
     • randomize_on_bounce: False
     • title_text: You're getting very, very sleepy

​

Configurar un objetivo

A continuación, configurará un objetivo. Los objetivos definen cómo desea medir la eficacia de sus variaciones. Hay varios tipos de objetivos personalizables que puede usar, pero este tutorial utiliza una métrica básica de “time spent”.

1. En el menú Set Up, haga clic en Goals > + Add goal.
2. En la sección Configure goals, haga clic en + Create a new goal y complete los siguientes campos:
   • Name: Time spent
   • Type: Time Spent
   • Project: {Seleccione su proyecto}
3. Haga clic en Next y establezca el objetivo en: The visitor spent more than 30 seconds.
4. Haga clic en Validate.

​

Lanzar un experimento

Ahora que las variaciones están configuradas, puede crear un experimento que muestre las dos variaciones a un subconjunto de su audiencia. Mostrará una variación al 40 % de los visitantes y la otra variación a un 40 % distinto. El 20 % restante de los visitantes verá una versión no modificada de la aplicación (la por defecto).

1. En la sección Rollout Planner, haga clic en Production.
2. Haga clic en + Add a rule > Experiment.
3. Reduzca el control deslizante Exposure al 80 %.
4. En Variations to serve, haga clic en Party time y cambie el valor de Exposition a 40.00 %.
5. Haga clic en + Add a variation. La variación Hypnotize debería estar seleccionada automáticamente (si no, selecciónela). Cambie el valor de Exposition a 40.00 %.
6. Cambie el interruptor ON/OFF a ON.
7. Haga clic en Save.

​

Probar la aplicación

Ahora probará el feature flag que configuró utilizando la salida de depuración del SDK, algunas técnicas del navegador y los Live events de la aplicación Kameleoon para confirmar que todo funciona.

​

Activar el registro de depuración

Los logs de nivel debug muestran cada decisión interna que toma el SDK, lo que le ayuda a entender por qué la aplicación no sirvió una variación o por qué el SDK no registró un evento. Active el registro de depuración antes de abrir la aplicación por primera vez, para tener visibilidad completa desde su primera visita.

1. En src/main.ts, cambie la importación del SDK para que KameleoonLogger y LogLevel provengan del paquete completo en lugar del predeterminado:
   import { EventType, KameleoonClient, KameleoonLogger, LogLevel } from "@kameleoon/javascript-sdk/full";
   
2. Justo después de crear el cliente, establezca el nivel de log:
   const client = new KameleoonClient({ siteCode });
   client.setLogLevel(LogLevel.DEBUG);
   
3. Haga commit de sus cambios (o guarde el archivo, si ejecuta la aplicación localmente).
4. Abra la consola de desarrollador de su navegador antes de cargar la aplicación. Verá logs detallados sobre la carga de la configuración, la asignación del código de visitante y el cálculo de la variación.

Para ver la lista completa de niveles de log y lo que informa cada uno, consulte Registro de logs.

​

Ver su variación

Abra la aplicación en un navegador, usando su URL de GitHub Pages o su URL local. Debería ver una de las tres variaciones posibles: la variación Party time, la variación Hypnotize o la variación por defecto.

​

Ver una variación diferente

Como su navegador guarda un visitorCode, que es un ID único que le identifica, al refrescar la página siempre ve la variación que Kameleoon le asignó al principio. Para aparentar ser un nuevo visitante, utilice uno de los siguientes métodos:

• Cambiar a un navegador o dispositivo diferente.
• Abrir cada vez la aplicación en una nueva ventana privada (según el navegador, puede llamarse “Incognito”, “Private Browsing” o algo similar).
• Utilizar el panel de simulación del Rollout Planner para seleccionar una variación específica sin generar un nuevo código de visitante. Consulte Usar el modo de simulación para conocer los pasos de configuración, incluida la extensión de Chrome necesaria para los proyectos que solo utilizan feature experimentation.

Tras suficientes intentos, debería poder ver las tres variaciones. Si es así, ¡enhorabuena! Ha configurado con éxito un feature experiment con Kameleoon. 🎉🎉🎉

​

Verificar el seguimiento con Live events

Que aparezca una variación en su navegador no garantiza que Kameleoon haya registrado la visita. Compruebe Live events en la aplicación Kameleoon para confirmar que Kameleoon recibió el evento.

1. En la aplicación Kameleoon, vaya a Insights > Live events.
2. Seleccione su proyecto.
3. Filtre por el tipo de evento Experiment.
4. Busque una fila con una marca de tiempo reciente y el nombre de su feature flag.

Live events funciona igual tanto si la aplicación se ejecuta en GitHub Pages como en su máquina local, ya que Kameleoon recibe el evento por la red en ambos casos. Consulte Live events para obtener más información sobre el filtrado y los tipos de evento.

​

Solucionar problemas comunes

• Aparece la misma variación todo el tiempo. Su navegador ya almacenó un visitorCode en una cookie. Utilice una ventana privada, cambie de navegador o utilice el panel de simulación para previsualizar una variación diferente sin restablecer su código de visitante.
• No aparece ninguna variación, o siempre ve la variación por defecto. Compruebe que el interruptor ON/OFF de la regla en el Rollout Planner muestre ON y que el estado de la regla muestre Active.
• La aplicación sigue mostrando una configuración antigua después de cambiar una regla. El SDK sondea las actualizaciones de configuración a un intervalo fijo, 60 minutos por defecto. Confirme que estableció un valor de updateInterval más corto en su configuración y que hizo commit del cambio, luego espere al menos la duración de ese intervalo antes de volver a probar.
• Los logs de depuración no aparecen en la consola. Confirme que su declaración de importación utiliza @kameleoon/javascript-sdk/full en lugar de @kameleoon/javascript-sdk. El paquete predeterminado elimina los logs de debug e info para reducir su tamaño.
• Aparece una variación, pero no aparece ningún evento en Live events. El panel de simulación previsualiza una variación sin enviar un evento rastreable, por lo que nunca aparece en Live events. Visite la aplicación de forma normal, sin el panel de simulación, para generar un evento que pueda verificar.

​

Próximos pasos

• En la sección Reporting de su experimento, revise algunos de los resultados iniciales, las integraciones disponibles y el registro de actividad. Aún no dispondrá de muchos datos de resultados, debido al bajo tráfico.
• Revise el código de ejemplo para entender cómo se aplican las variables en el código. Si tiene experiencia escribiendo TypeScript, pruebe a añadir su propia variable.
• Revise el resto de esta documentación para desarrolladores y la Guía de usuario de experimentación para conocer todas las opciones y funcionalidades disponibles.
• Instale el SDK de su elección y empiece a construir sus propios feature flags, personalizaciones y otros experimentos.