Perguntas frequentes

Esta página fornece respostas para algumas perguntas frequentes sobre o Currents.

Posso exportar dados de Campaign ou Canvas para um período específico?

Para obter métricas de Campaign ou Canvas em um intervalo de datas definido, use uma das seguintes abordagens:

• Se você tem interesse em date-aligned campaign or Canvas exports for dashboard-style reporting outside standard API windows, envie feedback de produto.
• Chame os endpoints de análise de dados de campanha ou de análise de dados de Canvas com os parâmetros ending_at e length (ou use /campaigns/data_series e /canvas/data_series) para obter dados de séries temporais.
• Transmita eventos para o seu data warehouse com o Currents quando precisar de dados contínuos e consultáveis de engajamento com mensagens no Amazon S3, no Azure Blob Storage ou em outro destino compatível.

Como editar uma integração ativa do Currents?

Para alterar um conector ativo do Currents, abra a integração e selecione Editar. Sem selecionar Editar, a interface da integração fica somente leitura e você não consegue modificar as configurações do conector apenas pelos ícones.

Como a Braze lida com os arquivos Avro no Azure Blob Storage após o upload?

A Braze não modifica os arquivos Avro no Microsoft Azure Blob Storage depois que o upload é concluído. O Azure pode bloquear a exclusão de um blob enquanto o upload ainda estiver em andamento.

Como obtenho dados históricos?

O Currents é um fluxo de dados em tempo real, o que significa que os eventos não podem ser reproduzidos novamente. No entanto, você pode armazenar os dados do Currents em um data warehouse, como o Amazon S3 ou o Microsoft Azure Blob Storage. Assim, você pode agir sobre eventos passados como achar melhor. Os dados ficam armazenados por 30 dias, mas, para dados mais antigos, você pode consultar o Snowflake.

Por que o Currents gera dados no formato Avro e não em JSON?

Diferente do JSON, que não tem esquema, o Avro oferece suporte nativo à evolução de esquemas. Além disso, como o Avro é altamente compressível, você consegue enviar arquivos Avro usando menos largura de banda e economizar espaço de armazenamento.

Como a Braze lida com a sobrecarga de arquivos?

Criamos um processo de ETL (extração, transformação e carga). Com ele, você extrai grandes volumes de dados de um banco de dados e os armazena em outro.

Onde devo armazenar esses dados para fazer consultas?

A Braze tem parceria com vários data warehouses onde você pode armazenar seus dados para fazer consultas. Recomendamos usar:

• Amazon S3
• Microsoft Azure Blob Storage
• Google Cloud Storage.

Qual é a confiabilidade dos dados do Currents?

O Currents garante a entrega “pelo menos uma vez” (at-least-once). Isso significa que, ocasionalmente, eventos duplicados podem ser gravados no seu bucket de armazenamento. Se o seu caso de uso exigir entrega exatamente uma vez, você pode desduplicar os eventos usando o campo de identificador exclusivo (id) enviado com cada evento. Para saber mais, consulte Semântica de entrega de eventos.

Com que frequência os dados são sincronizados com o Currents?

Os dados são transmitidos continuamente. A Braze envia um lote de eventos sempre que há um lote completo para enviar ou a cada 5 minutos, o que acontecer primeiro. Em conectores de alto volume, os dados chegam quase em tempo real. Já em conectores de baixo volume, os dados devem chegar em 5 a 30 minutos. Para saber mais, consulte Limite de gravação Avro.

Como descubro quais eventos estão disponíveis para o Currents?

Para ver a lista completa de eventos que o Currents registra, consulte os glossários de Eventos de comportamento do cliente e de Eventos de engajamento com mensagens. Você pode filtrar esses glossários por tipo de evento, como envios, entregas ou aberturas.

Por que as contagens de eventos do Currents não batem com as métricas do dashboard ou do relatório de engajamento?

O Currents e o dashboard da Braze calculam algumas métricas de formas diferentes. Por isso, não espere uma correspondência exata entre os eventos do Currents e as métricas do dashboard.

