Ir para o conteúdo

Importação via CSV

Saiba como registrar e atualizar atributos de usuários, eventos personalizados e eventos recomendados usando a importação via CSV.

Sobre a importação via CSV

Você pode usar a importação via CSV para registrar e atualizar os seguintes atributos de usuário, eventos personalizados e eventos recomendados. A Braze aceita esses dados como arquivos CSV padrão, dentro dos tamanhos máximos indicados na tabela a seguir.

Tipo Definição Exemplo Tamanho máximo do arquivo
Atributos padrão Atributos de usuário reservados reconhecidos pela Braze. first_name, email 500 MB
Atributos personalizados Atributos de usuário exclusivos da sua empresa. last_destination_searched 500 MB
Eventos personalizados Eventos exclusivos da sua empresa que representam ações do usuário. trip_booked 50 MB
Eventos recomendados Eventos personalizados padronizados com esquemas definidos e processamento especializado. order_placed 50 MB

Usando a importação de CSV

Etapa 1: Acesse a importação de CSV

Para acessar a importação de CSV, acesse Público > Importar usuários. Nessa página, há uma tabela com detalhes das importações mais recentes: data de upload, nome de quem fez o upload, nome do arquivo, disponibilidade para direcionamento, número de registros importados e status da importação.

Para começar, selecione Atributos, Eventos personalizados ou Eventos recomendados no menu suspenso Importar usuários. Se você usa o mapeador de dados ou já tem um arquivo, pode fazer o upload e pular para a Etapa 5: Mapeie seus campos. Você também pode baixar o modelo correspondente para criar o arquivo CSV de upload, mas isso é opcional ao usar o mapeador de dados.

Etapa 2: Escolha um identificador

O arquivo CSV importado precisa de um identificador dedicado. Escolha um dos seguintes tipos de identificador para sua importação:

Ao importar seus dados de cliente, você pode usar um external_id como identificador exclusivo de cada cliente. Quando você informa um external_id na importação, a Braze atualiza qualquer usuário existente com o mesmo external_id ou, se nenhum for encontrado, cria um novo usuário identificado com esse external_id.

Para direcionar usuários que não têm um external_id, você pode importar uma lista de usuários com aliases de usuário. Um alias funciona como um identificador exclusivo alternativo do usuário. Ele é útil quando você quer fazer marketing para usuários anônimos que ainda não se cadastraram ou não criaram uma conta no seu app.

Se você estiver fazendo upload ou atualizando perfis de usuário que têm apenas alias, seu CSV precisa ter as duas colunas a seguir:

  • user_alias_name: Um identificador exclusivo do usuário; uma alternativa ao external_id
  • user_alias_label: Um rótulo comum para agrupar aliases de usuário
user_alias_name user_alias_label last_name email sample_attribute
182736485 my_alt_identifier Smith [email protected] TRUE
182736486 my_alt_identifier Nguyen [email protected] FALSE

Quando você informa user_alias_name e user_alias_label na importação, a Braze atualiza qualquer usuário existente com os mesmos user_alias_name e user_alias_label. Se nenhum usuário for encontrado, a Braze cria um novo usuário identificado com esse user_alias_name.

Download: Modelo de importação de atributos via CSV: Alias de usuário

Para atualizar perfis de usuário existentes na Braze usando um ID interno da Braze em vez de um external_id ou dos valores user_alias_name e user_alias_label, especifique braze_id como cabeçalho de coluna.

Isso é útil se você exportou dados de usuários da Braze pela opção de exportação de CSV na segmentação e quer adicionar um novo atributo personalizado a esses usuários existentes.

Você pode omitir o ID externo ou o alias de usuário e usar um endereço de e-mail ou número de telefone para importar usuários. Antes de importar um arquivo CSV com endereços de e-mail ou números de telefone, verifique o seguinte:

  • Confirme que não há IDs externos nem aliases de usuário para esses perfis no seu arquivo CSV. Se houver, a Braze vai priorizar o ID externo ou o alias de usuário, antes do endereço de e-mail, para identificar os perfis.
  • Confirme que o arquivo CSV está formatado corretamente.

Se já existir um perfil com esse endereço de e-mail ou número de telefone, esse perfil é atualizado e a Braze não cria um novo. Se houver vários perfis com o mesmo endereço de e-mail, a Braze usa a mesma lógica do endpoint /users/track, em que o perfil atualizado mais recentemente é o que recebe a atualização.

Se não existir um perfil com esse endereço de e-mail ou número de telefone, a Braze cria um novo perfil com esse identificador. Você pode usar o endpoint /users/identify para identificar esse perfil depois. Para excluir um perfil de usuário, você também pode usar o endpoint /users/delete.

Etapa 3: Crie seu arquivo CSV

