Objeto de audiencia conectada

Una audiencia conectada es un filtro de audiencia dinámico que defines en línea dentro de tu solicitud de API, para que puedas dirigirte a los usuarios correctos en el momento del envío sin crear ni gestionar segmentos en el panel de Braze.

En lugar de crear previamente un segmento para cada posible combinación de audiencia, pasas los criterios de filtro directamente en tu llamada a la API. Dependiendo del endpoint, este objeto se pasa como audience o custom_audience. Braze evalúa a cada usuario contra esos criterios en tiempo real y entrega el mensaje solo a los usuarios que coincidan. Esto significa que una sola Campaign, Canvas o definición de mensaje solo de API puede servir a un número ilimitado de variaciones de audiencia, impulsadas completamente por tu lógica de negocio.

Cómo funciona

1. Define tu mensaje creando una Campaign o un Canvas activados por API en el panel de Braze, o define el contenido del mensaje completamente en línea usando los objetos de mensajería en tu solicitud de API. Usa las propiedades de activación o el contexto de Canvas para la personalización dinámica.
2. Llama a un endpoint compatible e incluye tus filtros de audiencia conectada en el parámetro audience, o en custom_audience para /messages/live_activity/start. Puedes filtrar por atributos personalizados, estado de suscripción push, estado de suscripción de correo electrónico y hora de último uso de la aplicación.
3. Braze evalúa los filtros en el momento del envío, entregando el mensaje solo a los usuarios que coincidan con tus criterios.

Consejo

No se requiere un campaign_id cuando se usa el parámetro audience. Los endpoints /messages/send y /messages/schedule/create te permiten definir el contenido del mensaje en línea sin una Campaign creada previamente. Sin embargo, si deseas rastrear métricas a nivel de Campaign (como envíos, clics o rebotes) en el panel, incluye un campaign_id.

Dado que la audiencia se define por solicitud, tus sistemas de backend pueden activar mensajes contextualmente relevantes en respuesta a cualquier evento de negocio (un cambio de precio, una alerta meteorológica, una actualización de puntuación en vivo) sin intervención del panel.

Endpoints compatibles

Puedes usar el objeto de audiencia conectada en estos endpoints:

• /messages/send
• /campaigns/trigger/send
• /canvas/trigger/send
• /messages/schedule/create
• /campaigns/trigger/schedule/create
• /canvas/trigger/schedule/create
• /messages/live_activity/start (usa custom_audience)

Ten en cuenta que el parámetro audience no admite matriz de objetos.

Ejemplos

Usa audiencias conectadas en escenarios donde tus sistemas de backend detectan un evento y necesitan notificar a un conjunto de usuarios determinado dinámicamente:

En cada caso, una sola Campaign o una definición de mensaje solo por API maneja todas las variaciones. Tu backend determina los valores de filtro y los pasa en la solicitud de API, por lo que no necesitas crear un Segment o una Campaign independiente para cada producto, programa, equipo o ubicación.

Ejemplo de solicitud

El siguiente ejemplo utiliza el endpoint /campaigns/trigger/send para dirigirse a los usuarios que han marcado como favorito un programa específico y han optado por recibir notificaciones push:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "campaign_id": "YOUR_CAMPAIGN_ID",
  "audience": {
    "AND": [
      {
        "custom_attribute": {
          "custom_attribute_name": "favorite_shows",
          "comparison": "includes_value",
          "value": "Example Show"
        }
      },
      {
        "push_subscription_status": {
          "comparison": "is",
          "value": "opted_in"
        }
      }
    ]
  },
  "trigger_properties": {
    "show_title": "Example Show",
    "episode_title": "Season 3, Episode 1",
    "deep_link": "https://example.com/shows/example-show/s3e1"
  },
  "broadcast": false
}

Cuerpo del objeto

El objeto de audiencia conectada se compone de un único filtro de audiencia conectada o de varios filtros de audiencia conectada combinados con los operadores AND y OR.

Ejemplo con múltiples filtros:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "AND":
    [
      Connected Audience Filter,
      {
        "OR" :
          [
            Connected Audience Filter,
            Connected Audience Filter
          ]
      },
      Connected Audience Filter
    ]
}

Filtros de audiencia conectada

Combina múltiples filtros con los operadores AND y OR para crear un filtro de audiencia conectada.

Consideraciones

Las audiencias conectadas no pueden filtrar usuarios por:

• Atributos predeterminados
• Eventos personalizados
• Segments
• Eventos de participación con mensajes
• Atributos personalizados anidados

Para utilizar estos filtros, te recomendamos incorporarlos en un Segment de audiencia y luego especificar ese Segment en el parámetro segment_id del endpoint /messages/send. Cuando utilices otros endpoints, primero debes añadir el Segment a la Campaign o Canvas activado por API en el panel de Braze. Si necesitas filtrar por atributos anidados, utiliza un Segment estándar en su lugar.

