Contexto

Los pasos de Contexto te permiten crear y actualizar una o más variables para un usuario a medida que avanza por un Canvas. Por ejemplo, si tienes un Canvas que gestiona descuentos de temporada, puedes usar una variable de contexto para almacenar un código de descuento diferente cada vez que un usuario entra en el Canvas.

Cómo funciona

Los pasos de contexto te permiten crear y usar datos temporales durante el recorrido de un usuario a través de un Canvas específico. Estos datos solo existen dentro de ese recorrido de Canvas y no persisten entre diferentes Canvas ni fuera de la sesión.

Las variables de contexto solo existen para ese recorrido específico de Canvas. No cambian el perfil del usuario de forma permanente ni aparecen en otros Canvas. Esto las hace ideales para información temporal que solo es relevante para una campaña o flujo de trabajo específico.

Consejo

Para una referencia completa sobre las variables de contexto, incluyendo tipos de datos, uso y mejores prácticas, consulta la Referencia de variables de contexto.

Dentro de un paso de contexto, puedes definir o actualizar hasta 10 variables de contexto. Estas variables se pueden usar para personalizar retrasos, segmentar usuarios dinámicamente y enriquecer la mensajería a lo largo del Canvas. Por ejemplo, podrías crear una variable de contexto para la hora de vuelo programada de un usuario y luego usarla para establecer retrasos personalizados y enviar recordatorios.

Puedes establecer variables de contexto de dos formas:

• En la entrada del Canvas: Las propiedades del evento personalizado o del desencadenador de API se completan automáticamente como variables de contexto.
• En un paso de contexto: Define o actualiza variables de contexto manualmente añadiendo un paso de contexto.

Cada variable de contexto requiere un nombre, un tipo de datos y un valor (establecido usando Liquid o la herramienta de añadir personalización). Una vez definidas, puedes hacer referencia a las variables de contexto a lo largo del Canvas usando Liquid, como {{context.${flight_time}}}. En el campo Nombre de la variable de contexto, también puedes introducir el nombre de la variable de contexto o seleccionarlo del menú desplegable en el editor de pasos. Para más detalles, consulta la Referencia de variables de contexto.

Cada entrada en el Canvas redefine las variables de contexto basándose en los datos de entrada más recientes y la configuración del Canvas, lo que permite que los usuarios tengan múltiples recorridos activos con su propio contexto. Por ejemplo, si un cliente tiene dos vuelos próximos, tendrá dos estados de recorrido separados ejecutándose simultáneamente, cada uno con sus propias variables de contexto específicas del vuelo, como la hora de salida y el destino. Esto te permite enviar recordatorios personalizados sobre su vuelo de las 2 pm a Nueva York mientras envías actualizaciones diferentes sobre su vuelo de las 8 am a Los Ángeles mañana, de modo que cada mensaje se mantenga relevante para la reserva específica.

Procesamiento de usuarios y procesamiento por lotes

Los pasos de contexto procesan a los usuarios en lotes para optimizar el rendimiento. Cuando los usuarios entran en un paso de contexto, Braze los procesa en lotes de 1,000 usuarios de forma predeterminada. Estos lotes se procesan en paralelo, pero dentro de cada lote, los usuarios se procesan de forma secuencial.

Esto significa:

Ejemplo: Si 3,500 usuarios entran en un paso de contexto con contenido conectado que tarda 650 ms por usuario:

• Braze crea 4 lotes de usuarios (1,000, 1,000, 1,000 y 500 usuarios en este ejemplo).
• Cada lote procesa a los usuarios de forma secuencial, por lo que un lote de 1,000 usuarios tarda aproximadamente 10.8 minutos (650 segundos; 1,000 × 650 ms).
• Los lotes se completan en momentos diferentes, por lo que los usuarios van pasando al siguiente paso a medida que su lote finaliza.
• Los primeros usuarios pueden llegar al siguiente paso varios minutos antes que los últimos usuarios, dependiendo del tamaño del lote y los tiempos de respuesta del contenido conectado.