Você pode fazer upload de qualquer um dos seguintes tipos de dados em um único arquivo CSV. Para fazer upload de mais de um tipo de dado, use vários arquivos CSV.

  • Atributos do usuário: Inclui atributos de usuário padrão e personalizados. Os atributos de usuário padrão são chaves reservadas na Braze (como first_name ou email), e os atributos personalizados são atributos de usuário exclusivos da sua empresa (como last_destination_searched).
  • Eventos personalizados: São exclusivos da sua empresa e refletem ações realizadas pelo usuário, como trip_booked em um app de reservas de viagem.
  • Eventos recomendados: São eventos personalizados com esquemas definidos e processamento especializado, como cálculos automáticos de campos ou gerenciamento de carrinho, que eventos personalizados genéricos não recebem. Incluem order_placed, product_viewed e cart_updated.

Quando estiver pronto para criar seu arquivo CSV, consulte as informações a seguir:

Identificadores obrigatórios

Embora o external_id não seja obrigatório, seu arquivo CSV precisa incluir um identificador de usuário que possa ser mapeado para um dos seguintes identificadores. Para ver detalhes de cada um, consulte Escolha um identificador.

  • external_id
  • braze_id
  • user_alias_name e user_alias_label
  • email
  • phone

Atributos personalizados

Os seguintes tipos de dados podem ser usados como atributos personalizados na importação de CSV. Cabeçalhos de coluna que não correspondem exatamente a um atributo padrão são importados como atributos personalizados na Braze, a menos que sejam alterados na etapa de mapeamento.

Tipo de dado Descrição
Datetime Deve estar no formato ISO-8601.
Booleano Aceita true ou false.
Número Deve ser um inteiro ou float, sem espaços nem vírgulas. Floats devem usar ponto (.) como separador decimal.
String Pode conter vírgulas se o valor estiver entre aspas duplas ("").
Em branco Valores em branco não sobrescrevem valores existentes no perfil do usuário, e você não precisa incluir todos os atributos de usuário existentes no arquivo CSV.

Atributos padrão

Os seguintes atributos padrão estão disponíveis para a importação de usuários.

Campo do perfil de usuário Tipo de dado Descrição Obrigatório?
external_id String Um identificador exclusivo do seu cliente. Condicionalmente. Consulte Identificadores obrigatórios.
user_alias_name String Um identificador exclusivo para usuários anônimos, alternativo ao external_id. Deve ser usado com user_alias_label. Condicionalmente. Consulte Identificadores obrigatórios.
user_alias_label String Um rótulo comum para agrupar aliases de usuário. Deve ser usado com user_alias_name. Condicionalmente. Consulte Identificadores obrigatórios.
first_name String O nome dos seus usuários, conforme informado por eles (por exemplo, Jane). Não
last_name String O sobrenome dos seus usuários, conforme informado por eles (por exemplo, Doe). Não
email String O e-mail dos seus usuários, conforme informado por eles (por exemplo, [email protected]). Não
country String Os códigos de país devem ser enviados à Braze no padrão ISO-3166-1 alfa-2 (por exemplo, GB). Não
dob String Deve ser enviado no formato “AAAA-MM-DD” (por exemplo, 1980-12-21). Isso importa a data de nascimento do usuário e permite direcionar usuários que fazem aniversário “hoje”. Não
gender String “M”, “F”, “O” (outro), “N” (não se aplica), “P” (prefere não informar) ou nil (desconhecido). Não
home_city String A cidade de residência dos seus usuários, conforme informado por eles (por exemplo, London). Não
language String O idioma deve ser enviado à Braze no padrão ISO-639-1 (por exemplo, en). Consulte nossa lista de idiomas aceitos. Não
phone String Um número de telefone informado pelos seus usuários, no formato E.164 (por exemplo, +442071838750). Consulte Números de telefone de usuários para orientações de formatação. Não
email_open_tracking_disabled Booleano Aceita true ou false. Defina como true para impedir que o pixel de rastreamento de abertura seja adicionado a todos os futuros e-mails enviados a esse usuário. Não
email_click_tracking_disabled Booleano Aceita true ou false. Defina como true para desativar o rastreamento de cliques em todos os links de futuros e-mails enviados a esse usuário. Não
email_subscribe String Os valores disponíveis são opted_in (registrado explicitamente para receber mensagens de e-mail), unsubscribed (optou explicitamente por não receber mensagens de e-mail) e subscribed (não aceitou nem recusou explicitamente). Não
push_subscribe String Os valores disponíveis são opted_in (registrado explicitamente para receber mensagens push), unsubscribed (optou explicitamente por não receber mensagens push) e subscribed (não aceitou nem recusou explicitamente). Não
time_zone String O fuso horário deve ser enviado à Braze no mesmo formato do banco de dados de fusos horários da IANA (por exemplo, America/New_York ou Eastern Time (US & Canada)). Não
date_of_first_session date_of_last_session String Pode ser enviado em um dos seguintes formatos ISO 8601: “YYYY-MM-DD” “YYYY-MM-DDTHH:MM:SS+00:00” “YYYY-MM-DDTHH:MM:SSZ” “YYYY-MM-DDTHH:MM:SS” (por exemplo, 2019-11-20T18:38:57) Não
subscription_group_id String O id do seu grupo de inscrições. Esse identificador fica na página do grupo de inscrições no dashboard. Não
subscription_state String O estado de inscrição no grupo de inscrições especificado por subscription_group_id. Os valores permitidos são unsubscribed (fora do grupo de inscrições) ou subscribed (no grupo de inscrições). Não, mas é altamente recomendado se subscription_group_id for usado

