Pular para o conteúdo principal

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.
1

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.
OneSignal dashboard showing the new app setup flow with Organization name, app name, and channel selection

Setting up your first OneSignal app, Organization, and channel.

2

Configure platform credentials

Enter the credentials for your platform:Click Save & Continue after entering your credentials.
3

Save your App ID and install the SDK

Your App ID is displayed on the final screen. Copy and save it — you need it when initializing the SDK. Select your SDK platform, then follow the setup guide.
OneSignal dashboard showing the App ID and team invite option after setup

Save your App ID and invite additional team members.


Configuração do iOS

Siga estes passos para adicionar notificações push ao seu aplicativo iOS, incluindo suporte para Badges, Confirmed receipt 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.
  1. Abra o arquivo .xcworkspace do seu aplicativo no Xcode.
  2. Selecione seu app target > Signing & Capabilities
  3. Clique em + Capability e adicione a capability Push Notifications

O app target recebe 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.
  1. Adicione a capability Background Modes
  2. Habilite Remote notifications

O app target recebe o modo de execução em segundo plano 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 receipt e Badges.
  1. Adicione a capability App Groups
  2. Na capability App Groups clique em +
  3. Adicione um novo container ID no formato: group.your_bundle_id.onesignal
  • Mantenha o prefixo group. e sufixo .onesignal. Substitua your_bundle_id pelo identificador de bundle do seu aplicativo.
  • Por exemplo, o identificador de bundle com.onesignal.MyApp, terá o nome de container group.com.onesignal.MyApp.onesignal.

O app target faz parte do App Group.

O nome do seu App Group deve corresponder exatamente à ortografia e capitalização do seu bundle ID em todos os targets.

4. Adicionar Notification Service Extension

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

Selecione o target Notification Service Extension.

Nomeie a Notification Service Extension.

Cancele a ativação para continuar depurando seu app target.

Defina o Minimum Deployment Target do OneSignalNotificationServiceExtension para corresponder ao seu aplicativo principal (iOS 15+ recomendado).
Se você está usando CocoaPods, defina a versão de deployment no seu Podfile também.

Defina o mesmo deployment target do aplicativo principal.

5. Adicionar NSE target ao app group

Use o mesmo App Group ID que você adicionou no passo 3.
  1. Vá para OneSignalNotificationServiceExtension > Signing & Capabilities
  2. Adicione App Groups
  3. Adicione o mesmo group ID exato
Se você está usando um nome de App Group customizado e não group.your_bundle_id.onesignal, então certifique-se de adicionar seu App Group ID ao Info.plist tanto do App Target quanto do OneSignalNotificationServiceExtension Target! Veja o passo 3 para mais informações.

O NSE agora pertence ao mesmo app group do seu app target.

6. Atualizar código do NSE

  1. Navegue até a pasta OneSignalNotificationServiceExtension
  2. Substitua o conteúdo do arquivo NotificationService.swift ou NotificationService.m pelo seguinte:

Navegue até seu arquivo NotificationService.

Você deve ver um erro porque o pacote OneSignal não está instalado. Isso será resolvido no próximo passo.

Este arquivo mostra um erro até você instalar o pacote no próximo passo.


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.
Navegue até File > Add Package Dependencies… e insira a URL para o repositório do OneSignal SDK: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.

Se seu aplicativo não requer rastreamento de localização, você pode remover o pacote conforme mostrado neste exemplo.

Para mais detalhes, consulte a documentação da Apple sobre adicionar dependências de pacote.

2. Inicializar SDK

Dependendo da configuração de interface do seu Xcode, inicialize o OneSignal seguindo estas opções.
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

1

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.

Prompts de permissão push do iOS e Android

2

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”.

Painel mostrando assinatura com status 'Never Subscribed'

3

Retorne ao aplicativo e toque em Allow no prompt.

4

Atualize a página de Subscriptions do painel OneSignal.

O status da assinatura agora deve mostrar Subscribed.

Painel mostrando assinatura com status '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.
1

Adicionar a Test Users.

No painel, ao lado da assinatura, clique no botão Options (três pontos) e selecione Add to Test Users.

Adicionando um dispositivo a Test Users

2

Nomeie sua assinatura.

Nomeie a assinatura para que você possa identificar facilmente seu dispositivo mais tarde 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 mais tarde).
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 o envio de mensagens para este dispositivo individual e grupos de usuários de teste.

Enviar push de teste via API

1

Obtenha sua App API Key e App ID.

No seu painel do 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 pelas 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 confirmed receipt.

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:

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 confirmed receipt.

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

Enviar uma mensagem no aplicativo

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

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.
2

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.

Segmentando o segmento 'Test Users' com uma mensagem no aplicativo

3

Personalize o conteúdo da mensagem se desejar.

Exemplo de personalização da mensagem Welcome no aplicativo

4

Defina Trigger como 'On app open'.

5

Agende a 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 no aplicativo

6

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

Abra o aplicativo e veja a mensagem.

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

Mensagem Welcome no aplicativo mostrada em dispositivos

Não está vendo a mensagem?
  • Inicie uma nova sessão
    • Você deve fechar ou colocar o aplicativo em segundo plano por pelo menos 30 segundos antes de reabrir. Isso garante que uma nova sessão seja iniciada.
    • Para mais informações, consulte como mensagens no aplicativo são exibidas.
  • Ainda no segmento Test Users?
    • Se você reinstalou ou trocou de dispositivo, adicione novamente o dispositivo às 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 aplicativo e configurar recursos adicionais.

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étodo login 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 (como username, 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.

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 direcionando usuários com um valor de current_level maior que 4 e menor que 10


Captura de tela mostrando uma notificação push direcionando o segmento Level 5-10 com uma mensagem personalizada


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

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. Se o endereço de email e/ou número de telefone já existir no aplicativo OneSignal, o SDK irá adicioná-lo ao usuário existente, não criará duplicatas. Você pode visualizar usuários unificados através de Audience > Users no painel ou com a API View user.

Um perfil de usuário com assinaturas push, email e SMS unificadas por External ID

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: Consulte nossos documentos de Privacidade & segurança para mais sobre:

Solicitar permissões push

Em vez de chamar requestPermission() 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

Para customização completa, consulte Mobile Service Extensions.

Mudanças de estado do usuário

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 via Info.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 ao Info.plist do seu aplicativo:
Quando o SDK detecta esse flag, ele ignora todo o method swizzling na inicialização e registra um aviso lembrando você de implementar o encaminhamento manual.

Etapa 2. Definir o delegado do UNUserNotificationCenter

Defina seu AppDelegate 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 seu AppDelegate. Todos os métodos são chamados por meio de OneSignal.Notifications. Registro de token:
Notificações em segundo plano / silenciosas:
Exibição de notificações em primeiro plano: O SDK chama seu completion block com um objeto 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.
Toque / ação na notificação:

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 um AppDelegate 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


Configuração avançada e capacidades

Explore mais capacidades para aprimorar sua integração:

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
We’re happy to help!