Sin contenido conectado, los pasos de contexto se procesan mucho más rápido porque no hay llamadas a API externas que esperar.

Consideraciones

• Puedes definir hasta 10 variables de contexto por paso de contexto.
• Cada variable requiere un nombre único (solo letras, números y guiones bajos, hasta 100 caracteres).
• El tamaño total de todas las variables en un paso no puede superar los 50 KB.
• Las variables pasadas mediante desencadenadores de API comparten el mismo espacio de nombres que las creadas en los pasos de contexto; redefinir una variable en un paso de contexto anula el valor de la API.

Para más detalles y uso avanzado, consulta Referencia de variables de contexto.

Creación de un paso de Contexto

Consejo

No necesitas un paso de contexto para hacer referencia a las propiedades del evento desencadenante en los pasos de ruta de audiencia o división de decisiones. Puedes hacer referencia a las propiedades directamente en los grupos de filtros con el filtro Context Variable. Asegúrate de seleccionar el tipo de datos correcto.

Paso 1: Añadir un paso

Añade un paso a tu Canvas, luego arrastra y suelta el componente desde la barra lateral, o selecciona el botón de más y selecciona Contexto.

Paso 2: Definir las variables

Nota

Puedes definir hasta 10 variables de contexto para cada paso de Contexto.

Para definir una variable de contexto:

1. Dale un nombre a tu variable de contexto.
2. Selecciona un tipo de datos.
3. Escribe una expresión Liquid manualmente o usa Añadir personalización para crear un fragmento de código Liquid a partir de atributos preexistentes.
4. Selecciona Vista previa para comprobar el valor de tu variable de contexto.
5. (Opcional) Para añadir variables adicionales, selecciona Añadir variable de contexto y repite los pasos 1-4.
6. Cuando hayas terminado, selecciona Listo.

Ahora puedes usar tu variable de contexto en cualquier lugar donde uses Liquid, como en los pasos de Mensaje y Actualización de usuario, seleccionando Añadir personalización. En el campo Nombre de la variable de contexto, también puedes introducir el nombre de la variable de contexto o seleccionarlo del menú desplegable en el editor de pasos. Para un recorrido completo, consulta Referencia de variables de contexto.

Importante

Al hacer referencia a variables de contexto, usa siempre el formato {{context.${variable_name}}}.

Filtros de variables de contexto

Puedes crear filtros usando variables de contexto en los pasos de rutas de audiencia y división de decisiones.

Para dirigir a los usuarios en función de la respuesta de un paso de Agente, añade el paso de Agente antes de tu paso de rutas de audiencia o división de decisiones. El paso de Agente almacena su salida en el contexto de Canvas, que puedes evaluar con filtros de variables de contexto en esos pasos de ramificación.

Si el agente devuelve un objeto y quieres filtrar por una propiedad anidada, introduce la ruta en el campo Nombre de la variable de contexto usando notación de puntos en lugar de solo el nombre de la variable de nivel superior (por ejemplo, intent_agent.persona cuando persona está anidada bajo intent_agent).

Para la configuración de filtros, la lógica de comparación y ejemplos avanzados, consulta Referencia de variables de contexto.

Importante

Elegir entre los tipos de filtro «Día del año» y «Hora»: al filtrar variables de contexto que contienen fechas, elige el tipo de comparación correcto en función de si la fecha se repite cada año. Usa «Día del año» solo cuando el año no esté incluido en el valor que produce la variable de contexto.

• Usa «Día del año» cuando la fecha se repita cada año (por ejemplo, cumpleaños, aniversarios o fiestas como Navidad). Este tipo de comparación calcula en función del día del año (1-365/366), ignorando el componente del año.
• Usa «Hora» cuando la fecha sea una fecha absoluta que no se repita (por ejemplo, fechas de finalización de contratos, fechas de citas o fechas de renovación de suscripciones). Este tipo de comparación calcula basándose en la marca de tiempo completa, incluido el año.

