Configuração do SDK .NET MAUI

​

Visão geral

​

Requisitos

• .NET 7.0+
• Visual Studio 2019 ou mais recente
• Aplicativo OneSignal e plataforma configurados

• macOS com Xcode 14+ (instruções de configuração usam Xcode 16.2)
• Dispositivo com iOS 12+, iPadOS 12+ ou simulador Xcode executando iOS 16.2+
• CocoaPods 1.16.2+

• Dispositivo ou emulador Android 7.0+ com Google Play Store (Services) instalado

​

Configure seu app e plataforma OneSignal

Instruções passo a passo para configurar seu app OneSignal.

Você pode gerenciar múltiplas plataformas (iOS, Android, Huawei, Amazon, Web) sob um único app OneSignal.

1

Crie ou selecione seu app

• Para adicionar plataformas a um app existente, vá para Settings > Push & In-App no dashboard OneSignal.
• Para começar do zero, clique em New App/Website e siga as instruções.

Exemplo mostrando criação de um novo app.

2

Configure e ative uma plataforma

• Escolha um nome claro e reconhecível para seu app e organização.
• Selecione a(s) plataforma(s) que você quer configurar (iOS, Android, etc.).
• Clique em Next: Configure Your Platform.

Exemplo configurando seu primeiro app OneSignal, org e canal.

3

Configure credenciais da plataforma

Siga as instruções baseadas nas suas plataformas:

• Android: Configure Credenciais Firebase
• iOS: Token p8 (Recomendado) ou Certificado p12
• Amazon: Gere API Key
• Huawei: Autorize OneSignal

Clique em Save & Continue após inserir suas credenciais.

4

Escolha o SDK alvo

Selecione o SDK que corresponde à sua plataforma de desenvolvimento (por exemplo, iOS, Android, React Native, Unity), depois clique em Save & Continue.

Selecione qual SDK você está usando para navegar à documentação.

5

Instale o SDK e salve seu App ID

Uma vez que sua plataforma está configurada, seu OneSignal App ID será exibido. Copie e salve este ID—você precisará dele ao instalar e inicializar o SDK.Se estiver colaborando com outros, use o botão Invite para adicionar desenvolvedores ou membros da equipe, depois clique em Done para completar a configuração.

Salve seu App ID e convide membros adicionais da equipe.

Uma vez completo, siga o guia de instalação do SDK para sua plataforma selecionada para finalizar a integração OneSignal.

​

Configuração do SDK

​

1. Adicionar SDK

  dotnet add package OneSignalSDK.DotNet

​

2. Inicializar SDK

using OneSignalSDK.DotNet;
using OneSignalSDK.DotNet.Core;
using OneSignalSDK.DotNet.Core.Debug;

public App() {
  InitializeComponent();

  // Enable verbose OneSignal logging to debug issues if needed.
  OneSignal.Debug.LogLevel = LogLevel.VERBOSE;

  // OneSignal Initialization
  OneSignal.Initialize("YOUR_APP_ID");

  // RequestPermissionAsync will show the notification permission prompt.
  // We recommend removing the following code and instead using an In-App Message to prompt for notification permission (See step 5)
  OneSignal.Notifications.RequestPermissionAsync(true);

  MainPage = new AppShell();
}

​

3. Adicionar uma extensão de serviço iOS

using System;
using Foundation;
using OneSignalSDK.DotNet;
using OneSignalSDK.DotNet.iOS;
using UIKit;
using UserNotifications;

namespace OneSignalNotificationServiceExtension
{
    [Register("NotificationService")]
    public class NotificationService : UNNotificationServiceExtension
    {
        Action<UNNotificationContent> ContentHandler { get; set; }
        UNMutableNotificationContent BestAttemptContent { get; set; }
        UNNotificationRequest ReceivedRequest { get; set; }

        protected NotificationService(IntPtr handle) : base(handle)
        {
            // Note: this .ctor should not contain any initialization logic.
        }

        public override void DidReceiveNotificationRequest(UNNotificationRequest request, Action<UNNotificationContent> contentHandler)
        {
            ReceivedRequest = request;
            ContentHandler = contentHandler;
            BestAttemptContent = (UNMutableNotificationContent)request.Content.MutableCopy();

            NotificationServiceExtension.DidReceiveNotificationExtensionRequest(request, BestAttemptContent, contentHandler);
        }

