Skip to content

Exportação de Currents personalizada

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 personalizado do Currents 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 apps na Braze, precisará configurar um conector personalizado do Currents para cada grupo. No entanto, você pode apontar todos os grupos de apps 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é Partner Integrations > Data Export, clique em Create New Current e selecione Custom Currents Export.

Dê um nome à sua exportação e insira um e-mail de contato, depois prossiga para a página Current Details. 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 você deseja exportar, e clique em Launch Current.

Eventos do Currents compatíveis

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

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

Prevenção contra 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 tempo de inatividade.

Para a maioria dos tipos de erro (como erros de servidor e erros de conexão de rede), a Braze tentará reenviar as transmissões de eventos ativamente. 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 tipos de evento.

Normalmente, enviamos um aviso com duas semanas de antecedência para 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 e serialização

O formato de dados de destino é JSON via 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 contendo 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 requisiçã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 (assim 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

Os 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 sejam opcionais, 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==, o seu cabeçalho Authorization deve ser semelhante ao seguinte:

1

Authorization: Bearer 0p3n5354m3==

Versionamento

Todas as requisições da nossa integração com o conector HTTP serão enviadas com um cabeçalho personalizado que designa a versão da requisiçã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 muita frequência, se é que algum dia será incrementado.

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

  1. Campos de evento específicos têm a garantia de sempre manter o mesmo tipo de dado 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 colocará a solicitação na fila e fará uma nova tentativa 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 permanentemente perdidos, e eventos já na fila serão permanentemente descartados após serem retidos por 7 dias. Se os dados ficarem parados 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 na seção a seguir.

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

Qualquer código de erro HTTP não listado na seção a seguir será tratado como um erro HTTP 5XX.

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