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 Segments en el panel de Braze.

En lugar de crear previamente un Segment 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 desencadenamiento 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 realizar un seguimiento de las 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 desencadenar mensajes contextualmente relevantes en respuesta a cualquier evento de negocio (un cambio de precio, una alerta meteorológica, una actualización de marcador 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 definición de mensaje solo de 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 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 aceptado 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 solo 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 conectados

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

Consideraciones

Las audiencias conectadas no pueden filtrar usuarios por:

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

Para usar 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 uses otros endpoints, primero debes añadir el Segment a la Campaign o Canvas activados por API en el panel de Braze. Si necesitas filtrar por atributos anidados, usa un Segment estándar en su lugar.

Filtro de atributo personalizado

Este filtro te permite segmentar en función del 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 válidas para un filtro determinado.

Advertencias sobre 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 array.

• is_any_of: coincide con usuarios cuyo valor de atributo es igual a cualquiera de los valores proporcionados. El value puede ser una cadena única o un array de cadenas.
• is_none_of: coincide con usuarios cuyo valor de atributo no coincide con ninguno de los valores proporcionados. El value puede ser una cadena única o un array de cadenas. Ten en cuenta que los usuarios que no tengan el atributo en su perfil siempre cumplen con esta comparación.

Para atributos de tipo array:

• includes_value también puede aceptar un array de valores para comprobar si el array del usuario contiene alguno de los valores especificados.
• Cuando se usan is_any_of o is_none_of con atributos de tipo array, funcionan igual que includes_value y does_not_include_value respectivamente.

Consejo

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

Ejemplos de atributo personalizado

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 un array 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 un array 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 un array (atributo de tipo array)

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 usuarios cuyo array 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 usada

Este filtro te permite segmentar en función de cuándo el usuario usó 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: datetime (cadena ISO 8601)