Segment

A Segment é uma CDP que ajuda você a coletar, limpar e ativar os dados dos seus clientes.

A integração da Braze com a Segment permite rastrear seus usuários e encaminhar dados para vários provedores de análise de dados de usuários. A Segment permite que você:

• Sincronize o Segment Engage com a Braze para uso em Campaigns da Braze e na segmentação de Canvas.
• Importe dados entre as duas plataformas. Oferecemos uma integração lado a lado de SDK para seus aplicativos Android, iOS e web e uma integração de servidor para servidor para sincronizar seus dados com as REST APIs da Braze.
• Conecte os dados à Segment pelo Currents.

Pré-requisitos

Integração

Para integrar a Braze e a Segment, você deve configurar a Braze como um destino de acordo com o tipo de integração escolhido (modo de conexão). Se você é um cliente novo da Braze, pode transmitir dados históricos para a Braze usando os replays da Segment. Em seguida, você deve configurar os mapeamentos e testar sua integração para garantir um fluxo de dados suave entre a Braze e a Segment.

Etapa 1: Criar um destino Braze

Depois de configurar suas fontes com sucesso, você precisará configurar a Braze como um destino para cada fonte (iOS, Android, web, etc.). Você terá muitas opções para personalizar o fluxo de dados entre a Braze e a Segment usando as configurações de conexão.

Etapa 2: Escolher o framework de destino e o tipo de conexão

Na Segment, navegue até Destinations > Braze > Configure Braze > Select your Source > Setup.

Você pode integrar a fonte web da Segment (Analytics.js) e as bibliotecas nativas do lado do cliente com a Braze usando uma integração lado a lado (device-mode) ou uma integração servidor a servidor (cloud-mode).

Sua escolha de modo de conexão será determinada pelo tipo de fonte para a qual o destino está configurado.

Nota

Visite a Segment para saber mais sobre as duas opções de integração (modos de conexão), incluindo os benefícios de cada uma.

Integração SDK lado a lado

Também chamada de device-mode, essa integração mapeia o SDK da Segment e seus métodos para o SDK da Braze, permitindo acesso a todos os recursos que nosso SDK oferece, como push, mensagens no app e outros métodos nativos da Braze.

Nota

Ao usar o device-mode da Segment, deixe a Segment inicializar a Braze. Não inicialize também o SDK da Braze no seu app. O plugin de destino configura a Braze e abre sessões; uma segunda inicialização nativa pode registrar sessões duplicadas. Use o identify da Segment para definir o ID do usuário. O plugin mapeia essa chamada para changeUser().

Importante

Para integrações device-mode em dispositivos móveis, você deve adicionar o plugin de destino da Braze ao seu app além de configurar o destino no dashboard da Segment. O SDK da Segment não inclui o plugin da Braze por padrão — sem ele, o SDK da Segment não consegue encaminhar dados ou chamadas de métodos mapeados para a Braze, e recursos como push, mensagens no app e Content Cards não funcionarão. Consulte as guias específicas por plataforma nesta seção para instruções de instalação.

Ao usar uma conexão device-mode, de forma semelhante à integração nativa do SDK da Braze, o SDK da Braze atribuirá um device_id e um identificador de backend, braze_id, a cada usuário. Isso permite que a Braze capture atividade anônima do dispositivo correspondendo esses identificadores em vez do userId.

Nota

Se você usa filtros de destino com destinos device-mode (Kotlin ou Swift), deve configurar o plugin de destino com o suporte a filtros ativado. Consulte a documentação de filtros de destino da Segment para detalhes sobre as versões de plugin suportadas.

• android
• ios
• web ou javascript
• react native

Importante

O código-fonte da integração device-mode para Android é mantido pela Braze e atualizado regularmente para refletir novos lançamentos do SDK da Braze.

O SDK da Braze que você usa dependerá de qual SDK da Segment você utiliza:

	SDK da Segment	SDK da Braze
Preferido	Analytics-Kotlin	Braze Segment Kotlin
Legado	Analytics-Android	Braze Segment Android

Para configurar a Braze como um destino device-mode para sua fonte Android, escolha Actions como o Destination framework e depois selecione Save.

Para concluir a integração lado a lado, você deve adicionar o plugin de destino Braze Kotlin ao seu app Android. Esse plugin faz a ponte entre o SDK da Segment e o SDK da Braze, permitindo que os dados em device-mode fluam para a Braze. Siga as instruções de instalação da Segment para adicionar a dependência do plugin e inicializá-lo com sua instância de analytics da Segment.

O código-fonte da integração device-mode para Android é mantido pela Braze e atualizado regularmente para refletir novos lançamentos do SDK da Braze.

Importante

O código-fonte da integração device-mode para iOS é mantido pela Braze e atualizado regularmente para refletir novos lançamentos do SDK da Braze.

