Importação por CSV

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

Sobre a importação por CSV

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

Usando a importação por CSV

Etapa 1: Baixar um modelo de CSV

Para abrir a importação por CSV, acesse Audiences > Import Users. Lá, você encontrará uma tabela com detalhes sobre as importações mais recentes, como a data do upload, o nome de quem fez o upload, o nome do arquivo, a disponibilidade de direcionamento, o número de linhas importadas e o status da importação.

Para começar com seu CSV, baixe um modelo para atributos ou eventos.

Etapa 2: Escolher um identificador

O CSV que você importar precisará de um identificador dedicado. Você pode escolher entre os seguintes:

• external id
• user alias
• braze id
• email address and phone numbers

Etapa 3: Construir seu arquivo CSV

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

• Atributos de usuário: Inclui tanto atributos de usuário padrão quanto personalizados. Atributos de usuário padrão são chaves reservadas na Braze (como first_name ou email) e atributos personalizados são atributos de usuário exclusivos do seu negócio (como last_destination_searched).
• Eventos personalizados: São exclusivos do seu negócio e refletem ações que um usuário realizou, como trip_booked para um app de reservas de viagens.

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

• user attributes
• custom events

Etapa 4: Fazer upload do seu arquivo

Para fazer upload do seu arquivo, selecione Attributes ou Events, clique em Browse Files e faça upload do seu CSV. A Braze exibe uma pré-visualização das primeiras linhas e um resumo dos campos detectados.

Para arquivos grandes (até 500 MB para atributos padrão e atributos personalizados, ou 50 MB para eventos personalizados), o dashboard pode parecer temporariamente sem resposta enquanto o arquivo é carregado e a Braze calcula a importação. Esses uploads e cálculos podem levar mais tempo para serem concluídos do que para arquivos menores. Aguarde a conclusão desta etapa. Para mais contexto sobre limites de arquivo e tempo, consulte Construindo seu CSV.

No campo Import name, você pode renomear sua importação. Por padrão, o nome do arquivo é usado.

Etapa 5: Validar seu arquivo (opcional)

Antes de iniciar sua importação, você pode executar a validação de arquivo para verificar todas as linhas em busca de erros e avisos. Para validar seu arquivo, selecione Validate file before importing e clique em Start import.

A validação pode levar até 2 minutos para arquivos no tamanho máximo permitido. Enquanto a validação é executada, você pode selecionar Skip validation para ignorá-la e prosseguir imediatamente.

Resultados da validação

Quando a validação for concluída, um dos seguintes resultados será exibido.

Entendendo o relatório de erros

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

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

Etapa 6: Escolher preferências de direcionamento

Você também pode escolher entre as seguintes preferências de direcionamento. Se você não precisar criar um novo filtro de direcionamento ou segmento a partir da sua importação, selecione Do not make this list available as a targeting filter.

Etapa 7: Iniciar sua importação por CSV

Quando estiver pronto, selecione Start import. Você pode acompanhar o progresso atual na página Import Users, que é atualizada automaticamente a cada 5 segundos. O processamento pode levar de alguns minutos a algumas horas, dependendo do tamanho do seu CSV. Durante esse tempo, o dashboard pode parecer sem resposta ou responder lentamente, mas a importação ainda está em execução.

Status da importação

Após iniciar sua importação, você pode verificar o status na página Import Users.

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

Considerações sobre pontos de dados

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

Solução de problemas

Se você usou a validação de arquivo, comece pelo relatório de erros, pois ele inclui o problema específico de cada linha sinalizada e uma descrição de como corrigi-lo. Para linhas que falharam durante a importação e não na validação, baixe o relatório de erros passando o cursor sobre a linha e selecionando o botão na página Import Users.

Para solucionar problemas de importação por CSV, revise os problemas comuns a seguir.

Problemas de formatação de arquivo

Linha malformada

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

Para importar dados corretamente, deve haver 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 que a linha de cabeçalho serão excluídas da importação. Vírgulas em um valor serão interpretadas como separador e podem causar esse erro. Além disso, todos os dados devem ser codificados em UTF-8.

Se o seu arquivo CSV tiver linhas em branco e importar menos linhas do que o total de linhas no arquivo CSV, isso pode não indicar um problema com a importação, já que as linhas em branco não precisariam ser importadas. Verifique o número de linhas que foram importadas corretamente e confirme se corresponde ao número de usuários que você está tentando importar.

Linha ausente

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

Aspas em strings

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

Datas formatadas incorretamente

Datas que não estejam 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 seu 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 possui e-mail, deve 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 a capitalização e o espaçamento do seu arquivo CSV. Por exemplo, First_name é importado como atributo personalizado, enquanto first_name é importado corretamente no campo “first name” do perfil do usuário.

Alterar o tipo de dado de um atributo personalizado

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

Múltiplos tipos de dados

A Braze espera que cada valor em uma coluna seja do mesmo tipo de dado. Valores que não correspondem ao tipo de dado do seu atributo causam erros na segmentação.

Além disso, iniciar um atributo numérico com zero causará problemas, pois números que começam com zeros 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), o que significa que é convertida para seu valor decimal correspondente. Por exemplo, se o valor no arquivo CSV for 0130, o perfil da Braze mostrará 88. Para evitar esse problema, use atributos com tipo de dado string. No entanto, esse tipo de dado não está disponível na comparação numérica de segmentação.

Tipos de atributos padrão

Alguns atributos padrão podem aceitar apenas determinados valores como válidos para atualizações de usuário. Para orientações, consulte Construindo seu CSV.

Espaços à direita e diferenças na capitalização podem fazer com que um valor seja interpretado como inválido. Por exemplo, no arquivo CSV a seguir, apenas o usuário na primeira linha (brazetest1) terá seus status de e-mail e push atualizados com sucesso, pois os valores aceitos são unsubscribed, subscribed e opted_in.

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

“Select CSV File” não está funcionando

Existem vários motivos pelos quais o botão Select CSV File pode não funcionar: