Requisitos
- Um aplicativo Expo gerenciado. Para aplicativos React Native puros, veja Configuração do SDK React Native.
- Build de desenvolvimento do Expo
- Expo SDK 53+ (React Native 0.79+) com Nova Arquitetura habilitada
- EAS CLI (documentação do EAS Build)
- App e plataforma OneSignal configurados
- 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+
- 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).Instruções de configuração passo a passo
Instruções de configuração passo a passo
Crie ou selecione seu app

Configurando seu primeiro app OneSignal, Organização e canal.
Configure credenciais da plataforma
- Android: Configure Credenciais Firebase
- iOS: Token p8 (Recomendado) ou Certificado p12
- Amazon: Gere API Key
- Huawei: Autorize OneSignal
Salve seu App ID e instale o SDK

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.react-native-onesignal ao seu projeto.
2. Configurar o plugin
Abra seuapp.json (ou app.config.js / app.config.ts). Você deve incluir as seguintes configurações.
Configurações obrigatórias
UIBackgroundModes definida como ["remote-notification"].- Defina
aps-environmentcomo"development"para testes e"production"para builds do TestFlight e App Store.
Propriedades adicionais do plugin.
Propriedades adicionais do plugin.
Opcional: desabilitar o módulo de localização
Se seu app não usaOneSignal.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.
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.
- app.config.ts
- app.json
onesignal-expo-plugin 2.6.0, você pode importar withOneSignal para ter suporte completo a TypeScript e autocompletar nas props do plugin.3. Inicializar SDK
Dependendo da sua estrutura Expo (entrada de App tradicional ou Expo Router), inicialize o OneSignal seguindo estas opções.- Traditional App Entry
- Expo Router
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.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.
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.- Continue com a configuração iOS, se aplicável.
- Ou pule para Testando a integração do OneSignal SDK.
Configuração iOS
Certifique-se de que seu app OneSignal está configurado para a plataforma iOS usando o Token p8 (Recomendado) ou Certificado p12.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
Cycle Inside... building could produce unreliable results.
Cycle Inside... building could produce unreliable results.
- Abra sua pasta
.xcworkspaceno Xcode e navegue até seu app target > Build Phases. - Você deve ter uma fase chamada “Embed Foundation Extensions” ou “Embed App Extensions”.
- Arraste e mova esta fase de build para acima de “Run Script”.
- 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.
Erro PBXGroup
Erro PBXGroup
PBXGroup tentou inicializar um objeto com ISA desconhecido PBXFileSystemSynchronizedRootGroup dos atributos: {"isa"=>"...", "exceptions"=>["//", "..."], "explicitFileTypes"=>{}, "explicitFolders"=>[], "path"=>"OneSignalNotificationServiceExtension", "sourceTree"=>"<group>"}- Encontre a pasta listada em “path” no erro
- Na barra lateral do projeto Xcode, clique com o botão direito na pasta
- Selecione Convert to Group

Erro de caminho para PBXGroup.

Converter pasta para grupo.
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.Verifique inscrições mobile
Inicie seu app em um dispositivo de teste.
requestPermission durante a inicialização.
Prompts de permissão push iOS e Android
Verifique seu 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'
Retorne ao app e toque em Allow no prompt.
Atualize a página de Subscription do dashboard OneSignal.

Dashboard mostrando inscrição com status 'Subscribed'
Configure inscrições de teste
Inscrições de teste são úteis para testar uma notificação push antes de enviar uma mensagem.Adicione a Test Users.

Adicionando um dispositivo a Test Users
Nomeie sua inscrição.
Crie um segmento de usuários de teste.
Nomeie o segmento.
Test Users (o nome é importante porque será usado depois).Adicione o filtro Test Users e clique em Create Segment.

Criando um segmento 'Test Users' com o filtro Test Users
Envie push de teste via API
Obtenha seu App API Key e App ID.
Atualize o código fornecido.
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.Execute o código.
Verifique imagens e entrega confirmada.

Notificação push com imagem no iOS e Android
Verifique por entrega confirmada.
Envie uma mensagem in-app
Mensagens in-app permitem que você se comunique com usuários enquanto eles estão usando seu app.Feche ou coloque em background seu app no dispositivo.
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
Personalize o conteúdo da mensagem se desejar.

Exemplo de personalização da mensagem Welcome in-app
Defina Trigger como 'On app open'.
Agende frequência.

Opções de agendamento de mensagem in-app
Torne a mensagem ativa.
Abra o app e veja a mensagem.

Mensagem in-app Welcome mostrada em dispositivos
- Coletar Inscrições, configurar inscrições de teste e criar Segmentos.
- Enviar Push com imagens e Entrega Confirmada usando Segmentos e nossa API Create message.
- Enviar Mensagens in-app.
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étodologin do nosso SDK cada vez que eles são identificados pelo seu app.
Adicione Tags
Tags são pares chave-valor de dados string que você pode usar para armazenar propriedades de usuário (comousername, 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"

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.- Use o método
addEmailpara criar inscrições de email. - Use o método
addSmspara criar inscrições de SMS.

Um perfil de usuário com inscrições push, email e SMS unificadas por External ID
- 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:setConsentRequired(true): Previne coleta de dados até que consentimento seja dado.setConsentGiven(true): Habilita coleta de dados uma vez que consentimento é concedido.
Solicite permissões push
Em vez de chamarrequestPermission() 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
addClickListener(): Detecte quando uma notificação é tocada. Útil para Deep Linking.addForegroundLifecycleListener(): Controle como notificações se comportam em foreground.
Mudanças de estado do usuário
addObserver()para estado do usuário: Detecte quando o External ID é definido.addPermissionObserver(): Rastreie a interação específica do usuário com o prompt de permissão push nativo.addObserver()para inscrição push: Rastreie quando o status de inscrição push muda.
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:- 🔁 Migrando para OneSignal de outro serviço
- 🌍 Rastreamento de localização
- 🔗 Deep Linking
- 🔌 Integrações
- 🧩 Mobile Service Extensions
- 🛎️ Botões de ação
- 🌐 Mensagens multilíngues
- 🛡️ Verificação de Identidade
- 📊 Custom Outcomes
- 📲 Live Activities
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.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. ChamesetConsentRequired antes de initialize.
setConsentGiven(true) assim que o usuário aceitar. Consulte Tratamento de dados pessoais para mais detalhes.Solução de problemas
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