El uso de «Día del año» para fechas absolutas puede producir resultados incorrectos o inesperados, ya que el cálculo ignora el componente del año. Por ejemplo, si comparas la fecha de vencimiento de un contrato futuro en abril para determinar si está dentro de los 63 días, el uso de «Día del año» puede hacer que las fechas coincidan incorrectamente, ya que solo compara los números de los días (119 frente a 359) sin tener en cuenta que, en realidad, quedan 188 días para abril.

Vista previa de las rutas de usuario

Recomendamos probar y previsualizar tus rutas de usuario para asegurarte de que tus mensajes se envían a la audiencia correcta y de que las variables de contexto se evalúan con los resultados esperados.

Nota

Si estás previsualizando tu Canvas en la sección Vista previa y envío de prueba del editor, la marca de tiempo en la vista previa del mensaje de prueba no se estandariza a UTC porque este panel genera las vistas previas como cadenas. Esto significa que si un Canvas está configurado para aceptar un objeto time, la vista previa del mensaje no refleja con precisión lo que ocurre cuando el Canvas está en vivo. Para probar tu Canvas de la forma más precisa, te recomendamos previsualizar las rutas de usuario en su lugar.

Asegúrate de observar cualquier escenario común que genere variables de contexto no válidas. Al previsualizar tu ruta de usuario, puedes ver los resultados de los pasos de Delay personalizados que utilizan variables de contexto, así como cualquier comparación de audiencia o paso de división de decisiones que asocie usuarios con variables de contexto.

Si la variable de contexto es válida, puedes hacer referencia a ella en todo tu Canvas. Sin embargo, si la variable de contexto no se creó correctamente, los pasos futuros en tu Canvas tampoco funcionarán correctamente. Por ejemplo, si creas un paso de contexto para asignar a los usuarios una hora de cita y estableces el valor de la hora de cita con una fecha pasada, el correo electrónico de recordatorio en tu paso de mensaje no se envía.

Conversión de cadenas de contenido conectado a JSON

Al realizar una llamada de contenido conectado en un paso de contexto, el JSON devuelto por la llamada se evalúa como un tipo de dato de cadena para mantener la coherencia y prevenir errores. Si deseas convertir esta cadena en JSON, conviértela usando as_json_string. Por ejemplo:

1
2