Cliques únicos: No e-mail, o dashboard rastreia cliques únicos em um período de sete dias e os mede por dispatch_id. Já o Currents registra cada evento de clique bruto. Para alinhar as contagens de cliques únicos baseadas no Currents com as métricas do dashboard, filtre os eventos em que is_unique é true.

Cancelamentos de inscrição: A métrica Unsub do dashboard reflete os cliques no link de cancelamento de inscrição padrão da Braze. Páginas de cancelamento de inscrição personalizadas não incrementam essa métrica, a menos que você atualize o usuário pela API. O evento users.messages.email.Unsubscribe do Currents é um evento de clique específico. Ele é disparado quando um usuário clica em um link de cancelamento de inscrição no corpo ou no rodapé do e-mail, ou pelo cabeçalho list-unsubscribe. Esse evento não representa todas as mudanças de estado de inscrição de e-mail.

Registros de data e hora e fusos horários: Todos os registros de data e hora do Currents estão em UTC. Já as métricas do dashboard seguem o fuso horário da sua empresa. Se você agregar os dados do Currents por dia do calendário sem converter para o fuso horário da empresa, as contagens podem cair em intervalos de datas diferentes dos exibidos no dashboard.

Eventos duplicados: O Currents oferece entrega do tipo “pelo menos uma vez” (at-least-once), então eventos duplicados podem ser gravados ocasionalmente. Antes de comparar os totais com as métricas do dashboard, faça a desduplicação usando o campo único id de cada evento.

Por que o external_user_id (esquema da Braze: external_id) no meu evento de abertura ou clique de e-mail do Currents é diferente do perfil de usuário no dashboard da Braze?

• No dashboard da Braze: Quando um usuário associado a um endereço de e-mail abre ou clica em um e-mail, todos os perfis de usuário que compartilham esse endereço são marcados como tendo aberto ou clicado nesse e-mail. Para saber mais, consulte O que acontece quando um e-mail é enviado e vários perfis têm o mesmo endereço de e-mail?.
• No Currents: Essa mesma abertura ou clique é armazenada em um único perfil. A Braze atribui o evento ao perfil originalmente segmentado para o envio, se esse perfil ainda compartilhar o endereço de e-mail. Caso contrário, a Braze atribui o evento a um perfil escolhido aleatoriamente entre os que compartilham o endereço de e-mail.

Por isso, o valor de external_user_id (chamado external_id na tabela de mapeamento do esquema da Braze) em um evento de abertura ou clique de e-mail do Currents pode não corresponder ao perfil de usuário esperado quando você compara o Currents com o dashboard da Braze.

Todos os eventos de envio são registrados no Currents?

A Braze registra no Currents os eventos de campanhas ativas e de Canvas ativos. Com exceção dos envios de teste, a Braze não suprime intencionalmente nenhum evento do fluxo do Currents.

Envios de teste não geram eventos de engajamento com mensagem no Currents. Isso vale para mensagens de teste enviadas de uma Campaign ou de uma etapa do Canvas. Também vale para mensagens enviadas com Send All Test Messages ao testar um Canvas. Para ver eventos de engajamento com mensagem no Currents, faça o envio a partir de uma campanha ativa ou de um Canvas ativo.

Os dados podem ser corrompidos no Currents?

Em circunstâncias normais, os dados do Currents não são corrompidos. Embora sempre exista a possibilidade de um problema raro, não há nenhuma condição conhecida em que os dados seriam corrompidos de forma sistemática.

Por que vejo dados de eventos personalizados com datas anteriores à configuração da minha integração do Currents?

A Braze não faz backfill de eventos para o Currents. No entanto, eventos personalizados podem ser registrados com um carimbo de data/hora passado. Isso acontece, por exemplo, quando um dispositivo estava offline no momento do evento e sincronizou os dados depois. Nesses casos, o carimbo de data/hora reflete quando o evento ocorreu originalmente, o que pode ser antes da configuração da integração do Currents.