O SDK da Braze que você usa dependerá de qual SDK da Segment você utiliza:

	SDK da Segment	SDK da Braze
Preferido	Analytics-Swift	Braze Segment Swift
Legado	Analytics-iOS	Braze Segment iOS

Para configurar a Braze como um destino device-mode para sua fonte iOS, escolha Actions como o Destination framework e depois selecione Save.

Para concluir a integração lado a lado, você deve adicionar o plugin de destino Braze Swift ao seu app iOS. Esse plugin faz a ponte entre o SDK da Segment e o SDK da Braze, permitindo que os dados em device-mode fluam para a Braze. Siga as instruções de instalação da Segment para adicionar a dependência do plugin (via Swift Package Manager ou CocoaPods) e inicializá-lo com sua instância de analytics da Segment.

O código-fonte da integração device-mode para iOS é mantido pela Braze e atualizado regularmente para refletir novos lançamentos do SDK da Braze.

O framework Braze Web Mode (Actions) da Segment é recomendado para configurar a Braze como um destino device-mode para sua fonte web.

Na Segment, selecione Actions como seu framework de destino e Device Mode como seu modo de conexão.

O código-fonte do plugin Braze para React Native é mantido pela Segment e atualizado regularmente para refletir novos lançamentos do SDK da Braze.

Ao conectar uma fonte React Native da Segment à Braze, você deve configurar uma fonte e um destino por sistema operacional. Por exemplo, configurar um destino iOS e um destino Android.

Na base de código do seu app, inicialize condicionalmente o SDK da Segment por tipo de dispositivo, usando a chave de escrita da fonte respectiva associada a cada app.

Quando um token por push é registrado em um dispositivo e enviado à Braze, ele é associado ao identificador de app usado na inicialização do SDK. A inicialização condicional por tipo de dispositivo ajuda a confirmar que quaisquer tokens por push enviados à Braze estão associados ao app relevante.

Importante

Se o app React Native inicializar a Braze com o mesmo identificador de app da Braze para todos os dispositivos, então todos os usuários do React Native serão considerados usuários Android ou iOS na Braze, e todos os tokens por push serão associados a esse sistema operacional.

Para configurar a Braze como um destino device-mode para cada fonte, escolha Actions como o Destination framework e depois selecione Save.

Integração servidor a servidor

Também chamada de cloud-mode, essa integração encaminha dados da Segment para as REST APIs da Braze. Use o framework Braze Cloud Mode (Actions) da Segment para configurar um destino cloud-mode para qualquer uma das suas fontes.

Diferente da integração lado a lado, a integração servidor a servidor não suporta recursos de interface da Braze, como mensagens no app, Content Cards ou registro automático de tokens por push. Também existem dados capturados automaticamente (como usuários anônimos e campos no nível do dispositivo) que não estão disponíveis via cloud-mode.

Se você deseja usar esses dados e recursos, considere usar a integração SDK lado a lado (device-mode).

O código-fonte do destino Braze Cloud Mode (Actions) é mantido pela Segment.

Etapa 3: Configurações

Defina as configurações do seu destino. Nem todas as configurações se aplicam a todos os tipos de destino.

• device-mode móvel
• device-mode web
• cloud-mode

Etapa 4: Mapear métodos

A Braze suporta os métodos Page, Identify e Track da Segment. Os tipos de identificadores usados nesses métodos dependerão de se os dados estão sendo enviados por meio de uma integração servidor a servidor (cloud-mode) ou lado a lado (device-mode). Nos destinos Braze Web Mode Actions e Cloud Mode Actions, você também pode optar por configurar um mapeamento para uma chamada de alias da Segment.

Nota

Embora aliases de usuário sejam suportados como identificador no destino Braze Cloud Mode (Actions), é importante notar que a chamada de alias da Segment não está diretamente relacionada aos aliases de usuário da Braze.

O destino Cloud Mode (Actions) oferece uma ação Create Alias que pode ser usada para criar um usuário somente com alias ou adicionar um alias a um perfil external_id existente. A ação Identify User pode ser usada junto com a ação Create Alias para mesclar um usuário somente com alias com um external_id depois que um se torna disponível para o usuário.

Também é possível criar uma solução alternativa e usar braze_id para enviar dados de usuários anônimos em cloud-mode. Isso requer incluir manualmente o braze_id do usuário em todas as suas chamadas de API da Segment. Você pode saber mais sobre como configurar essa solução alternativa na documentação da Segment.