Atualização do status do grupo de inscrições (opcional)

Você também pode adicionar usuários a grupos de inscrições de e-mail ou SMS pela importação de usuários. Isso é especialmente útil para SMS, porque o usuário precisa estar inscrito em um grupo de inscrições de SMS para receber mensagens pelo canal SMS. Para saber mais, consulte Grupos de inscrições de SMS.

Se você estiver atualizando status de grupos de inscrições, seu CSV precisa ter as duas colunas a seguir:

  • subscription_group_id: O id do grupo de inscrições.
  • subscription_state: Os valores disponíveis são unsubscribed (fora do grupo de inscrições) ou subscribed (no grupo de inscrições).
external_id first_name subscription_group_id subscription_state
A8i3mkd99 Colby 6ff593d7-cf69-448b-aca9-abf7d7b8c273 subscribed
k2LNhj8Ks Tom aea02307-a91e-4bc0-abad-1c0bee817dfa subscribed

Identificadores obrigatórios

Embora o external_id não seja obrigatório, seu arquivo CSV precisa incluir um identificador de usuário que corresponda a um dos seguintes identificadores. Para ver detalhes de cada um, consulte Escolha um identificador.

  • external_id
  • braze_id
  • user_alias_name e user_alias_label
  • email
  • phone

Campos de eventos personalizados

Além dos campos padrão listados na tabela a seguir, seu CSV também pode ter cabeçalhos de coluna adicionais para propriedades de eventos. Essas propriedades devem ter o cabeçalho de coluna <property name>. A Braze detecta as propriedades relevantes de cada evento com base na existência de um valor na célula correspondente do CSV.

Por exemplo, o evento personalizado trip_booked pode ter a propriedade destination. Você pode importá-la usando o cabeçalho de coluna destination e incluindo um valor na célula correspondente do CSV. Assim, vários eventos podem ter uma propriedade chamada destination sem precisar de colunas separadas.

Campo do perfil de usuário Tipo de dado Informações Obrigatório?
external_id String Um identificador exclusivo do seu usuário. Condicionalmente. Consulte Identificadores obrigatórios.
braze_id String Um identificador do seu usuário atribuído pela Braze. Condicionalmente. Consulte Identificadores obrigatórios.
user_alias_name String Um identificador exclusivo para usuários anônimos, alternativo ao external_id. Deve ser usado com user_alias_label. Condicionalmente. Consulte Identificadores obrigatórios.
user_alias_label String Um rótulo comum para agrupar aliases de usuário. Deve ser usado com user_alias_name. Condicionalmente. Consulte Identificadores obrigatórios.
email String O e-mail dos seus usuários, conforme informado por eles (por exemplo, [email protected]). Não, e só pode ser usado na ausência de outros identificadores. Veja a nota a seguir.
phone String Um número de telefone informado pelos seus usuários, no formato E.164 (por exemplo, +442071838750). Consulte Números de telefone de usuários para orientações de formatação. Não, e só pode ser usado na ausência de outros identificadores. Veja a nota a seguir.
name String Um evento personalizado dos seus usuários. Sim
time String O horário do evento. Pode ser enviado em um dos seguintes formatos ISO-8601: “YYYY-MM-DD” “YYYY-MM-DDTHH:MM:SS+00:00” “YYYY-MM-DDTHH:MM:SSZ” “YYYY-MM-DDTHH:MM:SS” (por exemplo, 2019-11-20T18:38:57) Sim
<property name> Vários Uma propriedade de evento que pode ser usada em vários tipos de evento. Um exemplo é destination. Essa propriedade é associada a um evento quando há um valor não nulo na célula correspondente do CSV. Não
<event name>.properties.<property name> Vários Uma propriedade de evento associada a um evento personalizado. Um exemplo é trip_booked.properties.destination Não
Entendendo a formatação de eventos personalizados

Formate corretamente seu CSV de eventos personalizados com um cabeçalho <property_name> e um valor não nulo na célula correta, ou use o formato legado com notação de ponto. Assim, a Braze mapeia cada propriedade para o evento correto. Se o formato estiver incorreto, as propriedades podem ser descartadas ou a importação pode falhar, principalmente quando vários tipos de evento estão no mesmo arquivo.

