Visão geral
Notificações push do iOS são essenciais para impulsionar o engajamento e retenção sustentados do usuário no seu aplicativo iOS. Elas permitem que você entregue atualizações em tempo real, lembretes e mensagens personalizadas diretamente aos seus usuários, melhorando a experiência geral do usuário e a aderência do seu aplicativo. Ao integrar o SDK do OneSignal com seu aplicativo, você pode aproveitar o Apple Push Notification Service (APNS) para garantir que suas notificações sejam entregues perfeitamente em dispositivos iOS. Este guia irá orientá-lo na integração do nosso SDK ao seu aplicativo iOS.Requisitos
- macOS com Xcode 14+ (instruções de configuração usam Xcode 16.2)
- Dispositivo com iOS 12+, iPadOS 12+, ou simulador Xcode rodando iOS 16.2+
- Aplicativo e plataforma OneSignal configurados
Configure your OneSignal app and platform
Configure your OneSignal app with the platforms you support — Apple (APNs), Google (FCM), Huawei (HMS), and/or Amazon (ADM).If your organization already has a OneSignal account, ask to be invited to the Organization. Otherwise, sign up for a free account to get started.
Step-by-step setup instructions
Step-by-step setup instructions
Create or select your app
Create a new app by clicking New App/Website, or add a platform to an existing app in Settings > Push & In-App. Select the platform(s) you want to configure and click Next: Configure Your Platform.

Configure platform credentials
Enter the credentials for your platform:
- Android: Set up Firebase credentials
- iOS: p8 token (recommended) or p12 certificate
- Amazon: Generate API key
- Huawei: Authorize OneSignal
Configuração do iOS
Siga estes passos para adicionar notificações push ao seu aplicativo iOS, incluindo suporte para Badges, Confirmed Delivery e imagens.1. Adicionar Push Notifications capability ao app target
A Push Notifications capability permite que seu aplicativo registre um token push e receba notificações.- Abra o arquivo
.xcworkspacedo seu aplicativo no Xcode. - Selecione seu app target > Signing & Capabilities
- Clique em + Capability e adicione a capability Push Notifications

2. Adicionar Background Modes capability ao app target
Isso permite que seu aplicativo desperte em segundo plano quando notificações push chegarem.- Adicione a capability Background Modes
- Habilite Remote notifications

3. Adicionar app target ao App Group
App Groups permitem compartilhamento de dados entre seu aplicativo e a Notification Service Extension. Necessário para Confirmed Delivery e Badges.- Se você NÃO tem um App Group configurado
- Se você TEM um App Group
- Adicione a capability App Groups
- Na capability App Groups clique em +
- Adicione um novo container ID no formato:
group.your_bundle_id.onesignal
- Mantenha o prefixo group. e sufixo .onesignal. Substitua
your_bundle_idpelo identificador de bundle do seu aplicativo. - Por exemplo, o identificador de bundle
com.onesignal.MyApp, terá o nome de containergroup.com.onesignal.MyApp.onesignal.

4. Adicionar Notification Service Extension
A Notification Service Extension (NSE) habilita notificações ricas e análises de Confirmed Delivery.- No Xcode: File > New > Target…
- Selecione Notification Service Extension, depois Next.
- Defina o nome do produto como
OneSignalNotificationServiceExtensione pressione Finish. - Pressione Don’t Activate no prompt de Activate scheme.



Se você está usando CocoaPods, defina a versão de deployment no seu Podfile também.

5. Adicionar NSE target ao app group
Use o mesmo App Group ID que você adicionou no passo 3.- Vá para OneSignalNotificationServiceExtension > Signing & Capabilities
- Adicione App Groups
- Adicione o mesmo group ID exato

6. Atualizar código do NSE
- Navegue até a pasta OneSignalNotificationServiceExtension
- Substitua o conteúdo do arquivo
NotificationService.swiftouNotificationService.mpelo seguinte:


Configuração do SDK
Esta seção irá guiá-lo na integração dos recursos principais do OneSignal. Ao final desta seção, você terá uma integração básica com nosso SDK permitindo que você acione mensagens no aplicativo e receba notificações push.1. Adicionar SDK
Adicione nosso SDK usando o Xcode Package Dependencies Manager (Swift Package Manager) ou CocoaPods. Existem 4 bibliotecas disponíveis. Se você não quer Mensagens no aplicativo e/ou rastreamento de localização, você pode omitir esses pacotes.| Biblioteca | Target | Necessário |
|---|---|---|
| OneSignalExtension | OneSignalNotificationServiceExtension | ✅ |
| OneSignalFramework | App | ✅ |
| OneSignalInAppMessages | App | Recomendado |
| OneSignalLocation | App | Opcional |
- Xcode Package Dependencies
- CocoaPods
Navegue até File > Add Package Dependencies… e insira a URL para o repositório do OneSignal SDK:
Para mais detalhes, consulte a documentação da Apple sobre adicionar dependências de pacote.
https://github.com/OneSignal/OneSignal-XCFrameworkSelecione o pacote onesignal-xcframework e clique em Add Package.Escolha Package Products para OneSignal-XCFramework.- Importante: Adicione o OneSignalExtension ao OneSignalNotificationServiceExtension Target.
- Adicione o OneSignalFramework ao seu App Target.
- Se você planeja usar mensagens no aplicativo (recomendado) e/ou rastreamento de localização, então adicione esses pacotes ao seu App Target também.

2. Inicializar SDK
Dependendo da configuração de interface do seu Xcode, inicialize o OneSignal seguindo estas opções.- SwiftUI
- Storyboard
Se estiver usando interface SwiftUI, navegue até seu arquivo
<APP_NAME>App.swift e inicialize o OneSignal com os métodos fornecidos.Substitua YOUR_APP_ID pelo seu App ID do OneSignal encontrado no painel do OneSignal Settings > Keys & IDs. Se você não tem acesso ao aplicativo OneSignal, peça aos seus Team Members para convidá-lo.Testando a integração do OneSignal SDK
Este guia ajuda você a verificar se a integração do OneSignal SDK está funcionando corretamente testando notificações push, registro de assinatura e mensagens no aplicativo.Verificar assinaturas mobile
Inicie seu aplicativo 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.
Verifique seu painel do OneSignal
Antes de aceitar o prompt, verifique o painel do OneSignal:
- Vá para Audience > Subscriptions.
- Você deve ver uma nova entrada com o status “Never Subscribed”.

Atualize a página de Subscriptions do painel OneSignal.
O status da assinatura agora deve mostrar Subscribed.

Você criou com sucesso uma assinatura mobile.
Assinaturas mobile são criadas quando usuários abrem seu aplicativo pela primeira vez em um dispositivo ou se eles desinstalarem e reinstalarem seu aplicativo no mesmo dispositivo.
Configurar assinaturas de teste
Assinaturas de teste são úteis para testar uma notificação push antes de enviar uma mensagem.Adicionar a Test Subscriptions.
No painel, ao lado da assinatura, clique no botão Options (três pontos) e selecione Add to Test Subscriptions.

Nomeie sua assinatura.
Nomeie a assinatura para que você possa identificar facilmente seu dispositivo mais tarde na aba Test Subscriptions.
Enviar push de teste via API
Obtenha sua App API Key e App ID.
No seu painel do OneSignal, vá para Settings > Keys & IDs.
Atualize o código fornecido.
Substitua
YOUR_APP_API_KEY e YOUR_APP_ID no código abaixo pelas suas chaves reais. Este código usa o segmento Test Users que criamos anteriormente.Verifique imagens e confirmed delivery.
Se todos os passos de configuração foram concluídos com sucesso, as assinaturas de teste devem receber uma notificação com uma imagem incluída:

Imagens aparecerão pequenas na visualização de notificação recolhida. Expanda a notificação para ver a imagem completa.
Enviar uma mensagem no aplicativo
Mensagens no aplicativo permitem que você se comunique com usuários enquanto eles estão usando seu aplicativo.Feche ou coloque seu aplicativo em segundo plano no dispositivo.
Isso é porque usuários devem atender aos critérios de público de mensagens no aplicativo antes que uma nova sessão inicie. No OneSignal, uma nova sessão inicia quando o usuário abre seu aplicativo depois que ele esteve em segundo plano ou fechado por pelo menos 30 segundos. Para mais detalhes, consulte nosso guia sobre como mensagens no aplicativo são exibidas.
Crie uma mensagem no aplicativo.
- No seu painel OneSignal, navegue até Messages > In-App > New In-App.
- Encontre e selecione a mensagem Welcome.
- Defina seu Audience como o segmento Test Users que usamos anteriormente.

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

Torne a mensagem ativa.
Clique em Make Message Live para que ela esteja disponível para seus Test Users cada vez que eles abrirem o aplicativo.
Você configurou com sucesso o OneSignal SDK e aprendeu conceitos importantes como:
- Coletar Assinaturas, definir Assinaturas de teste e criar Segmentos.
- Enviar Push com imagens e Confirmed Delivery usando Segmentos e nossa API Create message.
- Enviar Mensagens no aplicativo.
Identificação de usuário
Anteriormente, demonstramos como criar Assinaturas mobile. Agora vamos expandir para identificar Usuários através de todas as suas assinaturas (incluindo push, email e SMS) usando o OneSignal SDK. Vamos cobrir External IDs, tags, assinaturas multicanal, privacidade e rastreamento de eventos para ajudá-lo a unificar e engajar usuários através de plataformas.Atribuir 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 forem identificados pelo seu aplicativo.
O OneSignal gera IDs únicos somente leitura para assinaturas (Subscription ID) e usuários (OneSignal ID).À medida que usuários baixam seu aplicativo em diferentes dispositivos, se inscrevem no seu site e/ou fornecem endereços de email e números de telefone fora do seu aplicativo, novas assinaturas serão criadas.Definir o External ID através do nosso SDK é altamente recomendado para identificar usuários através de todas as suas assinaturas, independentemente de como elas são criadas.
Adicionar tags de dados
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 do usuário). Tags alimentam Personalização de mensagens e Segmentação avançadas permitindo casos de uso mais avançados.
Defina tags com os métodos addTag e addTags do nosso SDK conforme eventos ocorrem no seu aplicativo.
Neste exemplo, o usuário alcançou o nível 6 identificável pela tag chamada current_level definida com um valor de 6.




Adicionar assinaturas de email e/ou SMS
Anteriormente vimos como nosso SDK cria assinaturas mobile para enviar mensagens push e no aplicativo. Você também pode alcançar usuários através de canais de email e SMS criando as assinaturas correspondentes.- Use o método
addEmailpara criar assinaturas de email. - Use o método
addSmspara criar assinaturas de SMS.

Melhores práticas para comunicação multicanal
- Obtenha consentimento explícito antes de adicionar assinaturas 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 os usuários possam selecionar quais canais eles preferem.
Privacidade e consentimento do usuário
Para controlar quando o OneSignal coleta dados do usuário, use os métodos de controle de consentimento do SDK:setConsentRequired(true): Previne coleta de dados até que o consentimento seja dado.setConsentGiven(true): Habilita coleta de dados uma vez que o consentimento seja concedido.
Solicitar permissões push
Em vez de chamarrequestPermission() imediatamente ao abrir o aplicativo, adote uma abordagem mais estratégica. Use uma mensagem no aplicativo para explicar o valor das notificações push antes de solicitar permissão.
Para melhores práticas e detalhes de implementação, consulte nosso guia Solicitar permissões push.
Ouvir eventos de push, usuário e mensagens no aplicativo
Use os listeners do SDK para reagir a ações do usuário e mudanças de estado. O SDK fornece vários event listeners para você se conectar. Consulte nosso guia de referência do SDK para mais detalhes.Eventos de notificação push
addClickListener(): Detecta quando uma notificação é tocada. Útil para Deep Linking.addForegroundLifecycleListener(): Controla como notificações se comportam em primeiro plano.
Mudanças de estado do usuário
addObserver()para estado do usuário: Detecta quando o External ID é definido.addPermissionObserver(): Rastreia a interação específica do usuário com o prompt de permissão push nativo.addObserver()para assinatura push: Rastreia quando o status da assinatura push muda.
Eventos de mensagens no aplicativo
addClickListener(): Manipula ações de clique em mensagens no aplicativo. Ideal para deep linking ou rastreamento de eventos.addLifecycleListener(): Rastreia o ciclo de vida completo de mensagens no aplicativo (mostradas, clicadas, dispensadas, etc.).
Desativar o method swizzling (opcional)
Por padrão, o SDK do OneSignal usa method swizzling para lidar automaticamente com os métodos de delegado de notificação push. Se seu aplicativo precisar desativar o swizzling (por exemplo, para evitar conflitos com outros SDKs ou para manter controle total sobre os métodos de delegado de notificação), você pode optar por sair viaInfo.plist.
Quando o swizzling está desativado, você deve encaminhar manualmente os métodos de delegado de notificação para o SDK do OneSignal. Todos os outros recursos do SDK (listeners, observers, mensagens in-app, outcomes, etc.) continuam funcionando normalmente.
Etapa 1. Adicionar o flag no Info.plist
Adicione o seguinte aoInfo.plist do seu aplicativo:
Etapa 2. Definir o delegado do UNUserNotificationCenter
Defina seuAppDelegate como delegado do UNUserNotificationCenter antes de chamar OneSignal.initialize. Sem isso, a exibição de notificações em primeiro plano e o tratamento de toques em notificações não funcionarão.
Etapa 3. Encaminhar métodos de delegado de notificação
Implemente os seguintes métodos no seuAppDelegate. Todos os métodos são chamados por meio de OneSignal.Notifications.
Registro de token:
OSNotification. Se não for nil, o SDK quer que a notificação seja exibida — passe suas opções de apresentação preferidas. Se for nil (por exemplo, uma pré-visualização do IAM), não passe opções de apresentação.
O listener de ciclo de vida
onWillDisplayNotification e as APIs preventDefault / display continuam funcionando com o encaminhamento manual. O SDK invoca seus listeners a partir de handleWillPresentNotificationInForegroundWithPayload.Opcional: Definir contagem de badges
Quando o swizzling está desativado, o SDK não pode interceptar alterações de badge. Use este método para definir a contagem de badges e manter o cache interno de badges do OneSignal sincronizado:Aplicativos SwiftUI
Aplicativos SwiftUI não têm umAppDelegate por padrão. Use @UIApplicationDelegateAdaptor para adicionar um e, em seguida, implemente todos os métodos de encaminhamento mostrados acima:
Swift
Referência da API
| Método | Propósito |
|---|---|
didRegisterForRemoteNotifications(_:deviceToken:) | Encaminhar o token de dispositivo APNs para o OneSignal |
handleDidFailRegisterForRemoteNotification(_:) | Encaminhar falha de registro do APNs |
receiveRemoteNotification(_:userInfo:completionHandler:) | Encaminhar notificações em segundo plano/silenciosas |
handleWillPresentNotificationInForegroundWithPayload(_:withCompletion:) | Encaminhar notificação em primeiro plano para processamento do SDK |
handleNotificationResponse(_:) | Encaminhar toque/ação de notificação para o SDK |
setBadgeCount(_:) | Definir contagem de badges e sincronizar com o cache do SDK |
Configuração avançada e capacidades
Explore mais capacidades para aprimorar sua integração:- 🔁 Migrando para o OneSignal de outro serviço
- 🌍 Rastreamento de localização
- 🔗 Deep Linking
- 🔌 Integrações
- 🧩 Mobile Service Extensions
- 🛎️ Botões de ação
- 🌐 Mensagens em vários idiomas
- 🛡️ Verificação de identidade
- 📊 Outcomes customizados
- 📲 Live Activities
Configuração e referência do Mobile SDK
Certifique-se de ter habilitado todos os recursos principais revisando o guia de Configuração de push mobile. 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.
Need help?Chat with our Support team or email
support@onesignal.comPlease include:- Details of the issue you’re experiencing and steps to reproduce if available
- Your OneSignal App ID
- The External ID or Subscription ID if applicable
- The URL to the message you tested in the OneSignal Dashboard if applicable
- Any relevant logs or error messages