        public override void TimeWillExpire()
        {
            // Called just before the extension will be terminated by the system.
            // Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.

            NotificationServiceExtension.ServiceExtensionTimeWillExpireRequest(ReceivedRequest, BestAttemptContent);

            ContentHandler(BestAttemptContent);
        }
    }
}

​

Configuração Android

​

Configuração iOS

​

1. Adicione capability Push Notifications ao app target

1. Abra o arquivo .xcworkspace do seu app no Xcode.
2. Selecione your app target > Signing & Capabilities
3. Clique em + Capability e adicione a capability Push Notifications

O app target recebe a capability Push Notifications.

​

2. Adicione capability Background Modes ao app target

1. Adicione a capability Background Modes
2. Habilite Remote notifications

O app target recebe o modo de execução em background Remote Notifications.

​

3. Adicione 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 bundle identifier do seu app.
• Por exemplo, bundle identifier 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. Adicione 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 Activate scheme.

Selecione o target Notification Service Extension.

Nomeie a Notification Service Extension.

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

Defina o mesmo deployment target do app principal.

​

5. Adicione NSE target ao app group

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

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

​

6. Atualize código NSE

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

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

​

7. Adicione OneSignal ao NSE target

target 'OneSignalNotificationServiceExtension' do
  pod 'OneSignalXCFramework', '>= 5.0.0', '< 6.0'
end

cd ios pod install cd ..

​

Erros comuns do pod install

​

Build para iOS

​

Erros comuns de build iOS

Cycle Inside... building could produce unreliable results.

Você pode ver este erro ao fazer build com Xcode 15+, devido a uma mudança de configuração padrão afetando sistemas cross-platform.

1. Abra sua pasta .xcworkspace no Xcode e navegue para your app target > Build Phases.
2. Você deve ter uma fase chamada “Embed Foundation Extensions” ou “Embed App Extensions”.
3. Arraste e mova esta fase de build para acima de “Run Script”.
4. Faça build e execute seu app. O erro deve ser resolvido.

Ordem correta das Build Phases no Xcode.

Desmarque Copy only when installing.

Erro PBXGroup

RuntimeError - PBXGroup tentou inicializar um objeto com ISA desconhecido PBXFileSystemSynchronizedRootGroup dos atributos: {"isa"=>"...", "exceptions"=>["//", "..."], "explicitFileTypes"=>{}, "explicitFolders"=>[], "path"=>"OneSignalNotificationServiceExtension", "sourceTree"=>"<group>"}

Correção:

1. Encontre a pasta listada sob “path” no erro
2. Na barra lateral do projeto Xcode, clique com botão direito na pasta
3. Selecione Convert to Group

Erro de path para PBXGroup.

Converta pasta para group.

​

Testando a integração do OneSignal SDK

​

Verifique inscrições mobile

1

Inicie seu app 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 iOS e Android

2

Verifique seu dashboard OneSignal

Antes de aceitar o prompt, verifique o dashboard OneSignal:

• Vá para Audience > Subscriptions.
• Você deve ver uma nova entrada com o status “Never Subscribed”.

Dashboard mostrando inscrição com status 'Never Subscribed'

3

Retorne ao app e toque em Allow no prompt.

4

Atualize a página de Subscription do dashboard OneSignal.

O status da inscrição deve agora mostrar Subscribed.

Dashboard mostrando inscrição com status 'Subscribed'

Você criou com sucesso uma inscrição mobile. Inscrições mobile são criadas quando usuários abrem seu app pela primeira vez em um dispositivo ou se eles desinstalam e reinstalam seu app no mesmo dispositivo.

​

Configure inscrições de teste

1

Adicione a Test Subscriptions.

No dashboard, próximo à inscrição, clique no botão Options (três pontos) e selecione Add to Test Subscriptions.

Adicionando um dispositivo a Test Subscriptions

2

Nomeie sua inscrição.

Nomeie a inscrição para que você possa identificar facilmente seu dispositivo depois na aba Test Subscriptions.

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

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 enviar mensagens para este dispositivo individual e grupos de usuários de teste.

​

Envie push de teste via API

1

Obtenha seu App API Key e App ID.

No seu dashboard 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 com 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 entrega confirmada.

Se todos os passos de configuração foram completados com sucesso, as inscrições 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 por entrega confirmada.

