> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuração do SDK iOS
> Como adicionar notificações push e mensagens no aplicativo ao seu aplicativo iOS com o OneSignal.
export const SdkReleasesIframe = ({sdkFilter = undefined, viewMode = undefined, height, ...frameProps}) => {
const baseUrl = 'https://onesignal.github.io/sdk-releases';
const buildUrl = (theme, sdkFilter, viewMode) => {
const url = new URL(baseUrl);
const params = new URLSearchParams();
if (theme) {
params.set('theme', theme);
}
if (sdkFilter) {
params.set('sdk', sdkFilter);
}
if (viewMode) {
params.set('viewMode', viewMode);
}
if (params.toString()) {
url.search = params.toString();
}
return url.toString();
};
const detectTheme = () => {
if (document.documentElement.classList.contains('dark')) {
return 'dark';
}
return 'light';
};
const [theme, setTheme] = useState('light');
const [iframeSrc, setIframeSrc] = useState(() => {
const initialTheme = detectTheme();
return buildUrl(initialTheme, sdkFilter, viewMode);
});
useEffect(() => {
const currentTheme = detectTheme();
setTheme(currentTheme);
setIframeSrc(buildUrl(currentTheme, sdkFilter, viewMode));
const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
const handleThemeChange = () => {
const newTheme = detectTheme();
setTheme(newTheme);
setIframeSrc(buildUrl(newTheme, sdkFilter, viewMode));
};
if (mediaQuery.addEventListener) {
mediaQuery.addEventListener('change', handleThemeChange);
} else {
mediaQuery.addListener(handleThemeChange);
}
window.addEventListener('storage', handleThemeChange);
const observer = new MutationObserver(handleThemeChange);
observer.observe(document.documentElement, {
attributes: true,
attributeFilter: ['class', 'data-theme']
});
return () => {
if (mediaQuery.removeEventListener) {
mediaQuery.removeEventListener('change', handleThemeChange);
} else {
mediaQuery.removeListener(handleThemeChange);
}
window.removeEventListener('storage', handleThemeChange);
observer.disconnect();
};
}, [sdkFilter, viewMode]);
const getIframeHeight = () => {
if (viewMode === 'table') {
return '450';
}
if (viewMode === 'mini') {
return '170';
}
return '800';
};
const iframeHeight = height || getIframeHeight();
return
;
};
## 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](/docs/en/manage-team-members) to the Organization. Otherwise, [sign up for a free account](https://onesignal.com) to get started.
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**.
Enter the credentials for your platform:
* **Android**: [Set up Firebase credentials](/docs/en/android-firebase-credentials)
* **iOS**: [p8 token (recommended)](/docs/en/ios-p8-token-based-connection-to-apns) or [p12 certificate](/docs/en/ios-p12-generate-certificates)
* **Amazon**: [Generate API key](/docs/en/generate-an-amazon-api-key)
* **Huawei**: [Authorize OneSignal](/docs/en/authorize-onesignal-to-send-huawei-push)
Click **Save & Continue** after entering your credentials.
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.
***
## Configuração do iOS
Siga estes passos para adicionar notificações push ao seu aplicativo iOS, incluindo suporte para [Badges](./badges), [Confirmed receipt](./confirmed-delivery) e imagens.
### 1. Adicionar Push Notifications capability ao app target
A [Push Notifications capability](https://developer.apple.com/documentation/UserNotifications/registering-your-app-with-apns#Enable-the-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**
### 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](https://developer.apple.com/documentation/usernotifications/pushing-background-updates-to-your-app)
2. Habilite **Remote notifications**
### 3. Adicionar app target ao App Group
[App Groups](https://developer.apple.com/documentation/xcode/configuring-app-groups/#Create-App-Groups-for-all-other-platforms) 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 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 XML theme={null}
OneSignal_app_groups_key
group.your-custom-group-id
```
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
A [Notification Service Extension (NSE)](https://developer.apple.com/documentation/usernotifications/modifying-content-in-newly-delivered-notifications) 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.
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.
### 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](#3-add-app-target-to-app-group) para mais informações.
### 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:
```swift Swift theme={null}
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)
}
}
}
```
```objc Objective-C theme={null}
#import
#import "NotificationService.h"
@interface NotificationService ()
@property (nonatomic, strong) void (^contentHandler)(UNNotificationContent *contentToDeliver);
@property (nonatomic, strong) UNNotificationRequest *receivedRequest;
@property (nonatomic, strong) UNMutableNotificationContent *bestAttemptContent;
@end
@implementation NotificationService
// Note, this extension only runs when mutable-content is set
// Setting an attachment or action buttons automatically adds this
- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
self.receivedRequest = request;
self.contentHandler = contentHandler;
self.bestAttemptContent = [request.content mutableCopy];
// DEBUGGING: Uncomment the 2 lines below and comment out the one above to ensure this extension is executing
// NSLog(@"Running NotificationServiceExtension");
// self.bestAttemptContent.body = [@"[Modified] " stringByAppendingString:self.bestAttemptContent.body];
[OneSignalExtension didReceiveNotificationExtensionRequest:self.receivedRequest
withMutableNotificationContent:self.bestAttemptContent
withContentHandler:self.contentHandler];
}
- (void)serviceExtensionTimeWillExpire {
// Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.
[OneSignalExtension serviceExtensionTimeWillExpireRequest:self.receivedRequest withMutableNotificationContent:self.bestAttemptContent];
self.contentHandler(self.bestAttemptContent);
}
@end
```
Você deve ver um erro porque o pacote OneSignal não está instalado. Isso será resolvido 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](./in-app-messages-setup) 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 |
Navegue até **File > Add Package Dependencies...** e insira a URL para o repositório do OneSignal SDK:
`https://github.com/OneSignal/OneSignal-XCFramework`
Selecione 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](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app#Add-a-package-dependency).
**Requisitos**: CocoaPods 1.16.2+ (Instruções de configuração usam CocoaPods 1.16.2).
Abra seu `Podfile` e adicione o seguinte:
```ruby Podfile theme={null}
# 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 install`
Uma vez que a instalação estiver completa, certifique-se de abrir o arquivo *XCWorkspace* nomeado após seu projeto (ex.: `.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.
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/.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
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.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](./keys-and-ids)**. Se você não tem acesso ao aplicativo OneSignal, peça aos seus [Team Members](./manage-team-members) para convidá-lo.
```swift Swift theme={null}
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
}
}
```
Se estiver usando interface Storyboard, navegue até seu arquivo AppDelegate 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](./keys-and-ids)**. Se você não tem acesso ao aplicativo OneSignal, peça aos seus [Team Members](./manage-team-members) para convidá-lo.
```swift Swift theme={null}
//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...
}
```
```objc Objective-C theme={null}
#import
@implementation AppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// Habilite log detalhado para debugging (remova em produção)
[OneSignal.Debug setLogLevel:ONE_S_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:^(BOOL accepted) {
NSLog(@"User accepted notifications: %d", accepted);
} fallbackToSettings:false];
// Faça login do seu cliente com externalId
// [OneSignal login:@"EXTERNAL_ID"];
return YES;
}
```
***
## 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
O prompt de permissão push nativo deve aparecer automaticamente se você adicionou o método `requestPermission` durante a inicialização.
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".
O status da assinatura agora deve mostrar **Subscribed**.
Você criou com sucesso uma [assinatura mobile](/docs/en/subscriptions).
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.
No painel, ao lado da assinatura, clique no botão **Options (três pontos)** e selecione **Add to Test Users**.
Nomeie a assinatura para que você possa identificar facilmente seu dispositivo mais tarde na **aba Test Users**.
Vá para **Audience > Segments > New Segment**.
Nomeie o segmento `Test Users` (o nome é importante porque será usado mais tarde).
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
No seu painel do OneSignal, vá para **Settings > [Keys & IDs](/docs/en/keys-and-ids)**.
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.
```curl theme={null}
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"
}'
```
Execute o código no seu terminal.
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.
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](#ios-setup) pode estar faltando.
* Não recebeu confirmed receipt? Revise o guia de solução de problemas [aqui](/docs/en/confirmed-delivery#troubleshooting-confirmed-delivery).
* 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](/docs/en/in-app-messages-setup) permitem que você se comunique com usuários enquanto eles estão usando seu aplicativo.
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](/docs/en/in-app-messages-setup#how-are-iams-displayed%3F).
* 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.
Em **Schedule > How often do you want to show this message?** selecione **Every time trigger conditions are satisfied**.
Clique em **Make Message Live** para que ela esteja disponível para seus Test Users cada vez que eles abrirem o aplicativo.
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](/docs/en/in-app-messages-setup#how-are-iams-displayed%3F).
* Ainda no segmento `Test Users`?
* Se você reinstalou ou trocou de dispositivo, adicione novamente o dispositivo às [Test Users](#set-up-test-users) e confirme que ele faz parte do segmento Test Users.
* Tendo problemas?
* Siga [Obtendo um Debug Log](/docs/en/capturing-a-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:
* Coletar [Assinaturas](/docs/en/subscriptions), definir [Assinaturas de teste](/docs/en/find-set-test-subscriptions) e criar [Segmentos](/docs/en/segmentation).
* Enviar [Push](/docs/en/push) com imagens e [Confirmed receipt](/docs/en/confirmed-delivery) usando Segmentos e nossa API [Create message](/reference/create-message).
* Enviar [Mensagens no aplicativo](/docs/en/in-app-messages-setup).
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](/docs/en/subscriptions) mobile. Agora vamos expandir para identificar [Usuários](/docs/en/users) 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](/docs/en/integrations)).
Defina o External ID com o [método `login`](/docs/en/mobile-sdk-reference#login-external-id) 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](/docs/en/add-user-data-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](/docs/en/message-personalization) e [Segmentação](/docs/en/segmentation) avançadas permitindo casos de uso mais avançados.
Defina tags com os [métodos `addTag` e `addTags`](/docs/en/mobile-sdk-reference#data-tags) 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`.
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:
### 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 `addEmail`](/docs/en/mobile-sdk-reference#addemail-%2C-removeemail) para criar assinaturas de email.
* Use o [método `addSms`](/docs/en/mobile-sdk-reference#addsms-%2C-removesms) para criar assinaturas de SMS.
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](/reference/view-user).
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)`](/docs/en/mobile-sdk-reference#setconsentrequired): Previne coleta de dados até que o consentimento seja dado.
* [`setConsentGiven(true)`](/docs/en/mobile-sdk-reference#setconsentgiven): Habilita coleta de dados uma vez que o consentimento seja concedido.
Consulte nossos documentos de Privacidade & segurança para mais sobre:
* [Dados coletados pelo SDK](/docs/en/data-collected-by-the-onesignal-sdk)
* [Manipulação de dados pessoais](/docs/en/handling-personal-data)
***
## 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](/docs/en/prompt-for-push-permissions).
***
## 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](/docs/en/mobile-sdk-reference) para mais detalhes.
### Eventos de notificação push
* [`addClickListener()`](/docs/en/mobile-sdk-reference#addclicklistener-push): Detecta quando uma notificação é tocada. Útil para [Deep Linking](/docs/en/deep-linking).
* [`addForegroundLifecycleListener()`](/docs/en/mobile-sdk-reference#addforegroundlifecyclelistener-push): Controla como notificações se comportam em primeiro plano.
Para customização completa, consulte [Mobile Service Extensions](/docs/en/service-extensions).
### Mudanças de estado do usuário
* [`addObserver()` para estado do usuário](/docs/en/mobile-sdk-reference#addobserver-user-state): Detecta quando o External ID é definido.
* [`addPermissionObserver()`](/docs/en/mobile-sdk-reference#addpermissionobserver-push): Rastreia a interação específica do usuário com o prompt de permissão push nativo.
* [`addObserver()` para assinatura push](/docs/en/mobile-sdk-reference#addobserver-push-subscription-changes): Rastreia quando o status da assinatura push muda.
### Eventos de mensagens no aplicativo
* [`addClickListener()`](/docs/en/mobile-sdk-reference#addclicklistener-in-app): Manipula ações de clique em mensagens no aplicativo. Ideal para deep linking ou rastreamento de eventos.
* [`addLifecycleListener()`](/docs/en/mobile-sdk-reference#addclicklistener-in-app): 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:
```xml theme={null}
OneSignal_disable_swizzling
```
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.
```swift Swift theme={null}
// In application(_:didFinishLaunchingWithOptions:), BEFORE OneSignal.initialize()
UNUserNotificationCenter.current().delegate = self
```
```objc Objective-C theme={null}
// In application:didFinishLaunchingWithOptions:, BEFORE [OneSignal initialize:]
[UNUserNotificationCenter currentNotificationCenter].delegate = self;
```
### 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:**
```swift Swift theme={null}
func application(_ application: UIApplication,
didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
OneSignal.Notifications.didRegisterForRemoteNotifications(application, deviceToken: deviceToken)
}
func application(_ application: UIApplication,
didFailToRegisterForRemoteNotificationsWithError error: Error) {
OneSignal.Notifications.handleDidFailRegisterForRemoteNotification(error as NSError)
}
```
```objc Objective-C theme={null}
- (void)application:(UIApplication *)application
didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
[OneSignal.Notifications didRegisterForRemoteNotifications:application deviceToken:deviceToken];
}
- (void)application:(UIApplication *)application
didFailToRegisterForRemoteNotificationsWithError:(NSError *)error {
[OneSignal.Notifications handleDidFailRegisterForRemoteNotification:error];
}
```
**Notificações em segundo plano / silenciosas:**
```swift Swift theme={null}
func application(_ application: UIApplication,
didReceiveRemoteNotification userInfo: [AnyHashable: Any],
fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
OneSignal.Notifications.receiveRemoteNotification(application,
userInfo: userInfo,
completionHandler: completionHandler)
}
```
```objc Objective-C theme={null}
- (void)application:(UIApplication *)application
didReceiveRemoteNotification:(NSDictionary *)userInfo
fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
[OneSignal.Notifications receiveRemoteNotification:application
UserInfo:userInfo
completionHandler:completionHandler];
}
```
**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.
```swift Swift theme={null}
func userNotificationCenter(_ center: UNUserNotificationCenter,
willPresent notification: UNNotification,
withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
OneSignal.Notifications.handleWillPresentNotificationInForeground(
withPayload: notification.request.content.userInfo
) { notif in
if notif != nil {
if #available(iOS 14.0, *) {
completionHandler([.banner, .list, .sound])
} else {
completionHandler([.alert, .sound])
}
} else {
completionHandler([])
}
}
}
```
```objc Objective-C theme={null}
- (void)userNotificationCenter:(UNUserNotificationCenter *)center
willPresentNotification:(UNNotification *)notification
withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler {
[OneSignal.Notifications
handleWillPresentNotificationInForegroundWithPayload:notification.request.content.userInfo
withCompletion:^(OSNotification *notif) {
if (notif) {
if (@available(iOS 14.0, *)) {
completionHandler(UNNotificationPresentationOptionBanner |
UNNotificationPresentationOptionList |
UNNotificationPresentationOptionSound);
} else {
completionHandler(UNNotificationPresentationOptionAlert |
UNNotificationPresentationOptionSound);
}
} else {
completionHandler(UNNotificationPresentationOptionNone);
}
}];
}
```
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:**
```swift Swift theme={null}
func userNotificationCenter(_ center: UNUserNotificationCenter,
didReceive response: UNNotificationResponse,
withCompletionHandler completionHandler: @escaping () -> Void) {
OneSignal.Notifications.handleNotificationResponse(response)
completionHandler()
}
```
```objc Objective-C theme={null}
- (void)userNotificationCenter:(UNUserNotificationCenter *)center
didReceiveNotificationResponse:(UNNotificationResponse *)response
withCompletionHandler:(void (^)(void))completionHandler {
[OneSignal.Notifications handleNotificationResponse:response];
completionHandler();
}
```
### 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:
```swift Swift theme={null}
OneSignal.Notifications.setBadgeCount(5)
```
```objc Objective-C theme={null}
[OneSignal.Notifications setBadgeCount:5];
```
### 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 Swift theme={null}
@main
struct YourApp: App {
@UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate
var body: some Scene {
WindowGroup {
ContentView()
}
}
}
class AppDelegate: NSObject, UIApplicationDelegate, UNUserNotificationCenterDelegate {
func application(_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
UNUserNotificationCenter.current().delegate = self
OneSignal.initialize("YOUR_APP_ID", withLaunchOptions: launchOptions)
return true
}
// Implement all the forwarding methods shown above
}
```
### 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](/docs/en/migrating-to-onesignal)
* [🌍 Rastreamento de localização](/docs/en/mobile-sdk-reference#location)
* [🔗 Deep Linking](/docs/en/deep-linking)
* [🔌 Integrações](/docs/en/integrations)
* [🧩 Mobile Service Extensions](/docs/en/service-extensions)
* [🛎️ Botões de ação](/docs/en/action-buttons)
* [🌐 Mensagens em vários idiomas](/docs/en/multi-language-messaging)
* [🛡️ Verificação de identidade](/docs/en/identity-verification)
* [📊 Outcomes customizados](/docs/en/custom-outcomes)
* [📲 Live Activities](/docs/en/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](/docs/en/mobile-push-setup).
Para detalhes completos sobre métodos disponíveis e opções de configuração, visite a [Referência do Mobile SDK](/docs/en/mobile-sdk-reference).
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.com`
Please 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](/docs/en/capturing-a-debug-log)
We're happy to help!
***