Skip to main content
Usando um assistente de codificação com IA? Use este prompt para instalação orientada por IA:
Limitação do Expo Go: As notificações push não funcionam no Expo Go. Você deve criar um build de desenvolvimento para testar os recursos do OneSignal.

Requisitos

Requisitos iOS
  • macOS com Xcode 14+ (as instruções de configuração usam Xcode 16.2)
  • Dispositivo com iOS 12+, iPadOS 12+, ou simulador Xcode executando iOS 16.2+
  • CocoaPods 1.16.2+
Requisitos Android
  • Dispositivo ou emulador Android 7.0+ com Google Play Store (Services) instalado

Configure seu app e plataforma OneSignal

Configure seu app OneSignal com as plataformas que você suporta — Apple (APNs), Google (FCM), Huawei (HMS) e/ou Amazon (ADM).
Se sua organização já tem uma conta OneSignal, peça para ser convidado à Organização. Caso contrário, cadastre-se para uma conta gratuita para começar.
1

Crie ou selecione seu app

Crie um novo app clicando em New App/Website, ou adicione uma plataforma a um app existente em Settings > Push & In-App. Selecione a(s) plataforma(s) que você quer configurar e clique em Next: Configure Your Platform.
Dashboard do OneSignal mostrando o fluxo de configuração de novo app com nome da organização, nome do app e seleção de canal

Configurando seu primeiro app OneSignal, Organização e canal.

2

Configure credenciais da plataforma

Insira as credenciais para sua plataforma:Clique em Save & Continue após inserir suas credenciais.
3

Salve seu App ID e instale o SDK

Seu App ID é exibido na tela final. Copie e salve-o — você precisa dele ao inicializar o SDK. Selecione sua plataforma de SDK e siga o guia de configuração.
Dashboard do OneSignal mostrando o App ID e a opção de convite de equipe após a configuração

Salve seu App ID e convide membros adicionais da equipe.


Configuração do SDK

1. Adicionar SDK

Instale o plugin OneSignal Expo usando a Expo CLI.
npm
Adicione o pacote react-native-onesignal ao seu projeto.

2. Configurar o plugin

Abra seu app.json (ou app.config.js / app.config.ts). Você deve incluir as seguintes configurações. Configurações obrigatórias
string
obrigatório
O identificador de pacote do seu app. Deve corresponder à autenticação p8 ou p12 configurada no seu app OneSignal.
object
obrigatório
Deve incluir a chave UIBackgroundModes definida como ["remote-notification"].
object
obrigatório
Entitlements do iOS necessários para notificações push.
  • Defina aps-environment como "development" para testes e "production" para builds do TestFlight e App Store.
Certifique-se de adicionar o plugin [onesignal-expo-plugin] na frente do array de plugins. Ele deve ser o primeiro plugin no array. Fazer isso evitará o erro OneSignal/OneSignal.h file not found.

Opcional: desabilitar o módulo de localização

Se seu app não usa OneSignal.Location, defina disableLocation como true nas props do plugin Expo do OneSignal. Esta opção requer react-native-onesignal 5.5.1 ou posterior. O plugin configura a resolução de dependências nativas para que react-native-onesignal exclua o módulo de localização. No iOS, o plugin grava a configuração de ambiente do Podfile usada durante a resolução do CocoaPods. No Android, o plugin grava onesignal.disableLocation=true nas propriedades Gradle geradas.
Se o Podfile do iOS gerado declarar explicitamente OneSignalXCFramework em um target de Notification Service Extension ou de widget de Live Activity, use uma subespecificação modular como OneSignalXCFramework/OneSignal ou OneSignalXCFramework/OneSignalLiveActivities. O pod 'OneSignalXCFramework' agregado resolve OneSignalComplete e inclui localização. Após um prebuild limpo, verifique se nem OneSignalComplete nem OneSignalLocation aparecem em ios/Podfile.lock.
A partir do onesignal-expo-plugin 2.6.0, você pode importar withOneSignal para ter suporte completo a TypeScript e autocompletar nas props do plugin.
app.config.ts

3. Inicializar SDK

Dependendo da sua estrutura Expo (entrada de App tradicional ou Expo Router), inicialize o OneSignal seguindo estas opções.
No seu arquivo App.tsx ou App.js, inicialize o OneSignal com os métodos fornecidos.Substitua YOUR_APP_ID pelo ID do seu App OneSignal encontrado no painel OneSignal em Settings > Keys & IDs.
Se você não tem acesso ao app OneSignal, peça aos seus Membros da Equipe para convidá-lo.
App.tsx
Listeners reutilizáveis com useCallback Se o seu listener precisar acessar props ou state, defina-o fora do useEffect com useCallback para que a mesma referência seja usada ao adicionar e remover. Passar referências de função diferentes para addEventListener e removeEventListener não tem efeito — o listener não é removido e pode disparar depois que o componente é desmontado.
Revise nosso repositório GitHub do OneSignal Expo Plugin para opções de configuração adicionais, instruções de configuração mais complexas ou abra um issue. Nossos SDKs são open source e aceitamos PRs!

Configuração Android

Certifique-se de que seu app OneSignal está configurado para a plataforma Android usando suas credenciais Firebase. Configure seus ícones de notificação para corresponder à marca do seu app. O ícone pequeno é obrigatório. Se você pulá-lo, as notificações exibem um ícone de sino padrão. Build para Android Neste ponto, você deve ser capaz de fazer build e executar seu app em um dispositivo Android físico ou emulador sem problemas.
Após confirmar que seu build Android funciona:

Configuração iOS

Certifique-se de que seu app OneSignal está configurado para a plataforma iOS usando o Token p8 (Recomendado) ou Certificado p12.
Isso deve usar as mesmas credenciais configuradas na sua configuração EAS.

Build para iOS

Agora você deve ser capaz de fazer build e executar seu app em um dispositivo iOS real ou simulador iOS (16.2+).

Erros comuns de build do iOS

Você pode ver esse erro ao fazer build com Xcode 15+, devido a uma mudança de configuração padrão que afeta sistemas multiplataforma.
  1. Abra sua pasta .xcworkspace no Xcode e navegue até seu app target > Build Phases.
  2. Você deve ter uma fase chamada “Embed Foundation Extensions” ou “Embed App Extensions”.
  3. Arraste e mova esta fase de build para acima de “Run Script”.
  4. Faça o build e execute seu app. O erro deve ser resolvido.

Ordem correta das Build Phases no Xcode.

Desmarque Copy only when installing.

RuntimeError - PBXGroup tentou inicializar um objeto com ISA desconhecido PBXFileSystemSynchronizedRootGroup dos atributos: {"isa"=>"...", "exceptions"=>["//", "..."], "explicitFileTypes"=>{}, "explicitFolders"=>[], "path"=>"OneSignalNotificationServiceExtension", "sourceTree"=>"<group>"}
Correção:
  1. Encontre a pasta listada em “path” no erro
  2. Na barra lateral do projeto Xcode, clique com o botão direito na pasta
  3. Selecione Convert to Group

Erro de caminho para PBXGroup.


Converter pasta para grupo.

Depois de confirmar que seu build do iOS funciona, continue com Testando a integração do SDK OneSignal.

Testando a integração do OneSignal SDK

Este guia ajuda você a verificar se sua integração do OneSignal SDK está funcionando corretamente testando notificações push, registro de inscrição e mensagens in-app.
Se você está testando com um emulador Android, ele deve iniciar com um cold boot.
  1. Vá para Device Manager no Android Studio.
  2. Selecione seu dispositivo emulador e clique em Edit.
  3. Vá para Additional Settings ou More.
  4. Defina a Boot option para Cold Boot.
  5. Salve as alterações e reinicie o emulador.

Verifique inscrições mobile

1

Inicie seu app em um dispositivo de teste.

O prompt de permissão push nativo deve aparecer automaticamente se você adicionou o método requestPermission durante a inicialização.

Prompts de permissão push iOS e Android

2

Verifique seu dashboard OneSignal

Antes de aceitar o prompt, verifique o dashboard OneSignal:
  • Vá para Audience > Subscriptions.
  • Você deve ver uma nova entrada com o status “Never Subscribed”.

Dashboard mostrando inscrição com status 'Never Subscribed'

3

Retorne ao app e toque em Allow no prompt.

4

Atualize a página de Subscription do dashboard OneSignal.

O status da inscrição deve agora mostrar Subscribed.

Dashboard mostrando inscrição com status 'Subscribed'

Você criou com sucesso uma inscrição mobile. Inscrições mobile são criadas quando usuários abrem seu app pela primeira vez em um dispositivo ou se eles desinstalam e reinstalam seu app no mesmo dispositivo.

Configure inscrições de teste

Inscrições de teste são úteis para testar uma notificação push antes de enviar uma mensagem.
1

Adicione a Test Users.

No dashboard, próximo à inscrição, clique no botão Options (três pontos) e selecione Add to Test Users.

Adicionando um dispositivo a Test Users

2

Nomeie sua inscrição.

Nomeie a inscrição para que você possa identificar facilmente seu dispositivo depois na aba Test Users.
3

Crie um segmento de usuários de teste.

Vá para Audience > Segments > New Segment.
4

Nomeie o segmento.

Nomeie o segmento Test Users (o nome é importante porque será usado depois).
5

Adicione o filtro Test Users e clique em Create Segment.

Criando um segmento 'Test Users' com o filtro Test Users

Você criou com sucesso um segmento de usuários de teste. Agora podemos testar enviar mensagens para este dispositivo individual e grupos de usuários de teste.

Envie push de teste via API

1

Obtenha seu App API Key e App ID.

No seu dashboard OneSignal, vá para Settings > Keys & IDs.
2

Atualize o código fornecido.

Substitua YOUR_APP_API_KEY e YOUR_APP_ID no código abaixo com suas chaves reais. Este código usa o segmento Test Users que criamos anteriormente.
3

Execute o código.

Execute o código no seu terminal.
4

Verifique imagens e entrega confirmada.

Se todos os passos de configuração foram completados com sucesso, as inscrições de teste devem receber uma notificação com uma imagem incluída:

Notificação push com imagem no iOS e Android

Imagens aparecerão pequenas na visualização de notificação recolhida. Expanda a notificação para ver a imagem completa.
5

Verifique por entrega confirmada.

No seu dashboard, vá para Delivery > Sent Messages, depois clique na mensagem para ver as estatísticas.Você deve ver a estatística confirmed, significando que o dispositivo recebeu o push.
Você enviou com sucesso uma notificação via nossa API para um segmento.
  • Não recebeu imagem? Sua Notification Service Extension pode estar faltando.
  • Sem entrega confirmada? Revise o guia de solução de problemas aqui.
  • Tendo problemas? Copie e cole a requisição da api e um log do início ao fim do lançamento do app em um arquivo .txt. Depois compartilhe ambos com support@onesignal.com.

Envie uma mensagem in-app

Mensagens in-app permitem que você se comunique com usuários enquanto eles estão usando seu app.
1

Feche ou coloque em background seu app no dispositivo.

Isso é porque usuários devem atender aos critérios de público in-app antes que uma nova sessão inicie. No OneSignal, uma nova sessão inicia quando o usuário abre seu app depois de ter estado em background ou fechado por pelo menos 30 segundos. Para mais detalhes, veja nosso guia sobre como mensagens in-app são exibidas.
2

Crie uma mensagem in-app.

  • No seu dashboard OneSignal, navegue para Messages > In-App > New In-App.
  • Encontre e selecione a mensagem Welcome.
  • Defina seu Público como o segmento Test Users que usamos anteriormente.

Direcionando o segmento 'Test Users' com uma mensagem in-app

3

Personalize o conteúdo da mensagem se desejar.

Exemplo de personalização da mensagem Welcome in-app

4

Defina Trigger como 'On app open'.

5

Agende frequência.

Em Schedule > How often do you want to show this message? selecione Every time trigger conditions are satisfied.

Opções de agendamento de mensagem in-app

6

Torne a mensagem ativa.

Clique em Make Message Live para que fique disponível para seus Test Users cada vez que eles abrem o app.
7

Abra o app e veja a mensagem.

Depois que a mensagem in-app estiver ativa, abra seu app. Você deve vê-la exibida:

Mensagem in-app Welcome mostrada em dispositivos

Não está vendo a mensagem?
  • Inicie uma nova sessão
    • Você deve fechar ou colocar em background o app por pelo menos 30 segundos antes de reabrir. Isso garante que uma nova sessão seja iniciada.
    • Para mais, veja como mensagens in-app são exibidas.
  • Ainda no segmento Test Users?
    • Se você reinstalou ou trocou de dispositivo, adicione novamente o dispositivo a Test Users e confirme que ele faz parte do segmento Test Users.
  • Tendo problemas?
    • Siga Obtendo um Debug Log enquanto reproduz os passos acima. Isso gerará logging adicional que você pode compartilhar com support@onesignal.com e nós ajudaremos a investigar o que está acontecendo.
Você configurou com sucesso o OneSignal SDK e aprendeu conceitos importantes como:Continue com este guia para identificar usuários no seu app e configurar recursos adicionais.

Identificação de usuário

Anteriormente, demonstramos como criar Inscrições móveis. Agora vamos expandir para identificar Usuários através de todas as suas inscrições (incluindo push, email e SMS) usando o OneSignal SDK. Cobriremos External IDs, tags, inscrições multicanal, privacidade e rastreamento de eventos para ajudá-lo a unificar e engajar usuários através de plataformas.

Atribua External ID

Use um External ID para identificar usuários consistentemente através de dispositivos, endereços de email e números de telefone usando o identificador de usuário do seu backend. Isso garante que suas mensagens permaneçam unificadas através de canais e sistemas de terceiros (especialmente importante para Integrações). Defina o External ID com o método login do nosso SDK cada vez que eles são identificados pelo seu app.
OneSignal gera IDs únicos somente leitura para inscrições (Subscription ID) e usuários (OneSignal ID).À medida que usuários baixam seu app em diferentes dispositivos, se inscrevem no seu website e/ou fornecem endereços de email e números de telefone fora do seu app, novas inscrições serão criadas.Definir o External ID via nosso SDK é altamente recomendado para identificar usuários através de todas as suas inscrições, independentemente de como elas são criadas.