No seu dashboard, vá para Delivery > Sent Messages, depois clique na mensagem para ver as estatísticas.Você deve ver a estatística confirmed, significando que o dispositivo recebeu o push.

Estatísticas de entrega mostrando entrega confirmada

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

Entrega confirmada a nível de dispositivo em Audience Activity

Você enviou com sucesso uma notificação via nossa API para um segmento.

• Não recebeu imagem? Sua Notification Service Extension pode estar faltando.
• Sem entrega confirmada? Revise o guia de solução de problemas aqui.
• Tendo problemas? Copie e cole a requisição da api e um log do início ao fim do lançamento do app em um arquivo .txt. Depois compartilhe ambos com support@onesignal.com.

​

Envie uma mensagem in-app

1

Feche ou coloque em background seu app no dispositivo.

Isso é porque usuários devem atender aos critérios de público in-app antes que uma nova sessão inicie. No OneSignal, uma nova sessão inicia quando o usuário abre seu app depois de ter estado em background ou fechado por pelo menos 30 segundos. Para mais detalhes, veja nosso guia sobre como mensagens in-app são exibidas.

2

Crie uma mensagem in-app.

• No seu dashboard OneSignal, navegue para Messages > In-App > New In-App.
• Encontre e selecione a mensagem Welcome.
• Defina seu Público como o segmento Test Users que usamos anteriormente.

Direcionando o segmento 'Test Users' com uma mensagem in-app

3

Personalize o conteúdo da mensagem se desejar.

Exemplo de personalização da mensagem Welcome in-app

4

Defina Trigger como 'On app open'.

5

Agende 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 in-app

6

Torne a mensagem ativa.

Clique em Make Message Live para que fique disponível para seus Test Users cada vez que eles abrem o app.

7

Abra o app e veja a mensagem.

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

Mensagem in-app Welcome mostrada em dispositivos

Não está vendo a mensagem?

• Inicie uma nova sessão
  • Você deve fechar ou colocar em background o app por pelo menos 30 segundos antes de reabrir. Isso garante que uma nova sessão seja iniciada.
  • Para mais, veja como mensagens in-app são exibidas.
• Ainda no segmento Test Users?
  • Se você reinstalou ou trocou de dispositivo, adicione novamente o dispositivo a 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

​

Atribua External ID

​

Adicione data tags

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

Editor de segmento mostrando um segmento direcionado a usuários com um valor current_level maior que 4 e menor que 10

Captura de tela mostrando uma notificação push direcionada ao segmento Nível 5-10 com uma mensagem personalizada

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

​

Adicione inscrições de email e/ou SMS

• Use o método addEmail para criar inscrições de email.
• Use o método addSms para criar inscrições de SMS.

Um perfil de usuário com inscrições push, email e SMS unificadas por External ID

​

Privacidade e consentimento do usuário

• setConsentRequired(true): Previne coleta de dados até que consentimento seja dado.
• setConsentGiven(true): Habilita coleta de dados uma vez que consentimento é concedido.

• Dados coletados pelo SDK
• Tratamento de dados pessoais

​

Solicite permissões push

​

Escute eventos de push, usuário e in-app

​

Eventos de notificação push

• addClickListener(): Detecte quando uma notificação é tocada. Útil para Deep Linking.
• addForegroundLifecycleListener(): Controle como notificações se comportam em foreground.

​

Mudanças de estado do usuário

• addObserver() para estado do usuário: Detecte quando o External ID é definido.
• addPermissionObserver(): Rastreie a interação específica do usuário com o prompt de permissão push nativo.
• addObserver() para inscrição push: Rastreie quando o status de inscrição push muda.

​

Eventos de mensagem in-app

• addClickListener(): Lide com ações de clique in-app. Ideal para deep linking ou rastreamento de eventos.
• addLifecycleListener(): Rastreie o ciclo de vida completo de mensagens in-app (exibida, clicada, descartada, etc.).

​

Configuração avançada e capacidades

• 🔁 Migrando para OneSignal de outro serviço
• 🌍 Rastreamento de localização
• 🔗 Deep Linking
• 🔌 Integrações
• 🧩 Mobile Service Extensions
• 🛎️ Botões de ação
• 🌐 Mensagens multilíngues
• 🛡️ Verificação de Identidade
• 📊 Custom Outcomes
• 📲 Live Activities

​

Configuração e referência do Mobile SDK