Pular para o conteúdo principal

​
Visão Geral

Este guia orienta você através das diferentes maneiras de importar dados de usuário para o OneSignal. Seja migrando de outra plataforma ou adicionando novos assinantes, você pode importar ou atualizar Users e suas Subscriptions usando:
  • SDKs — recomendado para adicionar automaticamente novos usuários e assinaturas push.
  • Importador CSV — melhor para importação e atualização em massa de usuários.
  • API REST — ótimo para atualizações programáticas ou automatizadas.
  • Entrada Manual — ideal para adicionar ou editar usuários individuais.

A página dentro da seção Audience

​
Importação CSV

Importe ou atualize assinaturas de email e número de telefone junto com suas tags, idioma, fuso horário, país, status de assinatura (Email/SMS) e status de supressão (somente Email).

Tela de Importação CSV

​
Prepare seu CSV

Certifique-se de que seu arquivo atende aos seguintes padrões:
  • Codificação UTF-8 (sem BOM)
  • Sem caracteres não imprimíveis
  • Cabeçalhos de coluna limpos e únicos
  • Tamanho do arquivo menor que 150MB
Abra seu arquivo em um editor de texto simples como VS Code ou Sublime. Reabra com codificação UTF-8 e verifique a exibição adequada de caracteres.
Seu arquivo deve incluir pelo menos um dos seguintes:
  • external_id — Recomendado. Identifica Users em todas as Subscriptions.
  • email — Obrigatório para assinaturas de email.
  • phone_number — Obrigatório para assinaturas de SMS.
  • subscription_id — Recomendado apenas para uso ao adicionar o External ID a uma assinatura existente.
subscription_id pode ser usado como identificador para casos legados, ou onde seu backend rastreia este ID de Assinatura único. Não é recomendado ser usado como identificador para adicionar ou atualizar propriedades.
Apenas um identificador de cada tipo é permitido por linha. Para associar múltiplos emails ou números ao mesmo usuário, use linhas separadas compartilhando o mesmo external_id.
  • Incluir external_id ajuda a desduplicar usuários, suporta atualizações entre canais e habilita importações futuras.
  • Certifique-se de que o external_id seja único para cada usuário e seja o mesmo ID definido via método SDK login. Caso contrário, ele será redefinido quando o usuário abrir o aplicativo.

​
Colunas CSV disponíveis

​
external_id
Qualquer valor alfanumérico único
Veja external ID para mais informações.
​
email
Endereços de email válidos
Cria uma subscription de Email. Desduplicada se já estiver presente.
​
phone_number
Números de telefone válidos
Use formato E.164 como +15555551234. Cria uma subscription de SMS.
​
subscription_id
UUID v4 atribuído pelo OneSignal
Apenas para uso legado. Use ao rastrear IDs de assinatura do OneSignal.
​
subscribed
`yes`, `no`
Define o status de assinatura para email, phone_number e subscription_id.
​
suppressed
`true`, `false`
false remove o email das listas de supressão.
​
timezone_id
Fusos horários formatados IANA TZ
Veja IANA TZ.
​
country
Códigos ISO 3166-2 de 2 caracteres
Veja ISO 3166-2.
​
language
Códigos ISO 639-1 de 2 caracteres
Veja ISO 639-1.
​
data tags
Valores alfanuméricos
Até 1.000 tags. Use cabeçalhos de coluna como chaves. Veja Tags.

​
Importar tags de uma única coluna

Em vez de usar cabeçalhos de coluna separados para cada chave de tag, você pode definir um único cabeçalho tags, com cada linha de usuário contendo um mapa JSON de todos os pares chave-valor entre aspas. Isso é especialmente útil se você exportou anteriormente um CSV com tags e deseja reimportá-lo sem reformatação. Exemplo de cabeçalho: 
external_id,email,tags
Exemplo de linhas: As tags devem ser formatadas como um objeto JSON entre aspas. 
userA,[email protected],"{""level"":""30"",""Color"":""teal""}"
Quando importado, o OneSignal converte automaticamente cada par chave-valor em tags distintas para o registro de assinatura.

​
Use IA para verificar seu CSV antes de importar

Se você tiver erros ou dúvidas sobre a formatação do seu CSV, pode descrever o problema do CSV para uma ferramenta de IA (como Claude, ChatGPT ou similar) para limpar ou reconstruir automaticamente seu arquivo antes de importar novamente.
  • Excluindo tags
  • Formatação de tags
  • Identificar formatos inválidos
  • Formatação de número de telefone
  • Dados de outra plataforma
Exemplo de prompt de IA para excluir tags indesejadas
Quero remover todas as tags, exceto "user_name" deste CSV.

Por favor:
1. Mantenha apenas a coluna de tag "user_name".
2. Remova todas as outras colunas de tags.
3. Formate o CSV para que corresponda aos requisitos de importação do OneSignal neste documento:
   https://documentation.onesignal.com/docs/en/import

Aqui está meu CSV:
[COLAR CSV]
Sempre teste com uma amostra pequena (5-10 linhas) antes de importar milhares de registros.

​
Acessar importador CSV

  1. Vá para Audience > Import
  2. Clique em Launch CSV Importer
  3. Faça upload do seu CSV (arrastar e soltar ou usar seletor de arquivo)

​
Mapear campos

Após o upload:
  • O OneSignal mapeia automaticamente cabeçalhos para propriedades conhecidas.
  • Revise os mapeamentos antes de confirmar.

​
Atualizar propriedades

Use external_id, email, phone_number ou subscription_id para identificar o usuário que você está atualizando. Para adicionar um novo email ou número de telefone a um usuário existente, você deve usar external_id. Não use subscription_id — ele não vinculará ou mesclará assinaturas.

​
Lidar com avisos

Se o OneSignal detectar problemas de formato:
  • Corrija o CSV e reenvie (recomendado)
  • Ou desmarque a coluna afetada para pular a importação dela

​
Revisão

Na tela de Revisão:
  • Opcionalmente, crie um segmento para esta importação
  • Opcionalmente, exclua tags com valores em branco:
external_id,tag1,tag2
2349-wefh-h34a,,"tag 2 value"
Criar um segmento torna rápido e fácil enviar uma mensagem para esses usuários imediatamente. No entanto, se seu CSV já contém uma tag única, você não precisa criar um segmento aqui. Basta usar a tag que você já definiu para criar seu segmento.

Opções para criar um segmento e excluir valores de tag vazios

Após clicar em Confirm and Import, uma tela de status mostra o progresso. Você receberá um email quando a importação terminar.
A duração da importação depende do tamanho do arquivo. Adicione [email protected] aos seus contatos de email para garantir que você receba emails de conclusão.

​
Confirmação por email e solução de problemas

Quando o CSV terminar de ser enviado, você receberá um email de confirmação com os seguintes dados:
  • Registro(s) de assinatura adicionado(s)
    • O número de novas subscriptions de email e/ou SMS criadas via upload de CSV.
    • 0 significa que a lista não continha identificadores únicos de email e/ou phone_number para criar as assinaturas.
  • Registro(s) de assinatura modificado(s)
    • O número de Subscriptions onde alguns dados mudaram, como tags definidas ou outras propriedades.
    • Lembre-se de que Users podem ter múltiplas Subscriptions. Por exemplo, se você enviou uma lista de 10 External IDs e cada um estava associado a 20 assinaturas, você verá 200 registros de assinatura modificados.
  • Atualizações de assinatura ignoradas
    • O número de Subscriptions que foram ignoradas pelo motivo fornecido.
    • Se você enviou um CSV de email e/ou phone_number, essas Subscriptions provavelmente foram criadas.
    • Se o motivo for “due to being over your app’s tag limit”, você precisa remover tags e enviar novamente. Ou fazer upgrade do seu plano.
  • Não importado
    • O número de linhas que não foram atualizadas ou importadas.
    • Geralmente ocorre quando:
    1. O external_id que você definiu no CSV não existe em nenhuma assinatura no aplicativo OneSignal
    2. As assinaturas de email e/ou phone_number já existem no aplicativo OneSignal.
  • Novo segmento criado
    • O nome do segmento que você criou, se aplicável.