Filtro de atributo personalizado

Este filtro te permite segmentar en función de un atributo personalizado de un usuario. Estos filtros contienen hasta tres campos:

1
2
3
4
5
6
7
8
{
  "custom_attribute":
    {
      "custom_attribute_name": (String) the name of the custom attribute to filter on,
      "comparison": (String) one of the allowed comparisons to make against the provided value,
      "value": (String, Numeric, Boolean) the value to be compared using the provided comparison
    }
}

Comparaciones permitidas por tipo de datos

El tipo de datos del atributo personalizado determina las comparaciones que son válidas para un filtro determinado.

Advertencias sobre la comparación de atributos

Comparaciones de múltiples valores

Tanto is_any_of como is_none_of admiten la coincidencia con múltiples valores en una sola comparación. Estas comparaciones funcionan tanto con atributos personalizados de tipo cadena como de tipo matriz.

• is_any_of: Coincide con los usuarios cuyo valor de atributo es igual a cualquiera de los valores proporcionados. El value puede ser una sola cadena o una matriz de cadenas.
• is_none_of: Coincide con los usuarios cuyo valor de atributo no coincide con ninguno de los valores proporcionados. El value puede ser una sola cadena o una matriz de cadenas. Ten en cuenta que los usuarios que no tienen el atributo en su perfil siempre califican para esta comparación.

Para atributos de tipo matriz:

• includes_value también puede aceptar una matriz de valores para comprobar si la matriz del usuario contiene alguno de los valores especificados.
• Cuando se utilizan is_any_of o is_none_of con atributos de tipo matriz, funcionan de la misma manera que includes_value y does_not_include_value respectivamente.

Consejo

Para la coincidencia de múltiples valores, utiliza is_any_of en lugar de includes_value.

Ejemplos de atributos personalizados

1
2
3
4
5
6
7
8
{
  "custom_attribute":
    {
      "custom_attribute_name": "eye_color",
      "comparison": "equals",
      "value": "blue"
    }
}

1
2
3
4
5
6
7
8
{
  "custom_attribute":
  {
    "custom_attribute_name": "favorite_foods",
    "comparison": "includes_value",
    "value": "pizza"
  }
}

1
2
3
4
5
6
7
8
{
  "custom_attribute":
  {
    "custom_attribute_name": "last_purchase_time",
    "comparison": "less_than_x_days_ago",
    "value": 2
  }
}

Ejemplos de comparaciones de múltiples valores

is_any_of con una matriz de cadenas

1
2
3
4
5
6
7
8
{
  "custom_attribute":
  {
    "custom_attribute_name": "favorite_color",
    "comparison": "is_any_of",
    "value": ["red", "blue", "green"]
  }
}

is_none_of con una matriz de cadenas

1
2
3
4
5
6
7
8
{
  "custom_attribute":
  {
    "custom_attribute_name": "subscription_tier",
    "comparison": "is_none_of",
    "value": ["bronze", "silver"]
  }
}

includes_value con una matriz (atributo de tipo matriz)

1
2
3
4
5
6
7
8
{
  "custom_attribute":
  {
    "custom_attribute_name": "subscribed_products",
    "comparison": "includes_value",
    "value": ["1001", "1002", "1003"]
  }
}

Esto coincide con los usuarios cuya matriz subscribed_products contiene cualquiera de los valores "1001", "1002" o "1003".

Filtro de suscripción push

Este filtro te permite segmentar en función del estado de suscripción push de un usuario.

Cuerpo del filtro

1
2
3
4
5
6
7
{
  "push_subscription_status":
  {
    "comparison": (String) one of the following allowed comparisons,
    "value": (String) one of the following allowed values
  }
}

• Comparaciones permitidas: is, is_not
• Valores permitidos: opted_in, subscribed, unsubscribed

Filtro de suscripción de correo electrónico

Este filtro te permite segmentar en función del estado de suscripción de correo electrónico de un usuario.

Cuerpo del filtro

1
2
3
4
5
6
7
{
  "email_subscription_status":
  {
    "comparison": (String) one of the following allowed comparisons,
    "value": (String) one of the following allowed values
  }
}

• Comparaciones permitidas: is, is_not
• Valores permitidos: opted_in, subscribed, unsubscribed

Filtro de última aplicación utilizada

Este filtro te permite segmentar en función de cuándo el usuario utilizó la aplicación por última vez. Estos filtros contienen dos campos:

Cuerpo del filtro

1
2
3
4
5
6
7
{
  "last_used_app":
  {
    "comparison": (String) one of the allowed comparisons listed,
    "value": (String) the value to be compared using the provided comparison
  }
}

• Comparaciones permitidas: after, before
• Valores permitidos: fecha y hora (cadena ISO 8601)