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 via CSV

Você pode usar a importação via CSV para registrar e atualizar os seguintes atributos de usuário 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 via CSV

Etapa 1: Baixar um modelo de CSV

Para abrir a importação via CSV, acesse Públicos > Importar Usuários. Aqui, você encontrará uma tabela que lista detalhes sobre as importações mais recentes, como a data de 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, selecione Attributes ou Events e, em seguida, baixe o modelo adequado para ajudar você a criar seu arquivo CSV para upload.

Etapa 2: Escolher um identificador

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

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

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

• Download: Modelo de importação de atributos via CSV: ID externo
• Download: Modelo de importação de eventos via CSV: ID externo

Nota

Se estiver fazendo upload de uma combinação de usuários com external_id e usuários sem, você precisará criar um CSV para cada importação. Um CSV não pode conter external_id e aliases de usuário ao mesmo tempo.

Para direcionar usuários que não possuem um external_id, você pode importar uma lista de usuários com aliases de usuário. Um alias serve como um identificador único alternativo e pode ser útil se você está tentando alcançar usuários anônimos que não se cadastraram ou criaram uma conta no seu app.

Se estiver fazendo upload ou atualizando perfis de usuário que possuem apenas alias, seu CSV deve conter as seguintes duas colunas:

• user_alias_name: Um identificador único de 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ê fornece user_alias_name e user_alias_label na importação, a Braze atualiza qualquer usuário existente com o mesmo user_alias_name e user_alias_label. Se um usuário não for encontrado, a Braze cria um novo usuário identificado com esse user_alias_name definido.

Importante

Não é possível usar uma importação via CSV para atualizar um usuário existente com user_alias_name se ele já tiver um external_id. Em vez disso, isso cria um novo perfil de usuário com o user_alias_name associado. Para associar um usuário somente com alias a um external_id, use o endpoint Identificar 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 valor interno de ID da Braze em vez de external_id ou user_alias_name e user_alias_label, especifique braze_id como cabeçalho de coluna.

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

Importante

Não é possível usar uma importação via CSV para criar um novo usuário usando braze_id. Esse método só pode ser usado para atualizar usuários pré-existentes na plataforma Braze.

Dica

O valor braze_id pode aparecer como Appboy ID nas exportações via CSV do dashboard da Braze. Esse ID será o mesmo que o 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 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 você não possui IDs externos ou aliases de usuário para esses perfis no seu arquivo CSV. Se tiver, a Braze priorizará o uso do ID externo ou alias de usuário antes do endereço de e-mail para identificar perfis.
• Confirme que seu arquivo CSV está formatado corretamente.

Nota

Se você incluir endereços de e-mail e números de telefone no seu arquivo CSV, o endereço de e-mail será priorizado em relação ao número de telefone na busca de perfis.

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

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

Etapa 3: Construir seu arquivo CSV

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

• Atributos de usuário: Isso inclui atributos de usuário padrão e 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 realizadas por um usuário, como trip_booked para um app de reserva de viagens.

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

• user attributes
• custom events

Identificadores obrigatórios

Embora external_id não seja obrigatório, seu arquivo CSV deve incluir um identificador de usuário que possa ser mapeado para um dos seguintes identificadores. Para detalhes sobre cada um, consulte Escolher 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 para importação via CSV. Cabeçalhos de coluna que não correspondam exatamente a um atributo padrão são importados como atributos personalizados na Braze, a menos que sejam alterados durante a etapa de mapeamento.

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

Importante

Arrays, tokens por push e tipos de dados de eventos personalizados não são compatíveis com a importação de usuários, pois vírgulas no seu arquivo CSV serão interpretadas como separadores de coluna e causarão erros na análise 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

Importante

Ao importar atributos padrão, os cabeçalhos de coluna utilizados devem corresponder exatamente à ortografia e capitalização dos atributos de usuário padrão. Caso contrário, a Braze os detectará como atributos personalizados.

Dica

Para a lista completa de atributos padrão que a Braze reconhece (via SDK, API, CSV e ingestão de dados na nuvem), consulte Atributos padrão. A tabela a seguir cobre apenas o subconjunto que pode ser definido por meio de importação via CSV.

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