Um evento por linha

Cada linha do CSV representa um único evento personalizado de um único usuário. Se um usuário tiver vários eventos, inclua uma linha separada para cada evento, mesmo que elas compartilhem o mesmo identificador de usuário.

Exemplo de estrutura de CSV

A tabela a seguir mostra a formatação correta para importar eventos personalizados com propriedades. Neste exemplo, há dois usuários que realizaram eventos diferentes: um alugou um filme e o outro comprou um filme.

external_id name time movie_name sitcom_name genre
123 rented_movie 2024-06-10T12:00:00Z Ghostbusters   Action
456 bought_sitcom 2024-06-12T12:00:00Z   Scrubs Comedy

Neste exemplo:

  • O usuário 123 disparou o evento rented_movie com as propriedades movie_name (Ghostbusters) e genre (Action)
  • O usuário 456 disparou o evento bought_sitcom com as propriedades sitcom_name (Scrubs) e genre (Comedy)
  • Cada evento preenche apenas as colunas das próprias propriedades, deixando em branco as colunas de propriedades de outros eventos

Embora o external_id não seja obrigatório, seu arquivo CSV precisa incluir um dos seguintes identificadores como cabeçalho. Para ver detalhes de cada um, consulte Escolha um identificador.

  • external_id
  • braze_id
  • user_alias_name e user_alias_label
  • email
  • phone

Além dos campos a seguir, seu CSV também precisa ter cabeçalhos de coluna adicionais para as propriedades obrigatórias do evento recomendado que você está importando. Essas propriedades devem ter o cabeçalho de coluna <property_name> e podem ser mapeadas para a propriedade correspondente do evento recomendado.

Por exemplo, o evento recomendado order_placed precisa ter, entre outras, as propriedades order_id e total_value. Elas podem ser importadas usando os cabeçalhos de coluna order_id e total_value, ou usando cabeçalhos baseados no seu modelo de dados e mapeando-os para a propriedade correta. Para ver a lista completa de propriedades de eventos recomendados, consulte Esquemas de eventos recomendados.

Campo do perfil de usuário Tipo de dado Informações Obrigatório?
external_id String Um identificador exclusivo do seu usuário. Condicionalmente. Consulte Identificadores obrigatórios.
braze_id String Um identificador do seu usuário atribuído pela Braze. Condicionalmente. Consulte Identificadores obrigatórios.
user_alias_name String Um identificador exclusivo para usuários anônimos, alternativo ao external_id. Deve ser usado com user_alias_label. Condicionalmente. Consulte Identificadores obrigatórios.
user_alias_label String Um rótulo comum para agrupar aliases de usuário. Deve ser usado com user_alias_name. Condicionalmente. Consulte Identificadores obrigatórios.
email String O e-mail dos seus usuários, conforme informado por eles (por exemplo, [email protected]). Não, e só pode ser usado na ausência de outros identificadores. Veja a nota a seguir.
phone String Um número de telefone informado pelos seus usuários, no formato E.164 (por exemplo, +442071838750). Consulte Números de telefone de usuários para orientações de formatação. Não, e só pode ser usado na ausência de outros identificadores. Veja a nota a seguir.
name String Um evento personalizado dos seus usuários. Sim
time String O horário do evento. Pode ser enviado em um dos seguintes formatos ISO-8601: “YYYY-MM-DD” “YYYY-MM-DDTHH:MM:SS+00:00” “YYYY-MM-DDTHH:MM:SSZ” “YYYY-MM-DDTHH:MM:SS” (por exemplo, 2019-11-20T18:38:57) Sim
<property_name> Vários Uma propriedade de evento associada a um evento recomendado. Um exemplo é order_id. Condicionalmente. Consulte Esquemas de eventos recomendados.

Ao importar eventos recomendados via CSV, formate seu arquivo de acordo com os requisitos a seguir para que a importação de dados seja bem-sucedida. Para reduzir erros de mapeamento, inclua apenas um tipo de evento por arquivo.

É importante formatar seu CSV de eventos recomendados com os cabeçalhos corretos para que cada propriedade identificada seja mapeada para a propriedade de evento correta. Se o formato estiver incorreto, os eventos podem ser descartados ou a importação pode falhar, principalmente quando vários tipos de evento estão no mesmo arquivo.

Os eventos recomendados têm um esquema definido. Por exemplo, order_placed tem uma propriedade obrigatória products, que é um array de objetos, e cada objeto aninhado tem as próprias propriedades aninhadas obrigatórias.

