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.

Como os eventos recomendados usam um esquema definido, revise a guia Eventos recomendados na Etapa 3: Crie seu arquivo CSV antes do primeiro upload.
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.
- Download: Modelo de importação de atributos via CSV: ID externo
- Download: Modelo de importação de eventos via CSV: ID externo

Se você estiver fazendo upload de usuários com external_id junto com usuários sem esse identificador, precisa criar um CSV para cada importação. Um mesmo CSV não pode conter external_id e aliases de usuário.
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 aoexternal_iduser_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.

Não é possível usar a importação de CSV para atualizar um usuário existente com um user_alias_name se ele já tiver um external_id. Nesse caso, é criado um novo perfil de usuário com o user_alias_name associado. Para associar um usuário que tem apenas alias a um external_id, use o endpoint de identificação de usuários.
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.

Não é possível usar a importação de CSV para criar um novo usuário com braze_id. Esse método só pode ser usado para atualizar usuários que já existem na plataforma da Braze.

O valor braze_id pode aparecer como Appboy ID nas exportações de CSV feitas pelo dashboard da Braze. Esse ID é igual ao braze_id do usuário, então você pode renomear essa coluna para braze_id ao reimportar o CSV.
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 você incluir endereços de e-mail e números de telefone no arquivo CSV, o endereço de e-mail terá prioridade sobre o número de telefone na busca de perfis.
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_nameouemail), e os atributos personalizados são atributos de usuário exclusivos da sua empresa (comolast_destination_searched). - Eventos personalizados: São exclusivos da sua empresa e refletem ações realizadas pelo usuário, como
trip_bookedem 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_viewedecart_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_idbraze_iduser_alias_nameeuser_alias_labelemailphone
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. |

Arrays, tokens por push e tipos de dados de eventos personalizados não são compatíveis com a importação de usuários, porque as vírgulas no arquivo CSV são interpretadas como separadores de coluna e causam erros na leitura do arquivo.
Para fazer upload desses tipos de valores, use o endpoint /users/track ou a ingestão de dados na nuvem.
Atributos padrão

Ao importar atributos padrão, os cabeçalhos de coluna precisam corresponder exatamente à grafia e às maiúsculas e minúsculas dos atributos de usuário padrão. Caso contrário, a Braze os identifica como atributos personalizados.

Para ver a lista completa de atributos padrão reconhecidos pela Braze (no SDK, na API, no CSV e na ingestão de dados na nuvem), consulte Atributos padrão. A tabela a seguir abrange apenas os que podem ser definidos pela importação de CSV.
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: Oiddo grupo de inscrições.subscription_state: Os valores disponíveis sãounsubscribed(fora do grupo de inscrições) ousubscribed(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 |

Só é possível definir um único subscription_group_id por linha na importação de usuários. Linhas diferentes podem ter valores diferentes de subscription_group_id. Mas, se você precisar inscrever os mesmos usuários em vários grupos de inscrições, terá que fazer várias importações.
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_idbraze_iduser_alias_nameeuser_alias_labelemailphone
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.

O formato legado para cabeçalhos de propriedades de eventos continua sendo aceito, mas os cabeçalhos de propriedades não precisam seguir o formato <event_name>.properties.<property name>.
| 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.

Quando uma linha tiver dados de um evento específico, preencha apenas as colunas das propriedades desse evento. Deixe em branco as colunas de outros eventos.
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
123disparou o eventorented_moviecom as propriedadesmovie_name(Ghostbusters) egenre(Action) - O usuário
456disparou o eventobought_sitcomcom as propriedadessitcom_name(Scrubs) egenre(Comedy) - Cada evento preenche apenas as colunas das próprias propriedades, deixando em branco as colunas de propriedades de outros eventos
Identificadores obrigatórios
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_idbraze_iduser_alias_nameeuser_alias_labelemailphone
Campos de eventos recomendados
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. |
Requisitos de formato para 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.
Entendendo a formatação de eventos recomendados
É 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.
Agrupamentos de eventos recomendados para propriedades aninhadas
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.

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_102euser_103dispararam o eventoorder_placedcom as propriedades obrigatórias e as propriedades aninhadas. - Os pedidos dos usuários
user_101euser_102incluem metadados adicionados ao array de propriedadesdiscounts.

Quando uma linha tiver dados de um evento específico, preencha apenas as colunas das propriedades desse evento. Deixe em branco as colunas de outros eventos.
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.

A prévia mostra apenas as primeiras linhas do arquivo. Para verificar todas as linhas antes da importação, use a validação de arquivo.

As importações de usuários via CSV ficam disponíveis para download no dashboard por 14 dias após o upload. Depois desse período, o arquivo é excluído do armazenamento e deixa de ficar acessível.
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>).

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.


Não é possível avançar da etapa de mapeamento até que um identificador seja mapeado. A Braze mapeia um identificador automaticamente sempre que possível. Para eventos personalizados, também é preciso mapear as colunas name e time. Consulte a seção Campos obrigatórios para saber mais.
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. |

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. |

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.

Você pode importar mais de um CSV ao mesmo tempo. As importações de CSV são executadas simultaneamente, então não há garantia de que as atualizações aconteçam em sequência. Se você precisa que as importações de CSV sejam executadas uma após a outra, aguarde a conclusão de uma importação antes de fazer o upload da próxima.
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. |

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.

Os arquivos CSV enviados ficam disponíveis para download na página Importar usuários por 14 dias após a data de upload. Depois de 14 dias, o arquivo é excluído permanentemente e não pode mais ser acessado.
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. |

Definir language ou country em um usuário por meio de importação de CSV ou da API impede que a Braze capture automaticamente essas informações pelo SDK.
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.

Se uma importação falhar, revise os resultados da validação de arquivo e depois confira Problemas de formatação de arquivo e Problemas de estrutura de dados. Confirme se as colunas de identificador correspondem a Escolha um identificador antes de fazer o upload novamente. Se uma importação estiver travada em Calculating, não faça o upload novamente; consulte Importação de CSV travada em Calculating. Se uma importação não estiver disponível como filtro de Segment, consulte A importação de CSV não está disponível como filtro de Segment.
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
Calculatingdurar 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:
- Na página Importar usuários, encontre sua importação de CSV.
- Verifique se Ir para Segment aparece para essa importação.
- Se Ir para Segment aparecer, seu CSV está disponível no filtro de Segment
Updated/Imported from CSV. - 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_encryptedcom 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 adicionaremail_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. |