Perguntas frequentes

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

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

Para extrair métricas de Campaign ou Canvas de 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 Campaign ou análise de dados de Canvas com os parâmetros ending_at e length para obter dados de séries temporais. Você também pode usar /campaigns/data_series e /canvas/data_series.
• Transmita eventos para 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 faço para 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 permanece somente leitura, e não é possível 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 arquivos Avro no Microsoft Azure Blob Storage depois que o upload é concluído. O Azure pode bloquear a exclusão de um blob enquanto um upload ainda estiver em andamento.

Como faço para obter 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 Amazon S3 ou Microsoft Azure Blob Storage. Assim, você pode agir com base em eventos passados como achar melhor. Os dados ficam retidos por 30 dias. Para dados mais antigos, você pode consultar o Snowflake.

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

Ao contrário do JSON, que não tem esquema, o Avro oferece suporte nativo à evolução de esquema. Você também consegue enviar arquivos Avro usando menos largura de banda e economizar espaço de armazenamento, já que o Avro é altamente compactável.

Como a Braze lida com a sobrecarga de arquivos?

Criamos um processo de ETL (extração, transformação e carregamento), que permite extrair grandes volumes de dados de um banco de dados para colocá-los e armazená-los em outro.

Onde devo armazenar esses dados para consulta?

A Braze tem parceria com vários data warehouses onde você pode armazenar seus dados para consulta. 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 deduplicar 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 ocorrer primeiro. Para conectores de alto volume, os dados chegam quase em tempo real. Para conectores de baixo volume, os dados devem chegar em 5 a 30 minutos. Para saber mais, consulte Limite de gravação Avro.

Como faço para descobrir quais eventos estão disponíveis no Currents?

Para ver a lista completa de eventos registrados pelo Currents, 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 correspondem às métricas do dashboard ou do relatório de engajamento?

O Currents e o dashboard da Braze calculam certas métricas de forma diferente. Por isso, não é esperado que os eventos do Currents correspondam exatamente às métricas do dashboard.

Cliques únicos: No caso do e-mail, o dashboard rastreia cliques únicos durante um período de sete dias e os mede pelo dispatch_id. 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 seja 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 personalizadas de cancelamento de inscrição 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 especializado. 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.

Carimbos de data/hora e fusos horários: Todos os carimbos de data/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 sua 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). Isso significa que, ocasionalmente, eventos duplicados podem ser gravados. Antes de comparar os totais com as métricas do dashboard, faça a deduplicação pelo campo exclusivo 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 fica armazenada em um único perfil. A Braze atribui o evento ao perfil que foi 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 selecionado 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 Campaigns e Canvas ativos. Exceto pelos 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 inclui mensagens de teste enviadas a partir de uma Campaign ou de uma etapa do Canvas. Também inclui 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 Campaign 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á condições conhecidas 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 com o Currents?

