Objeto de público conectado

Um público conectado é um filtro de público dinâmico que você define inline na sua requisição de API, permitindo direcionar os usuários certos no momento do envio sem precisar criar ou gerenciar Segments no dashboard da Braze.

Em vez de pré-criar um Segment para cada combinação possível de público, você passa os critérios de filtro diretamente na sua chamada de API. Dependendo do endpoint, esse objeto é passado como audience ou custom_audience. A Braze avalia cada usuário em relação a esses critérios em tempo real e entrega a mensagem apenas aos usuários que correspondem. Isso significa que uma única Campaign, Canvas ou definição de mensagem somente via API pode atender a um número ilimitado de variações de público, totalmente orientadas pela sua lógica de negócios.

Como funciona

1. Defina sua mensagem criando uma Campaign ou um Canvas disparado por API no dashboard da Braze, ou defina o conteúdo da mensagem inteiramente inline usando os objetos de mensagem na sua requisição de API. Use propriedades de disparo ou contexto do Canvas para personalização dinâmica.
2. Faça uma chamada a um endpoint compatível e inclua seus filtros de público conectado no parâmetro audience, ou em custom_audience para /messages/live_activity/start. Você pode filtrar por atributos personalizados, status de inscrição em push, status de inscrição em e-mail e horário do último uso do app.
3. A Braze avalia os filtros no momento do envio, entregando a mensagem apenas aos usuários que correspondem aos seus critérios.

Dica

Um campaign_id não é necessário ao usar o parâmetro audience. Os endpoints /messages/send e /messages/schedule/create permitem definir o conteúdo da mensagem inline sem uma Campaign pré-criada. No entanto, se você quiser rastrear métricas no nível da Campaign (como envios, cliques ou bounces) no dashboard, inclua um campaign_id.

Como o público é definido por requisição, seus sistemas de backend podem disparar mensagens contextualmente relevantes em resposta a qualquer evento de negócio (uma mudança de preço, um alerta meteorológico, uma atualização de placar ao vivo) sem intervenção no dashboard.

Endpoints compatíveis

Você pode usar o objeto de público conectado nos seguintes 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)

Observe que o parâmetro audience não aceita array de objetos.

Casos de uso

Use públicos conectados para cenários em que seus sistemas de backend detectam um evento e precisam notificar um conjunto de usuários determinado dinamicamente:

Em cada caso, uma única Campaign ou definição de mensagem somente via API lida com todas as variações. Seu backend determina os valores do filtro e os passa na requisição da API, então você não precisa criar um Segment ou Campaign separado para cada produto, série, time ou local.

Exemplo de solicitação

O exemplo a seguir usa o endpoint /campaigns/trigger/send para direcionar usuários que favoritaram um programa específico e aceitaram receber notificações por 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
}

Corpo do objeto

O objeto de público conectado é composto por um único filtro de público conectado ou por vários filtros de público conectado combinados com os operadores AND e OR.

Exemplo com vários 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 público conectado

Combine vários filtros com os operadores AND e OR para criar um filtro de público conectado.

Considerações

Os públicos conectados não podem filtrar usuários por:

• Atributos padrão
• Eventos personalizados
• Segments
• Eventos de engajamento com mensagem
• Atributos personalizados aninhados

Para usar esses filtros, recomendamos incorporá-los a um Segment de público e, em seguida, especificar esse Segment no parâmetro segment_id do endpoint /messages/send. Ao usar outros endpoints, você deve primeiro adicionar o Segment à Campaign ou ao Canvas disparado por API no dashboard da Braze. Se você precisar filtrar por atributos aninhados, use um Segment padrão.

Filtro de atributo personalizado

Esse filtro permite segmentar com base em um atributo personalizado do usuário. Esses filtros contêm até três 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
    }
}

Comparações permitidas por tipo de dados

O tipo de dados do atributo personalizado determina quais comparações são válidas para um determinado filtro.

Ressalvas sobre comparações de atributos

Comparações com múltiplos valores

Tanto is_any_of quanto is_none_of suportam correspondência com múltiplos valores em uma única comparação. Essas comparações funcionam com atributos personalizados do tipo string e array.

• is_any_of: Corresponde a usuários cujo valor do atributo é igual a qualquer um dos valores fornecidos. O value pode ser uma única string ou um array de strings.
• is_none_of: Corresponde a usuários cujo valor do atributo não corresponde a nenhum dos valores fornecidos. O value pode ser uma única string ou um array de strings. Observe que usuários que não possuem o atributo em seu perfil sempre se qualificam para essa comparação.

Para atributos do tipo array:

• includes_value também pode aceitar um array de valores para verificar se o array do usuário contém qualquer um dos valores especificados.
• Ao usar is_any_of ou is_none_of com atributos do tipo array, eles funcionam da mesma forma que includes_value e does_not_include_value, respectivamente.

Dica

Para correspondência com múltiplos valores, use is_any_of em vez de includes_value.

Exemplos 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
  }
}

Exemplos de comparações com múltiplos valores

is_any_of com um array de strings

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 com um array de strings

1
2
3
4
5
6
7
8

{
  "custom_attribute":
  {
    "custom_attribute_name": "subscription_tier",
    "comparison": "is_none_of",
    "value": ["bronze", "silver"]
  }
}

includes_value com um array (atributo do tipo array)

1
2
3
4
5
6
7
8

{
  "custom_attribute":
  {
    "custom_attribute_name": "subscribed_products",
    "comparison": "includes_value",
    "value": ["1001", "1002", "1003"]
  }
}

Isso corresponde a usuários cujo array subscribed_products contém qualquer um dos valores "1001", "1002" ou "1003".

Filtro de inscrição para push

Esse filtro permite segmentar com base no status de inscrição para push do usuário.

Corpo do 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
  }
}

• Comparações permitidas: is, is_not
• Valores permitidos: opted_in, subscribed, unsubscribed

Filtro de inscrição para e-mail

Esse filtro permite segmentar com base no status de inscrição para e-mail do usuário.

Corpo do 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
  }
}

• Comparações permitidas: is, is_not
• Valores permitidos: opted_in, subscribed, unsubscribed

Filtro de último uso do app

Esse filtro permite segmentar com base na última vez que o usuário usou o app. Esses filtros contêm dois campos:

Corpo do 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
  }
}

• Comparações permitidas: after, before
• Valores permitidos: data/hora (string ISO 8601)