Skip to content

Conector HTTP personalizado

Saiba como integrar um conector Currents personalizado para receber dados de eventos da Braze em tempo real, possibilitando análises, relatórios e automações mais personalizados.

Pré-requisitos

Para integrar um conector Currents personalizado na Braze, você precisará fornecer uma URL de endpoint e um token de autenticação opcional.

Além disso, se você tiver mais de um grupo de app na Braze, precisará configurar um conector Currents personalizado para cada grupo. No entanto, você pode direcionar todos os grupos de app para o mesmo endpoint, ou para um endpoint com um parâmetro GET adicional, como your_app_group_key="Brand A".

Integração

Etapa 1: Configure seu endpoint

Você precisará de uma URL de endpoint para configurar essa integração. Seu endpoint deve ser capaz de receber solicitações HTTP POST e retornar um código de status 2XX para confirmar o recebimento bem-sucedido dos eventos. Se quiser autenticar as solicitações da Braze, você também precisará de um token bearer.

Etapa 2: Configure o Braze Currents

Na Braze, navegue até Integrações de parceiros > Exportação de dados, clique em Criar nova corrente e selecione Exportação de Currents personalizada.

Dê um nome à sua exportação e um e-mail de contato, depois prossiga para a página Informações da corrente. Nessa página, insira a URL do seu endpoint e o token bearer opcional.

Após configurar suas credenciais, marque todos os eventos de engajamento com mensagem, comportamento do cliente e eventos de usuário que deseja exportar, e clique em Lançar corrente.

Eventos do Currents compatíveis

A Braze oferece suporte à exportação dos seguintes dados para o seu conector HTTP personalizado:

Para ver a estrutura da carga útil de cada evento, selecione a guia Custom HTTP Connector no glossário de eventos.

Prevenção de perda de dados

Monitoramento de erros

Para evitar perda de dados e interrupção do serviço, é essencial que você monitore seus endpoints o tempo todo e resolva prontamente quaisquer erros ou períodos de inatividade.

Para a maioria dos tipos de erro (como erros de servidor e erros de conexão de rede), a Braze tentará reenviar ativamente as transmissões de eventos. Se o problema persistir por mais de 5 dias, a integração será desativada automaticamente. Novos eventos recebidos serão descartados e perdidos permanentemente.

Resiliência a mudanças

Ocasionalmente, faremos alterações não disruptivas nos esquemas do Braze Currents. Alterações não disruptivas são novas colunas anuláveis ou novos tipos de evento.

Normalmente, avisamos com duas semanas de antecedência sobre essas mudanças, mas às vezes isso não é possível. É essencial que você projete sua integração para lidar com campos ou tipos de evento não reconhecidos, caso contrário, isso provavelmente levará à perda de dados.

Agrupamento em lotes e serialização

O formato de dados de destino é JSON sobre HTTPS. Por padrão, os eventos são enviados ao seu endpoint em lotes de até 100 eventos cada.

Os eventos são enviados ao endpoint como um array JSON de todos os eventos no seguinte formato:

1

{"events": [event1, event2, event3, etc...]}

Haverá um objeto JSON de nível superior com a chave "events" que mapeia para um array de outros objetos JSON, cada um representando um único evento. Cada evento contém dois subobjetos:

Se um endpoint downstream receber uma carga útil com zero eventos ou um corpo de solicitação vazio, o resultado deve ser considerado um no-op, ou seja, nenhum efeito downstream deve ocorrer a partir dessa chamada. No entanto, você ainda deve verificar o cabeçalho Authorization (como faria em uma chamada de API normal) e retornar uma resposta HTTP apropriada para credenciais inválidas, como 401 ou 403. Isso permite que a Braze saiba que as credenciais do conector são válidas.

Autenticação

Tokens de autenticação na sua carga útil são opcionais. Eles podem ser passados por meio de um cabeçalho HTTP Authorization usando o esquema de autorização Bearer, conforme especificado na RFC 6750. Embora opcional, se um token de autenticação for passado, a Braze sempre o validará primeiro—mesmo que não haja eventos na carga útil.

De acordo com a RFC 6750, os tokens devem ser valores codificados em Base64 com pelo menos um caractere. Tenha em mente que a RFC 6750 permite que os tokens contenham os seguintes caracteres além dos caracteres Base64 normais: -, ., _ e ~. Você pode escolher se deseja incluir esses caracteres no seu token ou não—no entanto, ele deve estar no formato Base64.

Além disso, se o cabeçalho Authorization estiver presente, ele será construído usando o seguinte formato:

1

"Authorization: Bearer " + <token>

Por exemplo, se o seu token de autenticação for 0p3n5354m3==, seu cabeçalho Authorization deve ser semelhante ao seguinte:

1

Authorization: Bearer 0p3n5354m3==

Versionamento

Todas as solicitações da nossa integração de conector HTTP serão enviadas com um cabeçalho personalizado que designa a versão da solicitação do Currents sendo feita:

1

Braze-Currents-Version: 1

A versão será sempre 1, pois não esperamos incrementar esse número com frequência, se é que algum dia.

Assim como nossos esquemas de armazenamento em data warehouse, cada campo de evento em um evento individual tem garantia de compatibilidade retroativa com versões anteriores da carga útil de eventos, de acordo com a definição de compatibilidade retroativa do Apache Avro:

  1. Campos de evento específicos têm garantia de sempre manter o mesmo tipo de dados ao longo do tempo.
  2. Quaisquer novos campos adicionados à carga útil ao longo do tempo devem ser considerados opcionais por todas as partes.
  3. Campos obrigatórios nunca serão removidos.

Tratamento de erros e mecanismo de nova tentativa

Se ocorrer um erro, a Braze enfileirará e tentará reenviar a solicitação com base no código de retorno HTTP recebido. Se o problema persistir por mais de 5 dias, a integração será desativada automaticamente: novos eventos recebidos serão descartados e perdidos permanentemente, e eventos já enfileirados serão descartados permanentemente após serem retidos por 7 dias. Se os dados ficarem presos por mais de 24 horas, nossos engenheiros de plantão serão alertados automaticamente. Para uma análise completa de como cada código de status é tratado, consulte a tabela abaixo.

Se a sua integração do Currents estiver retornando erros de autenticação, a Braze enviará automaticamente um e-mail de notificação para você.

Qualquer código de erro HTTP não listado abaixo será tratado como um erro HTTP 5XX.

Os seguintes códigos de status HTTP serão reconhecidos pelo nosso cliente conector:
New Stuff!