Segmento

A Segment é uma plataforma de dados do cliente que ajuda você a coletar, limpar e ativar os dados de 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 da 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 definir a Braze como um destino de acordo com o tipo de integração escolhido (modo de conexão). Se você for um cliente novo na Braze, poderá retransmitir dados históricos para a Braze usando replays da Segment. Em seguida, você deve configurar mapeamentos e testar sua integração para garantir um fluxo de dados suave entre a Braze e a Segment.

Etapa 1: Crie um destino da Braze

Depois de configurar suas fontes com êxito, 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: Escolha a estrutura do 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 (modo dispositivo) ou uma integração servidor a servidor (modo nuvem).

Sua escolha do modo de conexão será determinada pelo tipo de fonte para o 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 lado a lado de SDK

Também chamada de modo dispositivo, essa integração mapeia o SDK e os métodos da Segment para o SDK da Braze, permitindo o acesso a todos os recursos do nosso SDK, como push, mensagens no app e outros métodos nativos da Braze.

Nota

Ao usar o modo de dispositivo da Segment, você não precisa integrar o Braze SDK diretamente. Ao adicionar a Braze como um destino do modo dispositivo para a Segment, o Segment SDK inicializará o Braze SDK e chamará os métodos mapeados relevantes da Braze.

Importante

Para integrações no modo dispositivo 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 Segment SDK não inclui o plugin da Braze por padrão — sem ele, o Segment SDK 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 abas específicas por plataforma abaixo para instruções de instalação.

Ao usar uma conexão no modo dispositivo, semelhante à integração nativa do Braze SDK, o Braze SDK atribuirá um device_id e um identificador de backend, braze_id, a cada usuário. Isso permite que a Braze capture a atividade anônima do dispositivo fazendo a correspondência com esses identificadores em vez de userId.

Nota

Se você usar filtros de destino com destinos no modo dispositivo (Kotlin ou Swift), será necessário 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 compatíveis.

• android
• ios
• web ou javascript
• react native

Importante

O código-fonte para a integração do modo de dispositivo Android é mantido pela Braze e é atualizado regularmente para refletir as novas versões do Braze SDK.

O Braze SDK a ser usado depende do Segment SDK que você usa:

	Segment SDK	Braze SDK
Preferencial	Analytics-Kotlin	Braze Segment Kotlin
Legado	Analytics-Android	Braze Segment Android

Para configurar a Braze como um destino de modo de dispositivo para sua origem Android, escolha Actions como a Destination framework e, em seguida, 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 Segment SDK e o Braze SDK, permitindo que os dados no modo dispositivo 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 para a integração do modo de dispositivo Android é mantido pela Braze e é atualizado regularmente para refletir as novas versões do Braze SDK.

Importante

O código-fonte para a integração do modo de dispositivo iOS é mantido pela Braze e é atualizado regularmente para refletir as novas versões do Braze SDK.

O Braze SDK a ser usado depende do Segment SDK que você usa:

	Segment SDK	Braze SDK
Preferencial	Analytics-Swift	Braze Segment Swift
Legado	Analytics-iOS	Braze Segment iOS

Para configurar a Braze como um destino no modo dispositivo para sua origem iOS, escolha Actions como a Destination framework e 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 Segment SDK e o Braze SDK, permitindo que os dados no modo dispositivo 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 do modo de dispositivo iOS é mantido pela Braze e é atualizado regularmente para refletir as novas versões do Braze SDK.

A estrutura Braze Web Mode (Actions) da Segment é recomendada para configurar a Braze como um destino de modo de dispositivo para sua fonte web.

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

O código-fonte do plugin React Native Braze é mantido pela Segment e é atualizado regularmente para refletir as novas versões do Braze SDK.

Ao conectar uma fonte React Native da Segment à Braze, configure uma origem e um destino por sistema operacional. Por exemplo, um destino para iOS e um destino para Android.

Na base de código do seu aplicativo, inicialize condicionalmente o Segment SDK por tipo de dispositivo, usando a respectiva chave de gravação de origem associada a cada app.

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

Importante

Se o aplicativo React Native inicializar a Braze com o mesmo identificador de aplicativo da Braze para todos os dispositivos, todos os usuários do React Native serão considerados usuários de 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 de modo de dispositivo para cada origem, selecione Actions como a Destination framework e, em seguida, selecione Save.

Integração de servidor para servidor

Também chamada de modo de nuvem, essa integração encaminha dados da Segment para as REST APIs da Braze. Use a estrutura Braze Cloud Mode (Actions) da Segment para configurar um destino em modo de nuvem para qualquer uma de suas origens.

Diferentemente da integração lado a lado, a integração servidor a servidor não oferece suporte aos recursos da interface do usuário da Braze, como mensagens no app, Content Cards ou registro automático de token 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 no modo de nuvem.

Se quiser usar esses dados e recursos, considere adotar a integração lado a lado (modo de dispositivo) do SDK.

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

Etapa 3: Configurações

Defina as configurações para seu destino. Nem todas as configurações se aplicarão a todos os tipos de destinos.

• mobile device-mode
• web device-mode
• cloud-mode

Etapa 4: Mapeie os métodos

A Braze oferece suporte aos métodos Page, Identify e Track da Segment. Os tipos de identificadores usados nesses métodos dependerão do fato de os dados estarem sendo enviados por meio de uma integração servidor a servidor (modo nuvem) ou lado a lado (modo dispositivo). 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 os aliases de usuário sejam suportados como um identificador no destino Braze Cloud Mode (Actions), deve-se 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 de alias ou adicionar um alias a um perfil external_id existente. A ação Identify User pode ser usada juntamente com a ação Create Alias para mesclar um usuário somente de alias com um external_id depois que um estiver disponível para o usuário.