Quais identificadores de usuário estão incluídos nos eventos do Currents?

Os eventos de engajamento com mensagens (envios, aberturas, cliques etc.) incluem o ID de usuário da Braze (user_id) e, quando estiver presente no perfil, o identificador externo (external_user_id nas cargas úteis dos eventos, identificado como external_id na tabela de mapeamento do esquema da Braze). Alguns eventos de engajamento com mensagens de e-mail também incluem email_address. Atributos personalizados não são incluídos.

Se você estiver enviando dados do Currents para um data warehouse ou CRM e precisar fazer a junção com dados de perfil, faça essa junção no seu sistema downstream usando user_id ou external_user_id.

O que é o campo app_group_id nos eventos do Currents?

O campo app_group_id contém o identificador de API do espaço de trabalho ao qual o evento pertence. Esse valor é um UUID. É o mesmo valor da coluna app_group_api_id nas tabelas SQL do Query Builder, das extensões de segmento SQL e do compartilhamento de dados do Snowflake. Assim, você pode usá-lo para unir os dados do Currents com essas tabelas.

O Currents usa identificadores de API em vez de IDs internos da Braze nos campos de ID. Por isso, os outros campos seguem o mesmo padrão. Por exemplo, canvas_id no Currents contém o identificador de API do Canvas.

O valor de app_group_id não é uma credencial, então você não pode usá-lo para autenticar solicitações da REST API. Para fazer solicitações da REST API para um espaço de trabalho, use uma chave da API REST.

Posso incluir atributos personalizados nos eventos de envio do Currents?

Não. O Currents não inclui atributos personalizados nos eventos de envio. O Currents registra eventos personalizados e eventos de engajamento com mensagens. Para ver a lista completa de campos disponíveis, consulte os glossários de eventos.

O Currents inclui tags ou pares de chave-valor de Campaign ou Canvas?

Não. O Currents não inclui tags de Campaign ou Canvas nem pares de chave-valor no nível da mensagem. Para obter dados de tags, use a API REST de exportação. Outra alternativa é usar um canal de webhook em uma Campaign para enviar dados de tags ou de pares de chave-valor para seu próprio endpoint. Nesse caso, use o Liquid para inserir os valores no modelo.

Como a Braze notifica os clientes sobre mudanças no Currents?

Em raras situações, podem ocorrer mudanças que quebram a compatibilidade. Nesses casos, a Braze envia um e-mail com antecedência para o contato de qualquer integração ativa e para todos os administradores com integrações ativas do Currents que usaram o dashboard nos últimos 30 dias. Para mudanças que não quebram a compatibilidade, como novos eventos ou novos campos em um evento existente, a Braze não envia notificação. Você pode consultar o changelog do Currents para ver as mudanças mais recentes.

Qual período uma notificação de recuperação do Currents abrange?

Quando uma integração do Currents se recupera de um erro, como credenciais inválidas ou erros 500 retornados pelo endpoint de destino, a Braze envia um e-mail para o contato da integração informando que ela “está se recuperando”. Depois que a integração coloca os dados em dia, a Braze informa que ela “se recuperou totalmente” e que todos os dados pendentes foram enviados. Essas notificações de recuperação não indicam o período coberto pelos dados pendentes.

Para identificar o período recuperado:

1. Encontre a primeira notificação de falha que a Braze enviou para a mesma integração. Ela informa aproximadamente quando a integração começou a falhar.
2. Anote quando você recebeu a notificação de que a integração “se recuperou totalmente”.

Os dados pendentes enviados pela Braze abrangem os eventos desde o momento em que a integração começou a falhar até a recuperação.

Se a integração ficou com falha por mais de cinco dias, alguns eventos podem ter sido descartados. Eventos descartados não podem ser recuperados. Para saber mais, consulte Requisitos.

De quanto armazenamento eu preciso para os dados do Currents?

Os requisitos de armazenamento dependem do seu volume de eventos e dos tipos de eventos que você exporta. A Braze fornece eventos de amostra no formato Avro que você pode usar para estimar o tamanho dos arquivos para o seu caso de uso.