A Braze não faz backfill de eventos no Currents. No entanto, eventos personalizados podem ser registrados com um carimbo de data/hora no passado. Isso acontece, por exemplo, quando um dispositivo estava offline no momento do evento e sincronizou depois. Nesses casos, o carimbo de data/hora mostra quando o evento ocorreu originalmente, o que pode ser antes da configuração da integração com o 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 presente no perfil, o identificador externo (external_user_id nas cargas úteis dos eventos, rotulado 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 encaminhando dados do Currents para um data warehouse ou CRM e precisar fazer junções 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. Ele é o mesmo valor da coluna app_group_api_id nas tabelas SQL do Query Builder, das extensões de segmento SQL e do Snowflake Data Sharing. Assim, você pode usá-lo para combinar os dados do Currents com essas tabelas.

O Currents usa identificadores de API em vez de IDs internos da Braze nos campos de ID, então 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 REST API de exportação. Outra alternativa é usar um canal de webhook em uma Campaign para enviar dados de tags ou pares de chave-valor para o seu próprio endpoint, usando Liquid para criar o modelo dos valores.

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

Nos raros casos em que ocorrem mudanças que quebram a compatibilidade, 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 do destino, a Braze envia um e-mail para o contato da integração. Esse e-mail informa que a integração “is now recovering” (está se recuperando). Quando a integração se atualiza, a Braze informa que ela “has fully recovered” (se recuperou totalmente) e que todos os dados pendentes foram enviados. Essas notificações de recuperação não informam qual período os dados pendentes abrangem.

Para descobrir 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 “has fully recovered”.

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

Se a integração ficou falhando 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 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 oferece eventos de amostra no formato Avro que você pode usar para estimar o tamanho dos arquivos no 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. Eventos enviados pelo Currents durante esse período podem ter NULL nos campos de nome (como campaign_name ou canvas_step_name). Isso também é esperado se o nome tiver sido modificado pouco antes de os eventos serem registrados. Para evitar isso, aguarde um pouco depois de criar ou renomear uma Campaign ou etapa do Canvas antes de fazer o envio.

Por que eventos de fim de sessão estão atrasados ou ausentes 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 localmente e os envia periodicamente, de acordo com a qualidade da rede. Por exemplo, com uma conexão forte, o envio acontece a cada 10 segundos, aproximadamente. O evento só aparece no Currents depois que o SDK faz o upload.

Se um usuário forçar o fechamento do app ou ficar off-line 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 costumam ser enviados só quando o app é reaberto, porque o SDK não consegue enviar dados enquanto o app está em segundo plano.

Se você precisar de limites de sessão mais precisos no Currents, chame requestImmediateDataFlush() em pontos do ciclo de vida, por exemplo, quando o app passar para segundo plano ou voltar para primeiro plano. Para saber mais, consulte Upload e download de dados e Fim de sessão e início de sessão têm carimbos de data/hora semelhantes (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 em fila os eventos que não foram gravados e continua tentando. Isso vale para qualquer erro que o seu bucket retornar. Quando o bucket voltar a aceitar gravações, a Braze entrega os eventos da fila e, em seguida, 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 sua integração. Dependendo do erro retornado pelo bucket, a notificação pode 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 esse nome exato:
   • 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.
   • Para o Azure Blob Storage, verifique a conta de armazenamento no endpoint da sua 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 a lista de permissões do Azure Blob Storage?.
5. Depois que seu bucket aceitar gravações, verifique se há novos arquivos no caminho da pasta ou prefixo. A Braze entrega primeiro os eventos da fila e, em seguida, 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 de 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 do IAM permite s3:ListBucket e s3:GetBucketLocation no bucket, e 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.
   • 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 a 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 Atualizar as credenciais do Amazon S3 para o Currents, Atualizar as credenciais do Azure para o Currents ou Atualizar o 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 bucket do Google Cloud Storage) e o nome do bucket, as credenciais e o prefixo continuarem os mesmos, não é necessário editar sua integração do Currents. Durante a realocação, a Braze coloca em 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 pools de direitos de uso separados 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ários: Necessário para ativar Track user profiles and attributes.

Se algum pool 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 receber ajuda para ajustar sua configuração.

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

O trecho version=<currents_version> no caminho de armazenamento avança a cada nova versão do Currents, com frequê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 trecho de versão específico. Assim, seu pipeline captura automaticamente os dados 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 determinado evento, confira se esse tipo de evento e esse contexto normalmente incluem identificadores de Campaign ou Canvas.

Por que os timestamps do Currents são limitados à precisão de segundos?

O campo time nos eventos do Currents é armazenado como um número inteiro de 32 bits. Por isso, ele é limitado à precisão de 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 de conversão total, ou seja, a duração do Canvas mais o prazo de conversão, medida 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.

É possível enviar dados de usuários anônimos para a Amplitude pelo Braze Currents?

Os dados de usuários anônimos, identificados pelo device_id, podem ser enviados para a Amplitude pelo Currents. Para isso, a equipe de conta da 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 uma mensagem a um usuário inexistente pela API?

Quando você direciona uma mensagem a 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 como padrão true. Portanto, os envios para usuários desconhecidos são ignorados sem aviso, a menos que você defina esse parâmetro explicitamente como false.