Os dados de destinos enviados à Braze podem ser agrupados em lotes no Cloud Mode Actions. Os tamanhos de lote são limitados a 75 eventos, e esses lotes serão acumulados ao longo de um período de 30 segundos antes de serem enviados. O agrupamento em lotes de requisições é feito por ação. Por exemplo, chamadas Identify (atributos) serão agrupadas em uma requisição e chamadas Track (eventos personalizados) serão agrupadas em uma segunda requisição. A Braze recomenda ativar esse recurso, pois ele reduzirá o número de requisições enviadas da Segment para a Braze. Por sua vez, isso reduzirá o risco de o destino atingir os limites de frequência da Braze e ter que reenviar requisições.

Você pode ativar o agrupamento em lotes para uma ação navegando até seu destino Braze > Mappings. A partir daí, clique no ícone de 3 pontos ao lado do mapeamento e selecione Edit Mapping. Role até o final da seção Select mappings e certifique-se de que Batch Data to Braze esteja definido como Yes.

• identify
• track
• page

Identify

A chamada Identify permite vincular um usuário às suas ações e registrar atributos sobre ele.

Certas traits especiais da Segment são mapeadas para campos de atributos padrão de perfil na Braze:

Traits especiais da Segment	Atributos padrão da Braze
userId	external_id
firstName	first_name
lastName	last_name
email	email
birthday	dob
address.country	country
address.city	home_city
gender	gender

Outros campos de perfil reservados da Braze, como email_subscribe e push_subscribe, podem ser enviados usando a convenção de nomenclatura da Braze para esses campos e passando-os como traits em uma chamada identify.

Adicionando um usuário a um grupo de inscrições

Você também pode inscrever ou cancelar a inscrição de um usuário em um determinado grupo de inscrições usando os seguintes campos no parâmetro de traits.

Use o campo de perfil reservado da Braze chamado braze_subscription_groups, que pode ser associado a um array de objetos. Cada objeto no array deve ter duas chaves reservadas:

1. subscription_group_state: Indica se o usuário está "subscribed" ou "unsubscribed" em um grupo de inscrições específico.
2. subscription_group_id: Representa o ID único do grupo de inscrições. Você pode encontrar este ID no dashboard da Braze em Subscription Group Management.