Por que o nome da Campaign ou da etapa do Canvas aparece como NULL nos meus dados do Currents?

Quando você cria uma nova Campaign ou um novo Canvas, o nome pode levar algum tempo para se propagar por todos os sistemas da Braze. Os eventos enviados pelo Currents durante esse intervalo podem ter NULL nos campos de nome, como campaign_name ou canvas_step_name. Isso também é esperado se o nome tiver sido alterado pouco antes do registro dos eventos. Para evitar esse problema, aguarde um pouco depois de criar ou renomear uma Campaign ou etapa do Canvas antes de fazer o envio.

Por que os eventos de fim de sessão chegam atrasados ou não aparecem no Currents?

Os eventos de fim de sessão seguem o cronograma normal de upload do SDK. O SDK da Braze armazena os dados da sessão em cache no dispositivo e os envia periodicamente, de acordo com a qualidade da rede. Por exemplo, com uma conexão forte, o envio acontece mais ou menos a cada 10 segundos. O evento só aparece no Currents depois que o SDK faz o upload.

Se o usuário forçar o fechamento do app ou ficar offline antes do próximo envio, o evento de fim de sessão pode chegar atrasado ou nem chegar. No iOS, os eventos de fim de sessão muitas vezes só são enviados quando o app é aberto de novo, porque o SDK não consegue enviar dados enquanto o app está em segundo plano.

Se você precisa de limites de sessão mais pontuais no Currents, chame requestImmediateDataFlush() em momentos do ciclo de vida do app, como quando ele vai para o segundo plano ou volta para o primeiro plano. Para saber mais, consulte Upload e download de dados e Fim e início de sessão com registros de data e hora parecidos (iOS).

O que acontece se meu bucket de armazenamento estiver indisponível quando o Currents tentar gravar dados?

Se a Braze não conseguir gravar no seu bucket de armazenamento, ela coloca na fila os eventos que não conseguiu gravar e continua tentando. Isso vale para qualquer erro que o bucket retornar. Quando o bucket voltar a aceitar gravações, a Braze entrega primeiro os eventos da fila e depois os novos eventos.

Enquanto a Braze não conseguir gravar no seu bucket, você poderá receber uma notificação de erro de integração no e-mail de contato da integração. Dependendo do erro retornado pelo bucket, a notificação poderá informar que suas credenciais são inválidas, mesmo que elas não tenham mudado.

Se o problema persistir por mais de cinco dias, a Braze começa a descartar eventos. Os eventos descartados não podem ser recuperados. Para saber mais, consulte Requisitos.

Como garantir que seu bucket esteja disponível

Seu bucket está disponível quando existe com o nome salvo na sua integração do Currents e aceita gravações da Braze. Para verificar isso, faça o seguinte:

1. Na Braze, acesse Integrações de parceiros > Currents e abra sua integração. Anote o nome do bucket (ou o nome do contêiner, no caso do Azure Blob Storage) e o caminho da pasta ou prefixo.
2. No console do seu provedor de nuvem, confirme que existe um bucket com exatamente esse nome:
   • Para o Amazon S3, verifique a conta da AWS proprietária do bucket.
   • Para o Google Cloud Storage, verifique o projeto indicado como project_id no seu arquivo de chave JSON. Se você usa federação de identidade de carga de trabalho, verifique o projeto proprietário do bucket.
   • Para o Azure Blob Storage, verifique a conta de armazenamento no endpoint da conta ou na string de conexão.
3. Se o bucket não existir, crie um novo bucket e atualize sua integração com o nome dele.
4. Se você restringe o acesso de rede ao seu bucket, por exemplo com regras de firewall ou endpoints privados, confirme que suas regras permitem que a Braze grave dados. Para ver os endereços IP de onde a Braze envia os dados do Currents, consulte Lista de permissões de IP. Para o Azure Blob Storage, consulte A Braze pode fornecer endereços IP para incluir na lista de permissões do Azure Blob Storage?.
5. Depois que seu bucket voltar a aceitar gravações, verifique se há novos arquivos no caminho da pasta ou prefixo. A Braze entrega primeiro os eventos da fila e depois os novos eventos.