Exemplo de confirmação por email.

No exemplo:
  • 100 assinaturas foram criadas porque as colunas email e/ou phone_number incluíam endereços de email únicos e/ou números de telefone que atualmente não existiam no aplicativo OneSignal.
  • 37814 assinaturas foram atualizadas. Isso não é a contagem de Users. Lembre-se de que usuários podem ter múltiplas Subscriptions.
  • 621852 linhas do CSV não foram importadas. Seja porque não tinham External IDs que mapeavam para usuários no aplicativo OneSignal, ou os emails e/ou números de telefone já existiam sem dados únicos para definir.
Atualmente Segments contam apenas o número de Subscriptions inscritas. Eles não contam assinaturas não inscritas, embora seus dados tenham sido atualizados.Se a contagem do seu segmento não corresponder ao CSV, é porque o segmento não está contando as assinaturas não inscritas no momento.Isso está sendo trabalhado atualmente. A nova e melhorada segmentação estará disponível no final de 2025.
Ainda tendo problemas?Entre em contato com [email protected] e compartilhe o arquivo CSV que você enviou junto com uma captura de tela do email de confirmação. Teremos prazer em dar uma olhada!

​
Dicas comuns de solução de problemas

Os seguintes são problemas comuns que vemos com importações CSV. Também recomendamos tentar a seção Use IA para verificar seu CSV antes de importar acima se você estiver tendo problemas.

​
Limites de tags

  • Seu limite de tags do plano é por usuário. Você pode ter uma quantidade ilimitada de tags por aplicativo, mas cada usuário está sujeito ao limite do plano.
  • Exemplo: Seu limite de plano é de 20 tags por usuário.
    • Se o usuário já tiver 19 tags, você só pode adicionar mais 1 tag a esse usuário.
    • Seu aplicativo poderia ter 1000 combinações de tags diferentes, mas cada usuário só pode ter 20 por vez.
  • Recomendação:
    • Use a exportação CSV do painel para exportar o ID externo, tags, email e/ou número de telefone dos seus usuários.
    • Configure os cabeçalhos CSV com as tags que deseja excluir e importe-as primeiro.
    • Configure um segundo CSV com as tags que deseja manter e importe-as em segundo lugar.
    • Consulte a seção Importar tags de uma única coluna acima para mais detalhes.

​
Sobrescritas e exclusões de tags

Durante uma importação CSV:
  • As tags incluídas no seu CSV são sobrescritas com o valor fornecido.
  • As tags não incluídas no seu CSV permanecem inalteradas no registro do usuário.
Se uma tag ainda estiver presente após a importação, verifique se:
  • a coluna de cabeçalho contém a chave da tag.
  • a linha não contém nenhum valor.
  • você selecionou a opção “Excluir tags com valores em branco” na tela de Revisão.

​
Outras fontes de tags sendo adicionadas

Se tags excluídas reaparecerem após a importação, uma integração pode estar escrevendo-as automaticamente de volta. Fontes comuns incluem:
  • Segment
  • HubSpot
  • Journeys
  • Métodos de marcação do SDK
  • APIs personalizadas ou pipelines ETL
Revise os mapeamentos de integração e gatilhos de eventos para garantir que não estejam sobrescrevendo suas alterações CSV.
Precisa de ajuda?

​
Entrada manual

Você pode adicionar manualmente as assinaturas de email e número de telefone do usuário através do painel do OneSignal navegando para Audience > Users > Update/Import Users > Manually Add Users.

Tela de adicionar usuários manualmente

Na tela New User, inclua os dados que você deseja e selecione Create User.