• swift
• kotlin
• typescript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
analytics.identify(
  userId: "{your-user}",
  traits: [
    "braze_subscription_groups": [
      [
        "subscription_group_id": "{your-group-id}",
        "subscription_group_state": "subscribed"
      ],
      [
        "subscription_group_id", "{your-group-id}",
        "subscription_group_state": "unsubscribed"
      ]
    ]
  ]
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
analytics.identify(
  "{your-user}",
  buildJsonObject {
    put("braze_subscription_groups", buildJsonArray {
        add(
          buildJsonObject {
            put("subscription_group_id", "{your-group-id}")
            put("subscription_group_state", "subscribed")
          }
        )
        add(
          buildJsonObject {
            put("subscription_group_id", "{your-group-id}")
            put("subscription_group_state", "unsubscribed")
          }
        )
      }
    )
  }
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
analytics.identify(
  "{your-user}",
  {
    braze_subscription_groups: [
      {
        subscription_group_id: "{your-group-id}",
        subscription_group_state: "subscribed"
      },
      {
        subscription_group_id: "{your-group-id}",
        subscription_group_state: "unsubscribed"
      }
    ]
  }
)

Atributos personalizados

Todas as outras traits serão registradas como atributos personalizados.

Método da Segment	Método da Braze	Exemplo
Identify com ID de usuário	Definir ID externo	Segment: analytics.identify("dawei"); Braze: Braze.changeUser("dawei")
Identify com traits reservadas	Definir atributos de usuário	Segment: analytics.identify({email: "[email protected]"}); Braze: Braze.getUser().setEmail("[email protected]");
Identify com traits personalizadas	Definir atributos personalizados	Segment: analytics.identify({fav_cartoon: "Naruto"}); Braze: Braze.getUser().setCustomAttribute("fav_cartoon": "Naruto");
Identify com ID de usuário e traits	Segment: Definir ID externo e atributo	Combine os métodos anteriores.

Nos destinos Web Mode Actions e Cloud Mode Actions, esses mapeamentos podem ser configurados usando a ação Update User Profile.

Importante

Ao passar dados de atributos de usuário, verifique se você está passando apenas valores para atributos que mudaram desde a última atualização. Isso garantirá que você não registre pontos de dados desnecessariamente. Para fontes do lado do cliente, use a ferramenta de código aberto Middleware da Segment para otimizar sua integração e limitar o uso de pontos de dados fazendo debounce de chamadas identify() duplicadas da Segment.

Track

Quando você rastreia um evento, nós registraremos esse evento como um evento personalizado usando o nome fornecido.

Metadados enviados no objeto de propriedades da chamada track serão registrados na Braze como as propriedades do evento personalizado para o evento associado. Todos os tipos de dados de propriedades de eventos personalizados são suportados.

Nos destinos Web Mode Actions e Cloud Mode Actions, esses mapeamentos podem ser configurados usando a ação Track Event.

Método da Segment	Método da Braze	Exemplo
Track	Registrado como um evento personalizado.	Segment: analytics.track("played_game"); Braze: Braze.logCustomEvent("played_game");
Track com propriedades	Registrado como propriedade do evento.	Segment: analytics.track("played_game", {name: "BotW", weapon: "boomerang"}); Braze: Braze.logCustomEvent("played_game", { "name": "BotW", "weapon": "boomerang"});
Track com produto	Registrado como um evento de compra.	Segment: analytics.track("Order Completed", {products: [product_id: "ab12", price: 19]}); Braze: Braze.logPurchase("ab12", 19);

Pedido concluído

Quando você rastreia um evento com o nome Order Completed usando o formato descrito na API de eCommerce da Segment, nós registraremos os produtos listados como compras.

Nos destinos Web Mode Actions e Cloud Mode Actions, o mapeamento padrão pode ser personalizado por meio da ação Track Purchase.

Page

A chamada Page permite registrar sempre que um usuário visualiza uma página do seu website, junto com quaisquer propriedades opcionais sobre a página.

Esse tipo de evento pode ser usado como gatilho nos destinos Web Mode Actions e Cloud Actions para registrar um evento personalizado na Braze.

Etapa 5: Testar sua integração

Ao usar a integração lado a lado (device-mode), suas métricas de visão geral (sessões vitalícias, MAU, DAU, aderência, sessões diárias e sessões diárias por MAU) podem ser usadas para garantir que a Braze está recebendo dados da Segment.

Você pode visualizar seus dados nas páginas de eventos personalizados ou receita, ou criando um Segment. A página Custom Events do dashboard permite visualizar contagens de eventos personalizados ao longo do tempo. Note que você não poderá usar fórmulas que incluem estatísticas de MAU e DAU ao usar uma integração servidor a servidor (cloud-mode).

Se você está enviando dados de compra para a Braze (veja pedido concluído na guia Track da Etapa 3), a página de receita permite visualizar dados de receita ou compras em períodos específicos ou a receita total do seu app.

Criar um Segment permite filtrar seus usuários com base nos dados de eventos personalizados e atributos.

Importante

Se você usa uma integração servidor a servidor (cloud-mode), filtros relacionados a dados de sessão capturados automaticamente (como “primeiro uso do app” e “último uso do app”) não funcionarão. Use uma integração lado a lado (device-mode) se quiser usar esses filtros na sua integração entre Segment e Braze.

Exclusão e supressão de usuários

Se você precisar excluir ou suprimir usuários, observe que o recurso de exclusão de usuários da Segment está mapeado para o endpoint /users/delete da Braze. A verificação dessas exclusões pode levar até 30 dias.

Você precisa garantir que selecionou um identificador de usuário comum entre a Braze e a Segment (como o external_id). Após iniciar uma solicitação de exclusão com a Segment, você pode visualizar o status na guia de solicitações de exclusão no seu dashboard da Segment.

Replays da Segment

A Segment oferece um serviço para seus clientes que permite “reproduzir” todos os dados históricos para uma nova parceira de tecnologia. Novos clientes da Braze que desejam importar todos os dados históricos relevantes podem fazer isso por meio da Segment. Fale com seu representante da Segment se isso for do seu interesse.

A Segment se conectará ao nosso endpoint /users/track para importar dados de usuários na Braze em seu nome.

Importante

Todos os identificadores compatíveis com o destino Cloud Mode Actions são compatíveis como parte dos Replays da Segment.

Práticas recomendadas

Nuances no mapeamento de dados.

Cenários em que os dados não serão transmitidos conforme esperado:

1. Atributos personalizados aninhados
   • Embora atributos personalizados aninhados possam tecnicamente ser enviados para a Braze por meio da Segment, a carga útil inteira será enviada a cada vez. Isso consumirá pontos de dados por chave transmitida no objeto aninhado a cada envio da carga útil.
     
     Para consumir apenas um subconjunto de pontos de dados ao enviar a carga útil, você pode usar o recurso de funções de destino personalizadas da Segment. Esse recurso na plataforma da Segment permite que você personalize como os dados são enviados para destinos downstream.

Nota

As funções de destino personalizadas são controladas dentro da Segment, e a Braze tem visibilidade limitada sobre funções que foram configuradas externamente.

2. Transmissão de dados anônimos de servidor para servidor.
   • Os clientes podem usar as bibliotecas de servidor para servidor da Segment para direcionar dados anônimos para outros sistemas. Consulte a seção sobre métodos de mapeamento para saber mais sobre como enviar usuários sem um external_id para a Braze por meio de uma integração de servidor para servidor (modo nuvem).