importação de usuário

A Braze oferece uma variedade de maneiras de importar dados de usuários para a plataforma: SDKs, APIs, ingestão de dados na nuvem, integrações com parceiros de tecnologia e arquivos CSV.

Antes de prosseguir, vale frisar que a Braze não sanitiza (valida ou formata corretamente) os dados HTML durante a importação. Isso significa que as tags de script devem ser removidas para todos os dados de importação destinados à personalização da web.

Ao importar dados para o Braze que são especificamente destinados ao uso de personalização em um navegador web, certifique-se de que eles estejam livres de HTML, JavaScript ou qualquer outra tag de script que possa ser potencialmente usada de forma maliciosa quando renderizada em um navegador web.

Alternativamente, para HTML, você pode usar os filtros de Liquid (strip_html) da Braze para escapar o texto renderizado em HTML. Por exemplo:

• entrada
• saída

1
{{ "Have <em>you</em> read <strong>Ulysses</strong>?" | strip_html }}

1
Have you read Ulysses?

API REST

Use o endpoint/users/track para registrar eventos personalizados, atributos de usuário e compras para usuários.

Ingestão de dados na nuvem

Use o Braze Cloud Data Ingestion para importar e manter as atribuições de usuários.

importação de CSV

Você pode fazer upload e atualizar perfis de usuários através de arquivos CSV de público > Importar Usuários.

A importação de CSV suporta o registro e a atualização de atribuições do usuário, como nome e e-mail, além de atributos personalizados, como tamanho do sapato. Você pode importar um CSV especificando um dos dois identificadores exclusivos de usuário: um external_id ou um alias de usuário.

Construindo seu CSV

Existem vários tipos de dados no Braze. Ao importar ou atualizar perfis de usuários com um arquivo CSV, você pode criar ou atualizar atributos de usuário padrão ou atributos personalizados.

• Os atributos padrão do usuário são chaves reservadas no Braze. Por exemplo, first_name ou email.
• Atributos personalizados são personalizados para o seu negócio. Por exemplo, um app de reserva de viagens pode ter um atributo personalizado chamado last_destination_searched.

A Braze aceita dados de usuários no formato CSV padrão de arquivos com até 500 MB de tamanho. Consulte as seções anteriores sobre importação para modelos de CSV disponíveis para download.

Considerações sobre pontos de dados

Cada peça de dados de cliente importada de um arquivo CSV substituirá o valor existente nos perfis de usuário e contará como um ponto de dados, exceto para IDs externos e valores em branco.

• IDs externos carregados de um arquivo CSV não consumirão pontos de dados. Se você estiver carregando um CSV para segmentar usuários existentes do Braze carregando apenas IDs externos, isso pode ser feito sem consumir pontos de dados. Se você adicionar mais dados como e-mails de usuários ou números de telefone na sua importação, isso substituirá os dados de usuários existentes, consumindo seus pontos de dados.
  • Importações de CSV para fins de segmentação (importações feitas com external_id, braze_id ou user_alias_name como o único campo) não consumirão pontos de dados.
• Valores em branco não substituirão os valores existentes no perfil do usuário, e você não precisa incluir todos os atributos de usuário existentes no seu arquivo CSV.
• A atualização de email_subscribe, push_subscribe, subscription_group_id ou subscription_state não contará para o consumo de dados.

Cabeçalhos de colunas de dados de usuários padrão

Importando um CSV

Para importar o arquivo CSV, acesse Públicos > Importação de usuário. Aqui, você encontrará uma tabela que lista as importações mais recentes, que inclui detalhes como a data de fazer upload, o nome do responsável pelo upload, nome do arquivo, disponibilidade de direcionamento, número de linhas importadas e status de cada importação.

Selecione Pesquisar arquivos e seu arquivo. Braze fará upload do seu arquivo e verificará os cabeçalhos das colunas e os tipos de dados de cada coluna.

Para baixar um modelo CSV, consulte as seções Importando com ID externo ou Importando com alias de usuário nesta página.

Após a conclusão do upload, você pode ver uma prévia do conteúdo do seu arquivo. Todas as informações nesta tabela são baseadas nos valores das primeiras linhas do seu arquivo CSV. Para cabeçalhos de coluna, os atributos padrão são escritos em texto normal, enquanto os atributos personalizados são italicizados e têm seu tipo anotado entre parênteses. Há também um resumo do seu arquivo no topo do pop-up.

Você pode importar mais de um CSV ao mesmo tempo. As importações de CSV são executadas simultaneamente, o que significa que a ordem das atualizações não é garantida como serial. Se você precisar que as importações de CSV sejam executadas uma após a outra, espere uma importação de CSV terminar para enviar outra.

Se a Braze notar algo malformado no arquivo durante o upload, esses erros aparecerão no resumo. Por exemplo, se o seu arquivo incluir uma linha malformada, esse erro será anotado na prévia quando você importar o arquivo. Então, um arquivo pode ser importado com erros, mas uma importação não pode ser cancelada ou revertida depois de iniciada. Revise a prévia e, se encontrar algum erro, cancele a importação e modifique seu arquivo.

Linhas malformadas e linhas sem um ID externo não serão importadas. Todos os outros erros podem ser importados, mas podem interferir na filtragem ao criar um segmento. Para saber mais, pule para a seção Resolução de Problemas.

Quando você estiver satisfeito com o upload, inicie a importação. O pop-up será fechado e a importação começará em segundo plano. Você pode acompanhar o progresso na página de importação de usuário, que será atualizada a cada FIVE segundos, ou ao pressionar o botão de atualização na caixa de Importações Recentes.

Sob Linhas Processadas está o progresso da importação; o status mudará para Concluído quando terminado. Você ainda pode usar o restante do dashboard do Braze durante a importação e receberá notificações quando a importação começar e terminar.

Se o processo de importação encontrar um erro, um ícone de aviso amarelo será exibido ao lado do número total de linhas no arquivo. Você pode passar o cursor sobre o ícone para ver detalhes sobre por que certas linhas falharam. Após a importação ser concluída, todos os dados serão adicionados aos perfis existentes ou novos perfis serão criados.

Importando com ID externo

Ao importar os dados de seus clientes, você precisará especificar o identificador exclusivo de cada cliente (external_id). Antes de iniciar sua importação de CSV, é importante entender com sua equipe de engenharia como os usuários serão identificados no Braze. Normalmente, este é um ID de banco de dados interno. Isso deve estar alinhado com a forma como os usuários serão identificados pelo Braze SDK em dispositivos móveis e web e é projetado para que cada cliente tenha um único perfil de usuário no Braze em todos os seus dispositivos. Leia mais sobre o ciclo de vida do perfil de usuário da Braze.

Quando você fornece um external_id na sua importação, a Braze atualizará qualquer usuário existente com o mesmo external_id ou criará um novo usuário identificado com esse conjunto de external_id se não for encontrado nenhum.

Baixe: Modelo de importação CSV

Importando com alias de usuário

Para direcionar os usuários que não têm um external_id, é possível importar uma lista de usuários com aliases de usuário. Um alias serve como um identificador único de usuário alternativo e pode ser útil se você estiver tentando fazer marketing para usuários anônimos que não se inscreveram ou criaram uma conta no seu app.

Se você estiver carregando ou atualizando perfis de usuário que são apenas alias, você deve ter as seguintes duas colunas em seu CSV:

• user_alias_name: Um identificador único de usuário; uma alternativa ao external_id
• user_alias_label: Um rótulo comum pelo qual agrupar aliases de usuário

Quando você fornece tanto um user_alias_name quanto um user_alias_label na sua importação, a Braze atualizará qualquer usuário existente com o mesmo user_alias_name e user_alias_label. Se um usuário não for encontrado, a Braze criará um novo usuário identificado com esse user_alias_name definido.

Baixe: [Modelo de Importação de eventos de alias CSV][template_alias_events]

Importando com Braze ID

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

Isso pode ser útil se você exportou dados de usuários do Braze através da nossa opção de exportação CSV dentro da segmentação e deseja adicionar um novo atributo personalizado a esses usuários existentes.

Importação com endereços de e-mail e números de telefone

É possível omitir uma ID externa ou um 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:

• Verifique se não há IDs externos ou aliases de usuário para esses perfis no arquivo CSV. Se o fizer, o Braze priorizará o uso da ID externa ou do alias do usuário antes do endereço de e-mail para identificar perfis.
• Confirme se o arquivo CSV está formatado corretamente.

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

Se não houver um perfil com esse endereço de e-mail ou número de telefone, o Braze criará 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.

Importando dados personalizados

Todos os cabeçalhos que não corresponderem exatamente aos dados de usuários padrão criarão um atributo personalizado no Braze.

Os seguintes tipos de dados são aceitos na importação de usuário:

• Data e hora: Deve ser armazenado no formato ISO-8601
• Booleano: true ou false
• Número: Inteiro ou float sem espaços ou vírgulas; os floats devem usar um ponto (.) como separador decimal
• String: Pode conter vírgulas se houver aspas duplas ("") ao redor do valor da coluna
• Em branco: Os valores em branco não substituirão os valores existentes no perfil do usuário, e não é necessário incluir todas as atribuições do usuário existentes no arquivo CSV

Importação de CSV do usuário Lambda

Você pode usar nosso script de importação CSV Lambda S3 sem servidor para fazer upload de atributos de usuário para a plataforma. Essa solução funciona como um carregador de CSV onde você solta seus CSVs em um bucket S3, e os scripts fazem upload através da nossa API.

O tempo de execução estimado para um arquivo com 1.000.000 de linhas deve ser de cerca de cinco minutos. Para saber mais, consulte CSV de atributos do usuário para importação da Braze.

Atualização do status do grupo de inscrições

É possível adicionar usuários a grupos de inscrições para e-mail ou SMS por meio da importação de usuários. Isso é particularmente útil para SMS, porque um usuário deve estar inscrito em um grupo de inscrições de SMS para ser enviado uma mensagem pelo canal de SMS. Para saber mais, consulte os grupos de inscrição de SMS.

Se estiver atualizando os status do grupo de inscrições, é necessário ter as duas colunas a seguir no CSV:

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

Criação de um filtro de redirecionamento a partir de uma importação de usuário

A importação de usuários pode ser usada para transformar o arquivo CSV em um filtro de redirecionamento, selecionando Importe os usuários neste CSV e possibilite o redirecionamento de um lote específico de usuários como grupo.. Para filtrar pelo arquivo em um segmento ou onde quer que a filtragem seja uma opção, selecione o filtro Atualizado/Importado de CSV e, em seguida, pesquise o nome exato do arquivo.

Criação de segmentos a partir de uma importação de usuário

A importação de usuários também pode ser usada para criar segmentos selecionando Importe os usuários neste CSV e possibilite o redirecionamento de um lote específico de usuários como grupo. e marcando Gere automaticamente um segmento a partir dos usuários importados deste CSV antes de iniciar a importação.

Você pode definir o nome do segmento ou aceitar o padrão, que é o nome do seu arquivo. Os arquivos que foram usados para criar um segmento terão um link para visualizar o segmento após a importação ser concluída.

O filtro usado para criar o segmento seleciona usuários que foram criados ou atualizados em uma importação selecionada e está disponível com todos os outros filtros na página de edição do segmento.

Considerações

Solução de problemas

Upload concluído com erros

Linha malformada

Deve haver uma linha de cabeçalho para importar os dados corretamente. Cada linha deve ter o mesmo número de células que a linha de cabeçalho. Linhas com um comprimento de mais ou menos valores do que a linha de cabeçalho serão excluídas da importação. As vírgulas em um valor serão interpretadas como um separador e podem levar a 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, pois as linhas em branco não precisariam ser importadas. Verifique o número de linhas que foram importadas corretamente e certifique-se de que corresponde ao número de usuários que você está tentando importar.

Endereços de e-mail inválidos

O Braze detectou endereços de e-mail criptografados inválidos. Confirme se todos os endereços de e-mail estão criptografados corretamente antes de importá-los para o Braze.

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

Linhas ausentes

Há algumas razões pelas quais o número de usuários importados pode não corresponder ao total de linhas no seu arquivo CSV:

• Duplicar IDs externas, aliases de usuários, IDs do Braze, endereços de e-mail ou números de telefone: Se houver colunas de ID externas duplicadas, isso poderá causar linhas malformadas ou não importadas, mesmo que as linhas estejam formatadas corretamente. Em alguns casos, isso pode não informar um erro específico. Verifique se há IDs externos duplicados no seu CSV. Se for o caso, remova os duplicados e tente fazer o upload novamente.
• Caracteres acentuados: Seu CSV pode ter nomes ou atributos que incluem acentos. Certifique-se de que seu arquivo esteja codificado em UTF-8 para evitar quaisquer problemas.
• O Braze ID pertence a um usuário órfão: Quando um usuário fica órfão, o usuário remanescente com o qual o órfão foi mesclado pode ainda não associar o Braze ID do usuário órfão ao perfil. Nesse caso, o Braze não encontrará um usuário para atualizar, portanto, a linha não será considerada importada.
• Fileira vazia: Há uma linha em branco no arquivo CSV. Isso pode ser verificado se você abrir o CSV em um programa editor de texto (não use o Excel ou o Sheets). Se você fizer upload do CSV com uma linha vazia, haverá uma mensagem de erro informando que há linhas com dados malformados.
• Incluindo aspas duplas ("): Esse caractere não é válido e fará com que a linha fique malformada. Em vez disso, use aspas simples (').
• Quebras de linha inconsistentes: Por exemplo, se o arquivo CSV usar \n para a primeira linha e \r\n para cada linha subsequente, a primeira linha de dados será processada como parte do cabeçalho, e esses dados não serão importados como esperado. Você pode verificar isso em um editor hexadecimal ou em um editor de texto especializado que diferencie caracteres de espaço em branco.
• Arquivo codificado incorretamente: O arquivo CSV pode incluir nomes ou atribuições que tenham acentos, mas o arquivo deve ser codificado em UTF-8 para importá-los corretamente. Outras codificações de caracteres podem funcionar em alguns casos, mas somente a UTF-8 é totalmente compatível.

Datas formatadas incorretamente

As datas que não estiverem no formato ISO-8601 não serão lidas como datetimes na importação.

String com aspas

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

Dados importados como atributo personalizado

Se uma parte dos dados padrão de usuários (como email ou first_name) for importada como um atributo personalizado, verifique as letras maiúsculas e minúsculas e o espaçamento do arquivo CSV. Por exemplo, First_name seria importado como um atributo personalizado, enquanto first_name seria corretamente importado no campo “first name” no perfil de um usuário.

Múltiplos tipos de dados

Braze espera que cada valor em uma coluna seja do mesmo tipo de dado. Os valores que não corresponderem ao tipo de dados do atributo causarão erros na segmentação.

Além disso, iniciar uma atribuição numérica com zero causará problemas porque os números que começam com zeros são considerados strings. Quando o Braze converte essa string, ela pode ser tratada como um valor octal (que usa dígitos de zero a sete), o que significa que será convertida em seu valor decimal correspondente. Por exemplo, se o valor no arquivo CSV for 0130, o perfil do Braze mostrará 88. Para evitar esse problema, use atribuições com tipos de dados string. No entanto, esse tipo de dados não está disponível na comparação de números de segmentação.

Tipos de atribuição padrão

Algumas atribuições padrão podem aceitar apenas determinados valores como válidos para atualizações de usuários. Para obter orientação, consulte Construção de seu CSV.

Espaços finais e diferenças na capitalização podem fazer com que um valor seja interpretado como inválido. Por exemplo, no arquivo CSV a seguir, somente o usuário da primeira linha (brazetest1) terá seus status de e-mail e push atualizados com êxito porque 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

O botão “Select CSV File” (Selecionar arquivo CSV) não funciona

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

• Bloqueador de pop-ups: Isso pode impedir a exibição da página. Confirme se o seu navegador está permitindo pop-ups no site do dashboard do Braze.
• Navegador desatualizado: Certifique-se de que seu navegador esteja atualizado; caso contrário, atualize-o para a versão mais recente.
• Processos em segundo plano: Feche todas as instâncias do navegador e reinicie o computador.