O CSV de eventos recomendados aceita o agrupamento de várias linhas com o mesmo identificador, nome de evento e horário, desde que as linhas não estejam separadas no arquivo. Assim, você pode usar linhas sequenciais para preencher valores de propriedades aninhadas. Ao formatar o arquivo, preencha as linhas extras apenas com o identificador, o nome do evento, o horário e as propriedades aninhadas relevantes. Não é necessário repetir os valores das propriedades de nível superior em todas as linhas.

Metadados e propriedades opcionais

Embora os eventos recomendados tenham um esquema definido (consulte Esquemas de eventos recomendados), você pode mapear e importar propriedades opcionais, como image_url para a propriedade de array products. Também é possível enviar propriedades adicionais para a propriedade metadata de nível superior, para a propriedade aninhada metadata no nível de products ou para o array de propriedades discounts. Depois de mapear todas as propriedades obrigatórias, clique em Carregar propriedades opcionais para carregar e mapear propriedades adicionais.

Exemplo de estrutura de CSV

O exemplo a seguir mostra a formatação correta para importar eventos recomendados com propriedades obrigatórias e propriedades aninhadas. Neste exemplo, há três usuários, cada um fazendo um pedido com dois produtos diferentes.

Exemplo de formatação de eventos recomendados.

Neste exemplo:

  • Os pedidos são identificados e agrupados pelo mesmo identificador, nome de evento e horário, com todas as linhas relevantes em sequência.
  • Os usuários user_101, user_102 e user_103 dispararam o evento order_placed com as propriedades obrigatórias e as propriedades aninhadas.
  • Os pedidos dos usuários user_101 e user_102 incluem metadados adicionados ao array de propriedades discounts.

Etapa 4: Faça upload do arquivo

Para fazer upload do arquivo, selecione Atributos, Eventos personalizados ou Eventos recomendados no menu suspenso Importar usuários, clique em Procurar arquivos e faça upload do seu CSV. A Braze exibe uma prévia das primeiras linhas e um resumo dos campos detectados.

Com arquivos grandes (até 500 MB para atributos padrão e atributos personalizados, ou 50 MB para eventos personalizados), o dashboard pode parar de responder temporariamente enquanto o arquivo é carregado e a Braze calcula a importação. Esses uploads e cálculos podem demorar mais do que com arquivos menores. Aguarde a conclusão dessa etapa. Para saber mais sobre limites de arquivo e tempo de processamento, consulte Construindo seu CSV.

Etapa 5: Mapeie seus campos

Depois da prévia, você pode mapear os cabeçalhos do CSV para atributos, eventos ou propriedades de eventos da Braze. A Braze mapeia automaticamente os campos do arquivo CSV para atributos, eventos ou propriedades de eventos com nomes idênticos e cria novos campos quando necessário. Você também pode ajustar manualmente as sugestões ou selecionar outros atributos, eventos ou propriedades.

No caso de propriedades de eventos, a Braze detecta as propriedades e as associa aos eventos relevantes conforme a célula do CSV contenha um valor não nulo, ou a partir de cabeçalhos que usam o formato legado com notação de ponto (como <event name>.properties.<property name>).

Página de mapeamento de colunas.

Status de mapeamento

A coluna de status de mapeamento indica a ação que ocorre quando o arquivo CSV é importado e pode ter qualquer um dos valores a seguir.

Status de mapeamento O que significa
Mapeado Campo mapeado para um atributo, evento ou identificador existente.
Novo atributo, Novo evento ou Nova propriedade de evento A Braze cria um novo atributo ou evento na importação. Você pode editá-lo selecionando o botão Editar novo atributo, Editar novo evento ou Editar nova propriedade.
Incompatibilidade de tipo de dado O tipo de dado detectado na coluna do CSV não corresponde ao tipo de dado do atributo, evento ou identificador existente. A Braze tenta converter o tipo de dado na importação para corresponder ao atributo existente. Se isso não for possível, a Braze descarta o valor.
Atributo na lista de bloqueio ou Evento na lista de bloqueio O campo do CSV corresponde ao nome de um atributo ou evento na lista de bloqueio. Selecione outro atributo ou evento para o mapeamento; caso contrário, ele não será importado.
Atributo duplicado Há um ou mais campos com o mesmo nome no arquivo CSV. Mapeie as colunas com nomes iguais para atributos diferentes; caso contrário, apenas a primeira coluna será importada.
Chave de evento reservada O nome da propriedade do evento corresponde a uma chave de evento reservada na Braze, como time ou event_name. Informe outro nome ou selecione outra propriedade para o mapeamento; caso contrário, ela será descartada.

Edição de novos atributos, eventos e propriedades

Quando não existe um atributo, evento ou propriedade de evento correspondente no seu espaço de trabalho, a Braze tenta criar um novo atributo, evento ou propriedade na importação usando o nome do campo do CSV e o tipo de dado detectado. Você pode editar esse novo campo antes da importação selecionando o botão Editar novo atributo, Editar novo evento ou Editar nova propriedade ao lado do status de mapeamento.