Adicione Tags

Tags são pares chave-valor de dados string que você pode usar para armazenar propriedades de usuário (como username, role ou preferências) e eventos (como purchase_date, game_level ou interações de usuário). Tags potencializam Personalização de Mensagem avançada e Segmentação permitindo casos de uso mais avançados. Defina tags com os métodos addTag e addTags do nosso SDK conforme eventos ocorrem no seu app. Neste exemplo, o usuário alcançou o nível 6 identificável pela tag chamada current_level definida com um valor de 6.

Um perfil de usuário no OneSignal com uma tag chamada "current_level" definida como "6"

Podemos criar um segmento de usuários que têm um nível entre 5 e 10, e usar isso para enviar mensagens direcionadas e personalizadas:

Editor de segmento mostrando um segmento direcionado a usuários com um valor current_level maior que 4 e menor que 10


Captura de tela mostrando uma notificação push direcionada ao segmento Nível 5-10 com uma mensagem personalizada


A notificação push é recebida em um dispositivo iOS e Android com o conteúdo personalizado

Adicione inscrições de email e/ou SMS

Anteriormente vimos como nosso SDK cria inscrições móveis para enviar push e mensagens in-app. Você também pode alcançar usuários através de canais de email e SMS criando as inscrições correspondentes. Se o endereço de email e/ou número de telefone já existem no app OneSignal, o SDK adicionará ao usuário existente, não criará duplicatas. Você pode visualizar usuários unificados via Audience > Users no dashboard ou com a API View user.

Um perfil de usuário com inscrições push, email e SMS unificadas por External ID

Melhores práticas para comunicação multicanal
  • Obtenha consentimento explícito antes de adicionar inscrições de email ou SMS.
  • Explique os benefícios de cada canal de comunicação aos usuários.
  • Forneça preferências de canal para que usuários possam selecionar quais canais eles preferem.

Privacidade e consentimento do usuário

Para controlar quando OneSignal coleta dados de usuário, use os métodos de controle de consentimento do SDK: Veja nossos documentos de Privacidade e segurança para mais sobre:

Solicite permissões push

Em vez de chamar requestPermission() imediatamente ao abrir o app, adote uma abordagem mais estratégica. Use uma mensagem in-app para explicar o valor das notificações push antes de solicitar permissão. Para melhores práticas e detalhes de implementação, veja nosso guia Solicite permissões push.

Escute eventos de push, usuário e in-app

Use listeners do SDK para reagir a ações de usuário e mudanças de estado. O SDK fornece vários event listeners para você conectar. Veja nosso guia de referência do SDK para mais detalhes.

Eventos de notificação push

Para personalização completa, veja Mobile Service Extensions.

Mudanças de estado do usuário

Eventos de mensagem in-app

  • addClickListener(): Lide com ações de clique in-app. Ideal para deep linking ou rastreamento de eventos.
  • addLifecycleListener(): Rastreie o ciclo de vida completo de mensagens in-app (exibida, clicada, descartada, etc.).

Configuração avançada e capacidades

Explore mais capacidades para melhorar sua integração:

Configuração e referência do Mobile SDK

Certifique-se de que você habilitou todos os recursos principais revisando o guia Configuração de mobile push. Para detalhes completos sobre métodos disponíveis e opções de configuração, visite a referência do Mobile SDK.
Parabéns! Você completou com sucesso o guia de configuração do Mobile SDK.


Privacidade e consentimento do usuário

Se seu app exige o consentimento do usuário antes de coletar dados (por exemplo, para conformidade com o GDPR), você pode atrasar a coleta de dados do OneSignal até que o consentimento seja concedido. Chame setConsentRequired antes de initialize.
Quando o consentimento é exigido mas ainda não foi dado, o SDK é inicializado mas não envia nenhum dado ao OneSignal. Chame setConsentGiven(true) assim que o usuário aceitar. Consulte Tratamento de dados pessoais para mais detalhes.

Solução de problemas

Precisa de ajuda?Converse com nossa equipe de Suporte ou envie email para support@onesignal.comPor favor inclua:
  • Detalhes do problema que você está enfrentando e passos para reproduzir se disponível
  • Seu OneSignal App ID
  • O External ID ou Subscription ID se aplicável
  • A URL para a mensagem que você testou no Dashboard OneSignal se aplicável
  • Quaisquer logs ou mensagens de erro relevantes
Estamos felizes em ajudar!