Como garantir que seu bucket esteja configurado corretamente

A Braze precisa do nome exato do bucket, de credenciais válidas e de permissão para gravar no seu bucket. Para verificar sua configuração, faça o seguinte:

1. Na sua integração do Currents, confirme que o nome do bucket corresponde exatamente ao seu bucket. Informe apenas o nome do bucket no campo do bucket, sem barras nem caminho. Informe qualquer caminho no campo de caminho da pasta ou prefixo.
2. Confirme que as credenciais da sua integração têm as permissões necessárias:
   • Amazon S3: Sua política de IAM permite s3:ListBucket e s3:GetBucketLocation no bucket, além de s3:PutObject e s3:GetObject nos objetos do bucket. Seu bucket também não pode usar criptografia SSE-KMS nem Object Lock. Para saber mais, consulte Integração com o Amazon S3 e Solução de problemas.
   • Google Cloud Storage: A função da sua conta de serviço inclui storage.objects.create, storage.objects.delete, storage.objects.list, storage.objects.get e storage.buckets.get. Se o seu bucket usa namespace hierárquico, a função também precisa de storage.folders.create. Para saber mais, consulte Etapa 1: Criar função. Se você usa federação de identidade de carga de trabalho, confirme que a identidade usada pela Braze (o principal da Braze ou a conta de serviço que ela representa) tem essa função no seu bucket. Confirme também que o URL do emissor e o público permitido do provedor do seu pool de identidades de carga de trabalho correspondem aos valores exibidos pela Braze. Para saber mais, consulte Etapa 3: Criar um pool de identidades de carga de trabalho e um provedor e Etapa 4: Conceder acesso ao seu bucket.
   • Azure Blob Storage: Se você usa autenticação por entidade de serviço com certificado ou por federação de identidade de carga de trabalho, o registro do seu app tem a função Storage Blob Data Contributor no seu contêiner. As atribuições de função podem levar até 30 minutos para entrar em vigor. Para federação de identidade de carga de trabalho, confirme também que o emissor, o identificador do assunto e o público da credencial federada correspondem aos valores exibidos pela Braze. Para saber mais, consulte Etapa 4: Conceder acesso à sua conta de armazenamento para entidade de serviço com certificado, ou Etapa 2: Adicionar uma credencial federada e Etapa 3: Conceder acesso à sua conta de armazenamento para federação de identidade de carga de trabalho.
3. Confirme que suas credenciais estão atualizadas. Se você fez a rotação de uma chave, função ou certificado, atualize sua integração. Para saber mais, consulte Atualização das credenciais do Amazon S3 para o Currents, Atualização das credenciais do Azure para o Currents, Atualização das credenciais do GCS para o Currents ou Atualização do Currents.

Posso realocar meu bucket de armazenamento sem perder dados do Currents?

Sim. Se você realocar um bucket de armazenamento conectado a uma integração ativa do Currents (por exemplo, com a realocação de buckets do Google Cloud Storage), não é preciso editar sua integração do Currents, desde que o nome do bucket, as credenciais e o prefixo continuem os mesmos. Durante a realocação, a Braze coloca na fila os eventos que não consegue gravar e os entrega quando o bucket voltar a aceitar gravações.

Conclua a realocação em até cinco dias para evitar a perda de eventos.

Por que vejo mensagens de limite de direitos de uso ao criar ou editar uma integração do Currents?

O Currents usa grupos separados de direitos de uso para diferentes recursos de conectores:

• Eventos de engajamento: Necessário para criar ou fazer upgrade de um conector padrão do Currents.
• Eventos de comportamento do cliente: Necessário para ativar Track Customer Behavior and User Events.
• Perfis e atributos de usuário: Necessário para ativar Track user profiles and attributes.