Botão Editar novo atributo na página de mapeamento de colunas.

Etapa 6: Escolha as preferências de direcionamento

Depois do mapeamento, você pode escolher entre as seguintes preferências de direcionamento na página Configurações de importação. Se você não precisa criar um novo filtro de direcionamento ou Segment a partir da importação, selecione Não disponibilizar esta lista como filtro de direcionamento.

Opção Descrição
Filtro de direcionamento Para transformar seu arquivo CSV em uma opção de redirecionamento ao criar Segments de usuários, escolha o arquivo no menu suspenso Atualizado/Importado do CSV e selecione Criar filtro de direcionamento.
Novos Segments Para também criar um novo Segment a partir do novo filtro de direcionamento, selecione Criar filtro de direcionamento e adicionar a um novo Segment.

Grupo de filtros com o filtro "Atualizado/Importado do CSV" incluindo um arquivo CSV chamado "Halloween season fun".

Etapa 7: Valide seu arquivo (opcional)

Antes de iniciar a importação, você pode executar a validação de arquivo para verificar erros e alertas em todas as linhas. Para validar o arquivo, selecione Validar arquivo antes de importar na página Configurações de importação e, em seguida, selecione Avançar.

A validação pode levar até 2 minutos para arquivos no tamanho máximo permitido. Durante a validação, você pode selecionar Pular validação para ignorá-la e seguir imediatamente.

Resultados da validação

Quando a validação termina, aparece um dos resultados a seguir.

Resultado O que significa Próxima etapa
Validação concluída Nenhum problema encontrado. Selecione Importar dados.
Problemas encontrados Algumas linhas têm erros ou alertas. Baixe o relatório de erros para revisá-los e selecione Importar mesmo assim para continuar ou Cancelar para corrigir o arquivo antes.
Tempo de validação esgotado O tempo da validação se esgotou. As linhas verificadas não tinham problemas. Selecione Importar dados. Um relatório completo estará disponível em alguns minutos.
Tempo de validação esgotado com problemas O tempo da validação se esgotou e foram encontrados erros em algumas das linhas verificadas. Baixe o relatório parcial para revisar o que foi encontrado e selecione Importar mesmo assim ou Cancelar.

Página de resumo exibindo a seção de problemas encontrados, com a contagem de linhas com erros e alertas e as opções de voltar, baixar o relatório de erros ou iniciar a importação.

Entendendo o relatório de erros

O relatório de erros é um arquivo CSV com todas as linhas sinalizadas, junto com os dados originais e uma descrição do problema.

Tipo de problema Descrição
Erro A linha será totalmente ignorada durante a importação.
Alerta A linha será importada, mas alguns valores serão descartados.

Depois de revisar o relatório, você pode corrigir os problemas no arquivo original e fazer o upload novamente, ou seguir com a importação e aceitar os resultados parciais.

Etapa 8: Inicie a importação de CSV

Quando estiver pronto, selecione Iniciar importação. Você pode acompanhar o andamento na página Importar usuários, que é atualizada automaticamente a cada 5 segundos. O processamento pode levar de alguns minutos a algumas horas, dependendo do tamanho do CSV. Durante esse período, o dashboard pode parar de responder ou ficar lento, mas a importação continua em andamento.

Status de importação

Depois de iniciar a importação, você pode verificar o status na página Importar usuários.

Status Descrição
Concluído Todas as linhas foram importadas com sucesso.
Sucesso parcial Algumas linhas falharam. Selecione o menu de três pontos ao lado da importação para baixar um relatório de erros ou o CSV original enviado.
Em andamento A importação está em execução.

Página Importar usuários exibindo o status Sucesso parcial com o menu de contexto aberto e as opções Baixar relatório de erros e Baixar CSV enviado.

O relatório de erros pós-importação inclui linhas que falharam por motivos não cobertos pela validação, por exemplo, quando um usuário não existe na Braze.

Considerações sobre pontos de dados

Cada dado de cliente importado de um arquivo CSV substitui o valor existente nos perfis de usuário e registra um ponto de dados, exceto IDs externos e valores em branco. Se tiver dúvidas sobre as particularidades dos pontos de dados da Braze, seu gerente de conta da Braze pode ajudar.

Consideração Detalhes
IDs externos Fazer upload de um CSV apenas com external_id não registra pontos de dados. Isso permite segmentar usuários existentes da Braze sem afetar os limites de dados. No entanto, incluir campos como email ou phone substitui os dados de usuários existentes e registra pontos de dados.

Importações de CSV usadas apenas para segmentação não registram pontos de dados, como aquelas que contêm apenas external_id, braze_id ou user_alias_name.
Valores em branco Valores em branco no seu CSV não substituem os dados existentes do perfil de usuário. Você não precisa incluir todos os atributos de usuário ou eventos personalizados ao importar.
Status de inscrição Atualizar email_subscribe, push_subscribe, subscription_group_id ou subscription_state não conta para o uso de pontos de dados.