Campo do perfil de usuário	Tipo de dados	Descrição	Obrigatório?
external_id	String	Um identificador único de usuário para seu cliente.	Condicional. Consulte Identificadores obrigatórios.
user_alias_name	String	Um identificador único de usuário para usuários anônimos, como alternativa ao external_id. Deve ser usado com user_alias_label.	Condicional. 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.	Condicional. Consulte Identificadores obrigatórios.
first_name	String	O nome dos seus usuários conforme indicado (por exemplo, Jane).	Não
last_name	String	O sobrenome dos seus usuários conforme indicado (por exemplo, Doe).	Não
email	String	O e-mail dos seus usuários conforme indicado (por exemplo, [email protected]).	Não
country	String	Os códigos de país devem ser passados para a Braze no padrão ISO-3166-1 alpha-2 (por exemplo, GB).	Não
dob	String	Deve ser passado no formato “YYYY-MM-DD” (por exemplo, 1980-12-21). Isso importa a data de nascimento do seu usuário e permite que você direcione usuários cujo aniversário é “hoje”.	Não
gender	String	“M”, “F”, “O” (outro), “N” (não aplicável), “P” (prefere não dizer) ou nil (desconhecido).	Não
home_city	String	A cidade natal dos seus usuários conforme indicado (por exemplo, London).	Não
language	String	O idioma deve ser passado para a 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 conforme indicado pelos seus usuários, no formato E.164 (por exemplo, +442071838750). Consulte Números de telefone do usuário para orientações de formatação.	Não
email_open_tracking_disabled	Boolean	Aceita true ou false. Defina como true para desativar a adição do pixel de rastreamento de abertura em todos os e-mails futuros enviados para este usuário.	Não
email_click_tracking_disabled	Boolean	Aceita true ou false. Defina como true para desativar o rastreamento de cliques em todos os links de e-mails futuros enviados para este usuário.	Não
email_subscribe	String	Os valores disponíveis são opted_in (registrou-se explicitamente para receber mensagens de e-mail), unsubscribed (cancelou explicitamente o recebimento de mensagens de e-mail) e subscribed (nem optou por receber nem cancelou).	Não
push_subscribe	String	Os valores disponíveis são opted_in (registrou-se explicitamente para receber mensagens push), unsubscribed (cancelou explicitamente o recebimento de mensagens push) e subscribed (nem optou por receber nem cancelou).	Não
time_zone	String	O fuso horário deve ser passado para a Braze no mesmo formato do banco de dados IANA Time Zone (por exemplo, America/New_York ou Eastern Time (US & Canada)).	Não
date_of_first_session date_of_last_session	String	Pode ser passado 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 pode ser encontrado na página de grupos de inscrições do seu dashboard.	Não
subscription_state	String	O estado da inscrição para o grupo de inscrições especificado por subscription_group_id. Os valores permitidos são unsubscribed (não está no grupo de inscrições) ou subscribed (está no grupo de inscrições).	Não, mas fortemente recomendado se subscription_group_id for usado

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

Além disso, você pode adicionar usuários a grupos de inscrições de e-mail ou SMS por meio da importação de usuários. Isso é particularmente útil para SMS, pois um usuário deve 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 estiver atualizando status de grupos de inscrições, seu CSV deve conter as seguintes duas colunas:

• subscription_group_id: O id do grupo de inscrições.
• subscription_state: Os valores disponíveis são unsubscribed (não está no grupo de inscrições) ou subscribed (está 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

Nota

Apenas um único subscription_group_id pode ser definido por linha na importação de usuários. Diferentes linhas podem ter valores de subscription_group_id diferentes. Porém, se for necessário inscrever os mesmos usuários em vários grupos de inscrições, você precisará realizar várias importações.

Identificadores obrigatórios

Embora external_id não seja obrigatório, seu arquivo CSV deve incluir um identificador de usuário que mapeie para um dos seguintes identificadores. Para detalhes sobre cada um, consulte Escolher 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 conter cabeçalhos de coluna adicionais para propriedades de evento. Essas propriedades devem ter um cabeçalho de coluna no formato <event_name>.properties.<property name> ou <property name>.

Por exemplo, o evento personalizado trip_booked pode ter as propriedades destination e duration. Você pode importá-las usando os cabeçalhos de coluna trip_booked.properties.destination e trip_booked.properties.duration. Você também pode representar propriedades nos cabeçalhos como <property name>. A Braze detecta as propriedades relevantes para cada evento com base na existência de um valor na célula CSV correspondente.

Campo do perfil de usuário	Tipo de dados	Informações	Obrigatório?
external_id	String	Um identificador único de usuário para o seu usuário.	Condicional. Consulte Identificadores obrigatórios.
braze_id	String	Um identificador atribuído pela Braze ao seu usuário.	Condicional. Consulte Identificadores obrigatórios.
user_alias_name	String	Um identificador único de usuário para usuários anônimos, como alternativa ao external_id. Deve ser usado com user_alias_label.	Condicional. 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.	Condicional. Consulte Identificadores obrigatórios.
email	String	O e-mail dos seus usuários conforme indicado (por exemplo, [email protected]).	Não, e só pode ser usado na ausência de outros identificadores. Consulte a nota a seguir.
phone	String	Um número de telefone conforme indicado pelos seus usuários, no formato E.164 (por exemplo, +442071838750). Consulte Números de telefone do usuário para orientações de formatação.	Não, e só pode ser usado na ausência de outros identificadores. Consulte a nota a seguir.
name	String	Um evento personalizado dos seus usuários.	Sim
time	String	O horário do evento. Pode ser passado 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
<event name>.properties.<property name>	Múltiplos	Uma propriedade de evento associada a um evento personalizado. Um exemplo é trip_booked.properties.destination	Não
<property name>	Múltiplos	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 CSV correspondente.	Não

Requisitos de formato para eventos personalizados

Ao importar eventos personalizados via CSV, você deve formatar seu arquivo de acordo com os seguintes requisitos para garantir uma importação de dados bem-sucedida.

Entendendo a formatação de eventos personalizados

Formate corretamente o CSV de eventos personalizados usando notação de ponto, ou com um valor não nulo na célula correspondente, para que a Braze mapeie cada propriedade para o evento final. Se a formatação estiver incorreta, as propriedades podem ser descartadas ou a importação pode falhar, especialmente quando vários tipos de evento estão incluídos em um único arquivo.

Use notação de ponto para propriedades de evento

Use a notação de ponto para definir a relação hierárquica entre um evento personalizado e suas propriedades. Essa convenção de formatação permite importar dados estruturados de eventos que incluem atributos específicos para cada evento.

O formato de notação de ponto segue esta estrutura: event_name.properties.property_name

A notação de ponto funciona na seguinte sequência:

1. O nome do evento vem primeiro
2. Seguido por .properties. para indicar que o que vem a seguir é uma propriedade do evento
3. Por fim, o nome específico da propriedade

Exemplo:

Para um evento personalizado chamado rented_movie com as propriedades movie_name e genre, os cabeçalhos de coluna do seu CSV seriam:

• rented_movie.properties.movie_name
• rented_movie.properties.genre

Essa notação informa à Braze para criar um evento personalizado chamado rented_movie e anexar as propriedades movie_name e genre a essa instância específica do evento.

Se você usar uma combinação de notação de ponto e notação sem ponto para importar propriedades, o upload do CSV pode falhar porque a Braze detecta cabeçalhos duplicados. Isso ocorre quando há os cabeçalhos rented_movie.properties.movie_name e movie_name dentro do mesmo arquivo. Para evitar isso, use apenas um formato de propriedades nos seus cabeçalhos.

Um evento por linha

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

Importante

Quando uma linha contém 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 demonstra a formatação correta para importar eventos personalizados com propriedades. Este exemplo mostra dois usuários que realizaram eventos diferentes: um alugou um filme e o outro comprou um filme.

external_id	name	time	rented_movie.properties.movie_name	rented_movie.properties.genre	bought_movie.properties.movie_name	bought_movie.properties.genre
123	rented_movie	2024-06-10T12:00:00Z	Ghostbusters	Action
456	bought_movie	2024-06-12T12:00:00Z			Ghostbusters	Action

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_movie com as propriedades movie_name (Ghostbusters) e genre (Action)
• Cada evento preenche apenas suas colunas de propriedade relevantes, deixando as colunas de propriedade de outros eventos em branco

Etapa 4: Fazer upload do seu arquivo

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

Para arquivos grandes (até 500 MB para atributos padrão e 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 essa etapa ser concluída. Para mais contexto sobre limites de arquivo e tempo, consulte Construindo seu CSV.

Antes de fazer upload do seu arquivo CSV, renomeie-o com o nome de importação que deseja ver na Braze. Não é possível editar o nome da importação após o upload.

Nota

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

Importante

As importações de usuários via CSV ficam disponíveis para download no dashboard por 14 dias após o upload. Após esse período, o arquivo é excluído do armazenamento e não pode mais ser acessado.

Etapa 5: Mapear seus campos

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

Para propriedades de evento, a Braze detecta propriedades e as associa aos eventos relevantes com base na existência de um valor não nulo na célula CSV, ou a partir de cabeçalhos que usam notação de ponto no formato <event name>.properties.<property name>.

Status de mapeamento

A coluna de status de mapeamento indica a ação que ocorre quando seu arquivo CSV é importado e pode ser qualquer um dos seguintes.

Editando novos atributos, eventos e propriedades

Quando um atributo, evento ou propriedade de evento correspondente não existe no seu espaço de trabalho, a Braze tenta criar um novo atributo, evento ou propriedade na importação usando o nome do campo CSV e o tipo de dados 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.

Nota

Não é possível prosseguir além da etapa de mapeamento até que um identificador seja mapeado. A Braze mapeia automaticamente um identificador quando possível. Para eventos personalizados, você também deve mapear as colunas name e time. Consulte a seção Campos obrigatórios para mais informações.

Etapa 6: Escolher preferências de direcionamento

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

Etapa 7: Validar seu arquivo (opcional)

Antes de iniciar a importação, você pode executar a validação de arquivo para verificar cada linha em busca de erros e alertas. Para validar seu arquivo, selecione Validar arquivo antes de importar na página de configurações de importação e, em seguida, selecione Próximo.

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

Resultados da validação

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

Entendendo o relatório de erros

O relatório de erros é um arquivo CSV que contém cada linha sinalizada 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 o upload novamente, ou prosseguir com a importação e aceitar os resultados parciais.

Etapa 8: Iniciar a importação via 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 lento, mas a importação ainda está em execução.

Nota

Você pode importar mais de um CSV ao mesmo tempo. As importações de CSV são executadas simultaneamente, então a ordem das atualizações não é garantida como serial. Se precisar que as importações de CSV sejam executadas uma após a outra, aguarde até que uma importação de CSV seja concluída antes de fazer upload de uma segunda.

Status de importação

Após iniciar a 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 razões que a validação não cobre, como quando um usuário não existe na Braze.

Importante

Arquivos CSV carregados anteriormente ficam disponíveis para download na página Import Users por 14 dias após a data de upload. Após 14 dias, o arquivo é excluído permanentemente e não pode mais ser acessado.

Considerações sobre pontos de dados

Cada informação de cliente importada 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 particularidades dos pontos de dados da Braze, seu gerente de conta da Braze pode esclarecê-las.

Importante

Definir language ou country em um usuário por meio de importação via CSV ou 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, 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 em vez da 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 de CSV, revise esses problemas comuns nas seções a seguir.

Importação de CSV travada em Calculating

Em Import Users, Calculating significa que a Braze ainda está preparando o arquivo para processamento. Durante essa etapa, a contagem de linhas pode ser exibida como 0 / Calculating até que a preparação termine.

Se sua importação parecer travada em Calculating:

• Deixe a importação continuar. Não cancele e reenvie o arquivo, a menos que o suporte da Braze recomende.
• Confirme que seu arquivo está dentro dos limites suportados em Construindo seu CSV.
• Revise a Etapa 4: Faça upload do seu arquivo e a Etapa 8: Inicie sua importação de CSV para 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 após você confirmar 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 e-mail como external_id, inclua as colunas external_id e email no seu CSV para que os usuários permaneçam direcionáveis no canal de e-mail. Use uma vírgula (,) como delimitador de coluna, e não dois pontos (:).

Caracteres de aspas em valores de external_id

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

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 Import Users, encontre sua importação de CSV.
2. Verifique se Go to Segment aparece para essa importação.
3. Se Go to Segment aparecer, seu CSV está disponível no filtro de Segment Updated/Imported from CSV.
4. Se Go to 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 após a conclusão de um upload de CSV. Para usar esse CSV como filtro de Segment, reenvie o arquivo e, na Etapa 6: Escolha as preferências de direcionamento, selecione Create targeting filter ou Create targeting filter and add to new segment.

Se seu objetivo é criar um Segment sem atualizar os dados do perfil, faça upload de um CSV que inclua apenas colunas de identificadores (por exemplo, external_id ou colunas de identificadores de alias) e selecione Create targeting filter and add to new segment.

Problemas de formatação de arquivo

Linha malformada

Se 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 do que a linha de cabeçalho serão excluídas da importação. Vírgulas dentro de um valor serão interpretadas como separadores 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 em mensagens enviadas.

Se 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 que 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 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 estiver 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, você deve adicionar email_encrypted. Caso contrário, a Braze não atualizará o usuário.

Dados importados como atributo personalizado

Se um dado padrão do usuário (como email ou first_name) for importado como atributo personalizado, verifique as maiúsculas/minúsculas e o espaçamento do 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 Custom Attributes no dashboard antes de importar seu CSV. Se o tipo de dados no seu CSV não corresponder ao tipo de dados 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 dados. Valores que não correspondem ao tipo de dados 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 tipos de dados string. Entretanto, esse tipo de dados 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ários. Para orientação, consulte Construindo seu CSV.

Espaços à direita e diferenças em maiúsculas/minúsculas 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) tem 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: