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.

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.

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.

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.

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

​

2. Adicionar Background Modes capability ao app target

1. Adicione a capability Background Modes
2. Habilite 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 nome do seu App Group deve corresponder exatamente à ortografia e capitalização do seu bundle ID em todos os targets.

1. Abra o Info.plist do seu App Target e OneSignalNotificationServiceExtension Target
2. Adicione uma nova propriedade ao Info.plist para ambos os targets:

• Key: OneSignal_app_groups_key
• Value: Nome do seu App Group existente (ex.: group.your-custom-group-id)

XML

Copiar

Perguntar à IA

<key>OneSignal_app_groups_key</key>
<string>group.your-custom-group-id</string>

Certifique-se de atualizar o OneSignal_app_groups_key em ambos o App Target e o Info.plist do OneSignalNotificationServiceExtension Target!

​

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.

​

5. Adicionar NSE target ao app group

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

​

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:

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

​

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

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

Requisitos: CocoaPods 1.16.2+ (Instruções de configuração usam CocoaPods 1.16.2).Abra seu Podfile e adicione o seguinte:

Podfile

Copiar

Perguntar à IA

  # If platform is uncommented, set to the same value as your minimum deployment target in Xcode
  # platform :ios, '15.0'

  target 'your_project_name' do
    pod 'OneSignal/OneSignal', '>= 5.2.9', '< 6.0'
    # If your app does not use In-App messages, you can remove this:
    pod 'OneSignal/OneSignalInAppMessages', '>= 5.2.9', '< 6.0'
    # If your app does not use CoreLocation, you can remove this:
    pod 'OneSignal/OneSignalLocation', '>= 5.2.9', '< 6.0'
    # Your other pods here
  end

  target 'OneSignalNotificationServiceExtension' do
    pod 'OneSignal/OneSignal', '>= 5.2.9', '< 6.0'
  end

Adicione as dependências ao seu main app target e OneSignalNotificationServiceExtension target. Se platform estiver descomentado, certifique-se de que é o mesmo valor do minimum deployment target no Xcode.Execute o seguinte comando para baixar o pod do OneSignal iOS SDK e adicioná-lo ao seu projeto:pod repo update && pod installUma vez que a instalação estiver completa, certifique-se de abrir o arquivo XCWorkspace nomeado após seu projeto (ex.: <project-name>.xcworkspace)

Ao usar o pod do OneSignal iOS SDK, você deve usar exclusivamente o arquivo .xcworkspace para abrir o projeto.

Você pode encontrar os seguintes erros, aqui está como você pode resolvê-los.

ArgumentError - \[Xcodeproj] Unable to find compatibility version string for object version `70`.

CocoaPods depende da gem Ruby xcodeproj para ler seus arquivos de projeto Xcode. Até agora, o lançamento mais recente do xcodeproj não reconhece object version 70, que foi introduzida pelo Xcode 16. Então quando CocoaPods tenta abrir seu arquivo .xcodeproj, ele falha com este erro.

1. Feche o Xcode.
2. Navegue até o arquivo ios/<your-app>.xcodeproj/project.pbxproj do seu projeto.
3. Altere esta linha: objectVersion = 70;
4. Substitua por: objectVersion = 55;
5. Salve, feche e execute novamente cd ios pod install cd ..

​

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

//AppDelegate.swift
import UIKit
import OneSignalFramework

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions:
[UIApplication.LaunchOptionsKey: Any]?) -> 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
}

// Conteúdo restante da sua classe AppDelegate...
}

​

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.

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

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.

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.

2

Nomeie sua assinatura.

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

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.

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.

Copiar

Perguntar à IA

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:

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.

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

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 [email protected].

​

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.

3

Personalize o conteúdo da mensagem se desejar.

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.

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:

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 [email protected] e nós ajudaremos a investigar o que está acontecendo.

​

Identificação de usuário

​

Atribuir External ID

​

Adicionar tags de dados

​

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.

​

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