Solução de problemas

Se você usou a validação de arquivo, comece pelo relatório de erros. Ele mostra o problema específico de cada linha sinalizada e explica como corrigi-lo. Para linhas que falharam durante a importação, e não na validação, baixe o relatório de erros: passe o mouse sobre a linha e selecione o botão na página Importar usuários.

Para solucionar problemas na importação via CSV, confira os problemas comuns nas seções a seguir.

Importação de CSV travada em Calculating

Em Importar usuários, Calculating significa que a Braze ainda está preparando o arquivo para processamento. Durante essa etapa, a contagem de linhas pode aparecer como 0 / Calculating até a preparação terminar.

Se sua importação parecer travada em Calculating:

  • Deixe a importação continuar. Não cancele nem faça o upload novamente, a menos que o suporte da Braze recomende.
  • Confirme se o arquivo está dentro dos limites suportados em Construindo seu CSV.
  • Revise a Etapa 4: Faça o upload do arquivo e a Etapa 8: Inicie a importação do CSV para entender o comportamento esperado do dashboard e os tempos de processamento.
  • Entre em contato com o suporte da Braze se Calculating durar muito mais do que o esperado para o tamanho do seu arquivo depois de fazer essas verificações.

Usar e-mail como external_id

A Braze não recomenda usar um endereço de e-mail como external_id. Se você usar o e-mail como external_id, inclua as colunas external_id e email no CSV para que os usuários continuem direcionáveis pelo canal de e-mail. Use vírgula (,) como delimitador de colunas, e não dois-pontos (:).

Aspas em valores de external_id

Se uma célula de external_id contiver aspas duplas, faça o escape duplicando o caractere (""), conforme descrito em Aspas duplas sem escape ou desbalanceadas. A importação via CSV não usa escape com barra invertida.

A importação de CSV não está disponível como filtro de Segment

Você só pode usar uma importação de CSV como filtro de Segment se tiver ativado uma preferência de direcionamento durante o upload.

Para verificar se a disponibilidade de direcionamento está ativada para uma importação existente:

  1. Na página Importar usuários, encontre sua importação de CSV.
  2. Verifique se Ir para Segment aparece para essa importação.
  3. Se Ir para Segment aparecer, seu CSV está disponível no filtro de Segment Updated/Imported from CSV.
  4. Se Ir para Segment não aparecer, a disponibilidade de direcionamento não foi ativada para essa importação.

Não é possível ativar a disponibilidade de direcionamento depois que o upload do CSV for concluído. Para usar esse CSV como filtro de Segment, faça o upload do arquivo novamente e, na Etapa 6: Escolha as preferências de direcionamento, selecione Criar filtro de direcionamento ou Criar filtro de direcionamento e adicionar ao novo Segment.

Se o seu objetivo é criar um Segment sem atualizar dados de perfil, faça o upload de um CSV que inclua apenas colunas de identificador (por exemplo, external_id ou colunas de identificador de alias) e selecione Criar filtro de direcionamento e adicionar ao novo Segment.

Problemas de formatação de arquivo

Linha malformada

Se o upload foi concluído com erros, pode haver uma linha malformada no seu arquivo CSV.

Para importar os dados corretamente, é necessário ter uma linha de cabeçalho. Cada linha deve ter o mesmo número de células que a linha de cabeçalho. Linhas com mais ou menos valores do que o cabeçalho serão excluídas da importação. Vírgulas dentro de um valor serão interpretadas como separador e podem causar esse erro.

Além disso, todos os dados devem estar codificados em UTF-8. Se o arquivo for salvo com uma codificação legada (por exemplo, alguns padrões do Excel), caracteres especiais e URLs nas células podem ser corrompidos e aparecer como pontos de interrogação (?) na Braze ou nas mensagens enviadas.

Se o seu arquivo CSV tiver linhas em branco e importar menos linhas do que o total de linhas do arquivo, isso não indica necessariamente um problema, já que as linhas em branco não precisam ser importadas. Verifique o número de linhas importadas corretamente e confirme se ele corresponde ao número de usuários que você está tentando importar.

Linha ausente

Há alguns motivos pelos quais o número de usuários importados pode não corresponder ao total de linhas do seu arquivo CSV:

