Configuração do SDK iOS

​

Visão geral

​

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

Step-by-step instructions for configuring your OneSignal app.

You can manage multiple platforms (iOS, Android, Huawei, Amazon, Web) under a single OneSignal app.

1

Create or select your app

• To add platforms to an existing app, go to Settings > Push & In-App in the OneSignal dashboard.
• To start fresh, click New App/Website and follow the prompts.

Example shows creating a new app.

2

Set up and activate a platform

• Choose a clear and recognizable name for your app and organization.
• Select the platform(s) you want to configure (iOS, Android, etc.).
• Click Next: Configure Your Platform.

Example setting up your first OneSignal app, org, and channel.

3

Configure platform credentials

Follow the prompts based on your platforms:

• Android: Set up Firebase Credentials
• iOS: p8 Token (Recommended) or p12 Certificate
• Amazon: Generate API Key
• Huawei: Authorize OneSignal

Click Save & Continue after entering your credentials.

4

Choose target SDK

Select the SDK that matches your development platform (e.g., iOS, Android, React Native, Unity), then click Save & Continue.

Select which SDK you are using to be navigated to the docs.

5

Install SDK and save your App ID

Once your platform is configured, your OneSignal App ID will be displayed. Copy and save this ID—you’ll need it when installing and initializing the SDK.If collaborating with others, use the Invite button to add developers or teammates, then click Done to complete setup.

Save your App ID and invite additional team members.

Once complete, follow the SDK installation guide for your selected platform to finish integrating OneSignal.

​

Configuração do iOS

​

1. Adicionar Push Notifications capability ao app target

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

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

• Se você NÃO tem um App Group configurado
• Se você TEM um App Group

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

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 mesmo deployment target do aplicativo principal.

​

5. Adicionar NSE target ao app group

1. Vá para OneSignalNotificationServiceExtension > Signing & Capabilities
2. Adicione App Groups
3. Adicione o mesmo group ID exato

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.

import UserNotifications
import OneSignalExtension

class NotificationService: UNNotificationServiceExtension {
    var contentHandler: ((UNNotificationContent) -> Void)?
    var receivedRequest: UNNotificationRequest!
    var bestAttemptContent: UNMutableNotificationContent?

    // Note this extension only runs when `mutable_content` is set
    // Setting an attachment or action buttons automatically sets the property to true
    override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
        self.receivedRequest = request
        self.contentHandler = contentHandler
        self.bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)

        if let bestAttemptContent = bestAttemptContent {
            // DEBUGGING: Uncomment the 2 lines below to check this extension is executing
//            print("Running NotificationServiceExtension")
//            bestAttemptContent.body = "[Modified] " + bestAttemptContent.body

            OneSignalExtension.didReceiveNotificationExtensionRequest(self.receivedRequest, with: bestAttemptContent, withContentHandler: self.contentHandler)
        }
    }

    override func serviceExtensionTimeWillExpire() {
        // Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.
        if let contentHandler = contentHandler, let bestAttemptContent =  bestAttemptContent {
            OneSignalExtension.serviceExtensionTimeWillExpireRequest(self.receivedRequest, with: self.bestAttemptContent)
            contentHandler(bestAttemptContent)
        }
    }
}

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

​

Configuração do SDK

​

1. Adicionar SDK

• Xcode Package Dependencies
• CocoaPods

Navegue até File > Add Package Dependencies… e insira a URL para o repositório do OneSignal iOS SDK:https://github.com/OneSignal/OneSignal-iOS-SDKSelecione o pacote onesignal-ios-sdk e clique em Add Package.Escolha Package Products para OneSignal-iOS-SDK.

• 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

import SwiftUI
import OneSignalFramework

@main
struct YOURAPP_NAME: App {
  //Connect the SwiftUI app to the UIKit app delegate
    @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

class AppDelegate: NSObject, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {

       // Habilite log detalhado para debugging (remova em produção)
       OneSignal.Debug.setLogLevel(.LL_VERBOSE)
       // Inicialize com seu OneSignal App ID
       OneSignal.initialize("YOUR_APP_ID", withLaunchOptions: launchOptions)
       // Use este método para solicitar notificações push.
       // Recomendamos remover este método após testes e, em vez disso, usar mensagens no aplicativo para solicitar permissão de notificação.
       OneSignal.Notifications.requestPermission({ accepted in
         print("User accepted notifications: \(accepted)")
       }, fallbackToSettings: false)

       return true
    }
}

​

Testando a integração do OneSignal SDK

​

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

1

Adicionar a Test Subscriptions.

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

Adicionando um dispositivo a Test Subscriptions

2

Nomeie sua assinatura.

Nomeie a assinatura para que você possa identificar facilmente seu dispositivo mais tarde na aba Test Subscriptions.

Painel mostrando o campo 'Name your subscription'

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.

Copy

Ask AI

curl -X \
POST --url 'https://api.onesignal.com/notifications' \
 --header 'content-type: application/json; charset=utf-8' \
 --header 'authorization: Key YOUR_APP_API_KEY' \
 --data \
 '{
  "app_id": "YOUR_APP_ID",
  "target_channel": "push",
  "name": "Testing basic setup",
  "headings": {
  	"en": "👋"
  },
  "contents": {
    "en": "Hello world!"
  },
  "included_segments": [
    "Test Users"
  ],
  "ios_attachments": {
    "onesignal_logo": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
  },
  "big_picture": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
}'

3

Execute o código.

Execute o código no seu terminal.

4

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:

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

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.

Estatísticas de entrega mostrando confirmed delivery

Se você está em um plano Professional ou superior, role até Audience Activity para ver confirmação em nível de assinatura:

Confirmed delivery no nível do dispositivo em Audience Activity

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 delivery? 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

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

​

Identificação de usuário

​

Atribuir External ID

​

Adicionar tags de dados

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

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

• Use o método addEmail para criar assinaturas de email.
• Use o método addSms para criar assinaturas de SMS.

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

​

Privacidade e consentimento do usuário

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

• Dados coletados pelo SDK
• Manipulação de dados pessoais

​

Solicitar permissões push

​

Ouvir eventos de push, usuário e mensagens no aplicativo

​

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

​

Configuração avançada e capacidades

• 🔁 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