{% connected_content http://example.com :save product %}
{{ product | as_json_string }}

Solución de problemas

Variables de contexto no válidas

Una variable de contexto se considera no válida cuando:

• Una llamada a un contenido conectado integrado falla.
• La expresión Liquid en tiempo de ejecución devuelve un valor que no coincide con el tipo de datos o está vacío (null).
• La expresión Liquid llama a {% abort_message() %}.

Por ejemplo, si el tipo de datos de la variable de contexto es Number pero la expresión Liquid devuelve una cadena, se considera no válida.

En estas circunstancias:

• El usuario avanza al siguiente paso.
• Los análisis del paso en Canvas lo cuentan como Not Updated.

Al solucionar problemas, monitoriza la métrica Not Updated para verificar que tu variable de contexto se esté actualizando correctamente. Si la variable de contexto no es válida, tus usuarios pueden continuar en tu Canvas más allá del paso de contexto, pero es posible que no califiquen para pasos posteriores.

Consulta Tipos de datos para ver las configuraciones de ejemplo para cada tipo de datos.

Una variable de contexto también puede omitirse a propósito con abort_message. Consulta Uso de abort_message en una variable de contexto.

Uso de abort_message en una variable de contexto

Puedes usar la etiqueta Liquid abort_message en el valor de una variable de contexto para omitir esa variable para algunos usuarios. En un paso de contexto, abort_message afecta solo a la variable en la que se encuentra. No detiene el paso ni hace que el usuario salga del Canvas.

Cuando el Liquid de una variable de contexto llama a abort_message para un usuario:

• La variable no se establece para ese usuario. Si un paso de contexto anterior ya estableció esta variable, el usuario conserva ese valor anterior.
• Las demás variables del paso se siguen evaluando y estableciendo.
• Las variables posteriores en el mismo paso que hacen referencia a esta variable no reciben un nuevo valor de esa variable.
• El usuario avanza al siguiente paso.
• Los análisis del paso en Canvas cuentan la variable como Not Updated.

Por ejemplo, esta variable se establece como true para usuarios en Francia y se omite para todos los demás:

1
2
3
4
5

{% if ${country} == "France" %}
  true
{% else %}
  {% abort_message("Not in France") %}
{% endif %}

Cuando previsualizas las rutas de usuario, una variable omitida aparece como “variable_name was not updated because the Liquid logic triggered an abort”.

Si los pasos posteriores dependen de esta variable, planifica para los usuarios que no la tengan establecida. Por ejemplo, puedes enrutarlos con un paso de ruta de audiencia.

Nota

Las cancelaciones del paso de contexto no se registran en el registro de actividad de mensajes, y la razón que pasas a abort_message no se muestra.

Retrasos en el envío con contenido conectado

Todos los usuarios de un lote se procesan antes de que cualquier usuario avance. Una vez completado el procesamiento del lote, los usuarios exitosos pasan al siguiente paso, mientras que los usuarios fallidos se reintentan por separado; los usuarios exitosos no esperan a que los reintentos tengan éxito antes de avanzar.

Comportamiento de reintentos

Las llamadas de contenido conectado en un Canvas solo se reintentan cuando la llamada incluye :retry.

• Pasos de contexto y de actualización de usuario: Braze reintenta la llamada de contenido conectado a nivel de paso (hasta cinco veces). Si todos los reintentos fallan, el usuario sale del Canvas.
• Pasos de mensaje: El contenido conectado con :retry sigue utilizando el pipeline de mensajería. Los destinatarios se retrasan en la cola de envío mientras Braze reintenta la llamada hasta cinco veces. Si todos los reintentos fallan, el mensaje se cancela y el usuario avanza al siguiente paso.

Para los pasos de contexto y de actualización de usuario, ciertos errores reintentables a nivel de paso, como una obtención fallida de código promocional o un error inesperado del paso, pueden desencadenar reintentos adicionales a nivel de paso con retirada exponencial (aproximadamente 13 veces) antes de que Braze haga salir al usuario del Canvas.

Para más información sobre la etiqueta :retry, consulta Reintentos de contenido conectado.

El tiempo que toma procesar a todos los usuarios a través de un paso de contexto depende de:

• El número de usuarios que ingresan al paso
• Si se utiliza contenido conectado (y su tiempo de respuesta)
• El tamaño del lote (predeterminado: 1000 usuarios por lote)

Si tu endpoint de contenido conectado tiene límites de velocidad, ten en cuenta que los pasos de contexto procesan a los usuarios de forma secuencial dentro de cada lote, lo que ayuda a respetar los límites de velocidad de forma natural. Sin embargo, múltiples lotes se procesan en paralelo, así que asegúrate de que tu endpoint pueda manejar solicitudes concurrentes de múltiples lotes.

Estandarización de consistencia de zona horaria

Con Canvas Context disponible de forma general, todas las propiedades de evento de marca de tiempo predeterminadas en Canvas basados en acciones están en UTC. Este cambio forma parte de un esfuerzo más amplio para garantizar una experiencia más predecible y consistente al editar pasos en Canvas y mensajes. Ten en cuenta que este cambio afecta a todos los Canvas basados en acciones, independientemente de si el Canvas específico está utilizando un paso de Context o no.

Importante

En todas las circunstancias, recomendamos encarecidamente usar filtros de zona horaria de Liquid para que las marcas de tiempo se representen en la zona horaria deseada. Puedes consultar esta pregunta frecuente para ver un ejemplo.

Preguntas frecuentes

¿Qué ha cambiado desde que el contexto de Canvas está disponible de forma general?

Ahora que el contexto de Canvas está disponible de forma general, se aplican los siguientes detalles:

• Todas las marcas de tiempo con un tipo datetime de las propiedades del evento desencadenante en Canvas basados en acciones están en UTC.
• Este cambio afecta a todos los Canvas basados en acciones, independientemente de que el Canvas específico esté utilizando un paso de contexto o no.

¿Cuál es el motivo de este cambio?

Este cambio forma parte de un esfuerzo más amplio para crear una experiencia más predecible y coherente al editar pasos y mensajes de Canvas.

¿Los Canvas activados por API o programados se ven afectados por este cambio?

No.

¿Este cambio afecta a las propiedades de entrada de Canvas?

Sí, esto afecta a canvas_entry_properties si la canvas_entry_property se está utilizando en un Canvas basado en acciones y el tipo de propiedad es time. En todos los casos, recomendamos utilizar filtros de Liquid time_zone para que las marcas de tiempo se representen en la zona horaria deseada.

A continuación se muestra un ejemplo de cómo hacerlo:

¿Cuál es un ejemplo práctico de cómo el nuevo comportamiento de las marcas de tiempo podría afectar mis mensajes?

Supongamos que tenemos un Canvas basado en acciones con el siguiente contenido en un paso de mensaje:

1

Your appointment is scheduled for {{canvas_entry_properties.${appointment_time} | date: "%Y-%m-%d %l:%M %p"}}, we'll see you then!

Esto da como resultado el siguiente mensaje:

1

Your appointment is scheduled for 2025-08-05 4:15 PM, we’ll see you then!

Dado que no se especifica ninguna zona horaria con Liquid, la marca de tiempo aquí está en UTC.

Para especificar una zona horaria de forma clara, podemos utilizar filtros de Liquid time_zone de esta manera:

1

Your appointment is scheduled for {{canvas_entry_properties.${appointment_time} | time_zone: "America/Los_Angeles" | date: "%Y-%m-%d %l:%M %p"}}, we'll see you then!

Esto da como resultado el siguiente mensaje:

1

Your appointment is scheduled for 2025-08-05 8:15 AM, we'll see you then!

Dado que se especifica la zona horaria America/Los Angeles con Liquid, la marca de tiempo aquí está en PST.

La zona horaria preferida también se puede enviar en la carga útil de las propiedades del evento y utilizarse en la lógica de Liquid:

1
2
3
4

{
  "appointment_time": "2025-08-05T08:15:30:250-0800"
  "user_timezone": "America/Los_Angeles"
}

¿En qué se diferencian las variables de contexto de las propiedades de entrada de Canvas?

Las propiedades de entrada de Canvas se incluyen como variables de contexto de Canvas. Esto significa que puedes enviar propiedades de entrada de Canvas mediante la API de Braze y hacer referencia a ellas en otros pasos, de manera similar a como se utiliza una variable de contexto con el fragmento de código de Liquid.

¿Pueden las variables hacer referencia entre sí en un único paso de contexto?

Sí. Todas las variables de un paso de contexto se evalúan en secuencia, lo que significa que podrías tener las siguientes variables de contexto configuradas:

Esto también se aplica a múltiples pasos de contexto. Por ejemplo, imagina esta secuencia:

1. Un paso de contexto inicial crea una variable llamada JobInfo con el valor job_title.
2. Un paso de mensaje hace referencia a {{context.${JobInfo}}} y muestra job_title al usuario.
3. Más adelante, un paso de contexto actualiza la variable de contexto, cambiando el valor de JobInfo a job_description.
4. Todos los pasos posteriores que hacen referencia a JobInfo ahora utilizan el valor actualizado job_description.

Las variables de contexto utilizan su valor más reciente a lo largo del Canvas, y cada actualización afecta a todos los pasos posteriores que hacen referencia a esa variable.