Problema Solução
IDs externos, aliases de usuário, IDs da Braze, endereços de e-mail ou números de telefone duplicados Colunas de ID externo duplicadas podem causar linhas malformadas ou não importadas, mesmo que as linhas estejam formatadas corretamente. Em alguns casos, nenhum erro específico é informado. Verifique se há duplicatas e remova-as antes de fazer o upload novamente.
Caracteres acentuados Seu CSV pode incluir nomes ou atributos com acentos. Confirme que o arquivo está codificado em UTF-8 para evitar problemas na importação.
O ID da Braze pertence a um usuário órfão Se um usuário foi mesclado a outro e a Braze não consegue associar o ID da Braze ao perfil restante, a linha não será importada.
Linha vazia Linhas em branco no CSV podem causar erros de dados malformados. Verifique usando um editor de texto simples, e não o Excel ou o Planilhas.
Aspas duplas (") sem escape ou desbalanceadas As aspas duplas envolvem valores de string que contêm vírgulas. Se um valor contiver aspas duplas, faça o escape duplicando-as (""). Aspas duplas sem escape ou desbalanceadas geram uma linha malformada.
Quebras de linha inconsistentes Quebras de linha misturadas (por exemplo, \n e \r\n) podem fazer com que a primeira linha de dados seja tratada como parte do cabeçalho. Use um editor hexadecimal ou um editor de texto avançado para inspecionar e corrigir.
Arquivo com codificação incorreta Mesmo que acentos sejam permitidos, o arquivo deve estar codificado em UTF-8. Outras codificações podem funcionar parcialmente, mas não são totalmente suportadas.

Strings entre aspas

Valores entre aspas simples ('') ou duplas ("") serão lidos como strings na importação.

Datas formatadas incorretamente

Datas que não estão no formato ISO-8601 não serão lidas como datetimes na importação.

Problemas de estrutura de dados

Endereços de e-mail inválidos

Se o upload foi concluído com erros, pode haver um ou mais endereços de e-mail criptografados inválidos. Confirme que todos os endereços de e-mail estão criptografados corretamente antes de importá-los para a Braze.

  • Ao atualizar ou importar endereços de e-mail na Braze, use o valor de e-mail com hash sempre que um e-mail for incluído. Esses valores de e-mail com hash são fornecidos pela sua equipe interna.
  • Ao criar um novo usuário, você deve adicionar email_encrypted com o valor de e-mail criptografado do usuário. Caso contrário, a Braze não criará o usuário. Da mesma forma, se você estiver adicionando um endereço de e-mail a um usuário existente que não tem e-mail, é necessário adicionar email_encrypted. Caso contrário, a Braze não atualizará o usuário.

Dados importados como atributo personalizado

Se um dado de usuário padrão (como email ou first_name) for importado como atributo personalizado, verifique as maiúsculas, minúsculas e os espaços no seu arquivo CSV. Por exemplo, First_name é importado como atributo personalizado, enquanto first_name é importado corretamente no campo “nome” do perfil do usuário.

Alterar o tipo de dados de um atributo personalizado

Se você precisar alterar o tipo de dados de um atributo personalizado existente (por exemplo, de string para booleano), atualize o tipo de dados na página Atributos personalizados no dashboard antes de importar o CSV. Se o tipo de dados no CSV não corresponder ao tipo de dados definido atualmente para o atributo, a importação falhará com um erro.

Vários tipos de dados

A Braze espera que todos os valores de uma coluna sejam do mesmo tipo de dados. Valores que não correspondem ao tipo de dados do atributo causam erros na segmentação.

Além disso, começar um atributo numérico com zero causa problemas, porque números que começam com zero são considerados strings. Quando a Braze converte essa string, ela pode ser tratada como um valor octal (que usa dígitos de zero a sete), ou seja, é convertida no valor decimal correspondente. Por exemplo, se o valor no arquivo CSV for 0130, o perfil na Braze mostrará 88. Para evitar esse problema, use atributos com tipo de dados string. No entanto, esse tipo de dados não está disponível na comparação numérica da segmentação.

Tipos de atributos padrão

Alguns atributos padrão só aceitam determinados valores como válidos para atualizações de usuários. Para saber mais, consulte Construindo seu CSV.

Espaços no final e diferenças entre maiúsculas e minúsculas podem fazer com que um valor seja interpretado como inválido. Por exemplo, no arquivo CSV a seguir, apenas o usuário da primeira linha (brazetest1) tem os status de e-mail e push atualizados com sucesso, porque os valores aceitos são unsubscribed, subscribed e opted_in.

external_id,email,email_subscribe,push_subscribe
brazetest1,[email protected],unsubscribed,unsubscribed
brazetest2,[email protected],Unsubscribed,Unsubscribed

O botão “Selecionar arquivo CSV” não está funcionando

Há vários motivos pelos quais o botão Selecionar arquivo CSV pode não funcionar:

Problema Solução
Bloqueador de pop-ups Ele pode impedir que a página seja exibida. Confirme que seu navegador permite pop-ups no website do dashboard da Braze.
Navegador desatualizado Verifique se o seu navegador está atualizado; se não estiver, atualize-o para a versão mais recente.
Processos em segundo plano Feche todas as instâncias do navegador e reinicie o computador.
New Stuff!