Se algum grupo estiver esgotado, a Braze mostra um alerta de direitos de uso e bloqueia essa ação. Entre em contato com o gerente da sua conta Braze para solicitar mais direitos de uso ou para receber ajuda no ajuste da sua configuração.

Com que frequência a versão do Currents no caminho de armazenamento muda?

O segmento version=<currents_version> no caminho de armazenamento avança a cada versão do Currents, em uma cadência mensal (por exemplo, de version=6 para version=7). Recomendamos ler os arquivos de forma recursiva a partir do caminho raiz, em vez de fixar no código um segmento de versão específico. Assim, seu pipeline passa a coletar os dados automaticamente depois de uma mudança de versão. Para saber mais sobre o formato do caminho, consulte Semântica de entrega de eventos. Para ver o histórico de mudanças por versão, consulte o changelog do Currents.

Por que campaign_id ou canvas_id não aparecem em um evento de engajamento com mensagem?

Dependendo do tipo de evento e do contexto, um evento de engajamento com mensagem pode não estar vinculado a uma Campaign ou etapa do Canvas específica. Nesses casos, campaign_id, canvas_id e os campos de nome relacionados podem ser omitidos da carga útil do evento. Se esses campos não aparecerem em um evento, verifique se esse tipo de evento e esse contexto normalmente incluem identificadores de Campaign ou Canvas.

Por que os timestamps do Currents têm precisão de apenas um segundo?

O campo time nos eventos do Currents é armazenado como um inteiro de 32 bits e, por isso, tem precisão limitada a segundos. Alguns eventos também incluem um campo de timestamp separado de 64 bits, com precisão de milissegundos. Consulte o glossário de eventos para ver os campos disponíveis em cada tipo de evento.

Por que o evento users.canvas.Conversion do Currents tem um horário diferente do Canvas?

O horário do evento users.canvas.Conversion no Currents reflete a janela total de conversão, ou seja, a duração do Canvas mais o prazo de conversão, contada a partir da entrada no Canvas.

O que acontece quando os relatórios de engajamento são enviados para o S3?

Se as credenciais do S3 estiverem configuradas para exportação de dados, mas não para o Currents, a Braze faz upload dos relatórios de engajamento para o bucket S3 especificado. O usuário indicado no campo Enviar relatório para recebe um e-mail com um link para o relatório no S3.

Dados de usuários anônimos podem ser enviados para a Amplitude pelo Braze Currents?

Sim. Os dados de usuários anônimos, identificados por device_id, podem ser enviados para a Amplitude pelo Currents. Para isso, a equipe da sua conta Braze precisa ativar o recurso.

Como os usuários do grupo de controle são registrados no Currents para Content Cards, mensagens no app e Banners?

Quando um usuário é atribuído a um grupo de controle para uma Campaign de Content Card ou mensagem no app, o Currents emite um evento users.campaigns.EnrollInControl em vez de um evento de impressão.

Campaigns de Banner funcionam de forma diferente. Os usuários de controle não são registrados em users.campaigns.EnrollInControl. Em vez disso, a exposição do controle é registrada como um evento users.messages.banner.Impression após o SDK registrar uma impressão — inclusive quando sua integração chama insertBanner para um Banner de controle e oculta o contêiner. Para identificar os usuários de controle no Currents ou no compartilhamento de dados, filtre pelo message_variation_id ou message_variation_name (Control Group) da variação de controle.

Para os esquemas de tabela, consulte Eventos de impressão de Banner e USERS_MESSAGES_BANNER_IMPRESSION_SHARED.

O que acontece quando você direciona um usuário inexistente pela API?

Quando você direciona um usuário que não existe, a API retorna uma resposta 200, mas o envio é cancelado com o resultado “Unknown external ID”. Nenhum evento do Currents é gerado para esse envio. O parâmetro send_to_existing_only tem true como padrão. Por isso, envios para usuários desconhecidos são ignorados sem aviso, a menos que você defina esse parâmetro explicitamente como false.