Também é possível criar uma solução alternativa e usar o braze_id para enviar dados de usuários anônimos no modo de nuvem. Para isso, é necessário incluir manualmente o braze_id do usuário em todas as suas chamadas à 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 dentro do Cloud Mode Actions. Os tamanhos dos lotes são limitados a 75 eventos, e esses lotes se acumulam em um período de 30 segundos antes de serem descarregados. O agrupamento de solicitações é feito por ação. Por exemplo, as chamadas de identificação (atributos) serão agrupadas em uma solicitação e as chamadas de rastreamento (eventos personalizados) serão agrupadas em uma segunda solicitação. A Braze recomenda ativar esse recurso, pois ele reduz o número de solicitações enviadas da Segment para a Braze. Por sua vez, isso reduzirá o risco de o destino atingir os limites de taxa da Braze e tentar novamente as solicitações.

Você pode ativar a criação de lotes para uma ação navegando até Braze Destination > Mappings. A partir daí, clique no ícone de três pontos à direita do mapeamento e selecione Edit Mapping. Role até a parte inferior da seção Select mappings e verifique se a opção Batch Data to Braze está definida como Yes.

• identify
• track
• page

Identify

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

Certas características especiais da Segment são mapeadas para campos de perfil de atributo padrão na Braze:

Características 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 características em uma chamada de identificação.

Adição de um usuário a um grupo de inscrições

Também é possível inscrever ou cancelar a inscrição de um usuário em um determinado grupo de inscrições usando os seguintes campos no parâmetro traits.

Use o campo reservado do perfil da Braze chamado braze_subscription_groups, que pode ser associado a um vetor de objetos. Cada objeto do vetor 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 exclusivo do grupo de inscrições. Você pode encontrar esse ID no dashboard da Braze, em Gerenciamento de grupos de inscrições.

• 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 características serão registradas como atributos personalizados.

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

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

Importante

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

Track

Quando você rastrear um evento, registraremos esse evento como um evento personalizado usando o nome fornecido.

Os metadados enviados dentro do objeto de propriedades da chamada de rastreamento serão registrados na Braze como as propriedades de evento personalizado para o evento associado. Todos os tipos de dados de propriedades de eventos personalizados são compatíveis.

Nos destinos Web Mode Actions e Cloud Mode Actions, os mapeamentos acima podem ser definidos 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 de 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ê rastrear um evento com o nome Order Completed usando o formato descrito na API de eCommerce da Segment, registraremos os produtos que você listou como compras.

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

Page

A chamada Page permite registrar sempre que um usuário vê uma página do seu site, juntamente com quaisquer propriedades opcionais sobre a página.

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

Etapa 5: Teste sua integração

Ao usar a integração lado a lado (modo de dispositivo), suas métricas de visão geral (sessões vitalícias, MAU, usuário ativo diário, aderência, sessões diárias e sessões diárias por MAU) podem ser usadas para assegurar que a Braze receba dados da Segment.

Você pode visualizar seus dados nas páginas de eventos personalizados ou receita, ou criando um segmento. A página Eventos personalizados do dashboard permite que você visualize as contagens de eventos personalizados ao longo do tempo. Observe que você não poderá usar fórmulas que incluam estatísticas de MAU e DAU ao usar uma integração de servidor para servidor (modo de nuvem).

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

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

Importante

Se você usar uma integração de servidor para servidor (modo de nuvem), os filtros relacionados aos dados de sessão coletados automaticamente (como “primeiro app usado” e “último app usado”) não funcionarão. Use uma integração lado a lado (modo de dispositivo) se quiser usá-los na sua integração da Segment e da Braze.

Exclusão e supressão de usuários

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

É necessário selecionar um identificador de usuário comum entre a Braze e a Segment (como em external_id). Depois de iniciar uma solicitação de exclusão com a Segment, você pode visualizar o status na guia de solicitações de exclusão no dashboard da Segment.

Replays da Segment

A Segment presta um serviço aos clientes para “reproduzir” todos os dados históricos em um novo parceiro de tecnologia. Os novos clientes da Braze que desejarem importar todos os dados históricos relevantes poderão fazê-lo por meio da Segment. Fale com seu representante da Segment se isso for algo de seu interesse.

A Segment se conectará ao nosso endpoint /users/track para importar dados de usuários para a 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.

Melhores práticas

Nuances do mapeamento de dados.

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

1. Atributos personalizados aninhados
   • Embora os atributos personalizados aninhados possam tecnicamente ser enviados à Braze por meio da Segment, toda a carga útil será enviada a cada vez. Isso incorrerá em pontos de dados por chave passada no objeto aninhado toda vez que a carga útil for enviada.
     
     Para gastar apenas um subconjunto de pontos de dados quando a carga útil é enviada, você pode usar o recurso de funções de destino personalizadas pertencente à Segment. Esse recurso da plataforma Segment permite que você personalize a forma como os dados são enviados para destinos downstream.

Nota

As funções de destinos personalizados são controladas na Segment, e a Braze tem insight limitado sobre as funções que foram configuradas externamente.

2. Passagem de dados anônimos de servidor para servidor.
   • Os clientes podem usar as bibliotecas de servidor para servidor da Segment para canalizar dados anônimos para outros sistemas. Consulte a seção de mapeamento de métodos 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 de nuvem).