Pular para o conteúdo principal

​
Visão geral

Este guia explica como integrar notificações push do OneSignal em um aplicativo .NET MAUI. Ele cobre tudo, desde a instalação até a configuração e gerenciamento do service worker.

​
Requisitos

  • .NET 7.0+
  • Visual Studio 2019 ou mais recente
  • Aplicativo OneSignal e plataforma configurados
Requisitos iOS
  • 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+
Requisitos Android
  • Dispositivo ou emulador Android 7.0+ com Google Play Store (Services) instalado

​
Configure seu app e plataforma OneSignal

Configure seu app OneSignal com as plataformas que você suporta — Apple (APNs), Google (FCM), Huawei (HMS) e/ou Amazon (ADM).
Se sua organização já tem uma conta OneSignal, peça para ser convidado à Organização. Caso contrário, cadastre-se para uma conta gratuita para começar.
1

Crie ou selecione seu app

Crie um novo app clicando em New App/Website, ou adicione uma plataforma a um app existente em Settings > Push & In-App. Selecione a(s) plataforma(s) que você quer configurar e clique em Next: Configure Your Platform.
Dashboard do OneSignal mostrando o fluxo de configuração de novo app com nome da organização, nome do app e seleção de canal
2

Configure credenciais da plataforma

Insira as credenciais para sua plataforma:Clique em Save & Continue após inserir suas credenciais.
3

Salve seu App ID e instale o SDK

Seu App ID é exibido na tela final. Copie e salve-o — você precisa dele ao inicializar o SDK. Selecione sua plataforma de SDK e siga o guia de configuração.
Dashboard do OneSignal mostrando o App ID e a opção de convite de equipe após a configuração

​
Configuração do SDK

​
1. Adicionar SDK

Usando a CLI .NET:
bash
  dotnet add package OneSignalSDK.DotNet

​
2. Inicializar SDK

Xamarin Forms não é mais suportado além da versão 5.0.2 do nosso SDK .NET. A Microsoft tem guias sobre migração para Maui aqui, se necessário.
Inicialize o OneSignal no arquivo App.xaml.cs. Substitua YOUR_APP_ID pelo seu OneSignal App ID encontrado no painel OneSignal Settings > Keys & IDs.
Se você não tem acesso ao aplicativo OneSignal, peça aos Membros da Equipe para convidá-lo.
C#
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

A Microsoft tem um guia sobre geração de uma Notification Service Extension aqui, usando Visual Studio e Visual Studio para Mac, mas não tem orientação sobre como você criaria isso para VSCode neste momento. Se você gerar uma extensão de serviço seguindo o guia acima, você pode seguir este código em nosso projeto de exemplo encontrado no Github
C#
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

Certifique-se de que seu app OneSignal está configurado para a plataforma Android usando suas credenciais Firebase. Configure seus ícones de notificação para corresponder à marca do seu app. Se este passo for pulado, um ícone de sino padrão será exibido para suas notificações push. Build para Android Neste ponto, você deve ser capaz de fazer build e executar seu app em um dispositivo Android físico ou emulador sem problemas.
Após confirmar que seu build Android funciona:

​
Configuração iOS

Certifique-se de que seu app OneSignal está configurado para a plataforma iOS usando o Token p8 (Recomendado) ou Certificado p12. Siga estes passos para adicionar notificações push ao seu app iOS, incluindo suporte para Badges, Entrega Confirmada e imagens.

​
1. Adicione capability Push Notifications ao app target

A capability Push Notifications permite que seu app registre um token push e receba notificações.
  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

​
2. Adicione capability Background Modes ao app target

Isso permite que seu app seja ativado em background quando notificações push chegam.
  1. Adicione a capability Background Modes
  2. Habilite Remote notifications

​
3. Adicione app target ao App Group

App Groups permitem compartilhamento de dados entre seu app e a Notification Service Extension. Necessário para Entrega Confirmada 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 bundle identifier do seu app.
  • Por exemplo, bundle identifier 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.

​
4. Adicione Notification Service Extension

A Notification Service Extension (NSE) habilita notificações ricas e análises de Entrega Confirmada.
  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.
Defina o Minimum Deployment Target do OneSignalNotificationServiceExtension para corresponder ao seu app principal (iOS 15+ recomendado).
Se você está usando CocoaPods, defina a versão de deployment no seu Podfile também.

​
5. Adicione 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 exatamente o mesmo group ID
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 para ambos o App Target e o Info.plist do OneSignalNotificationServiceExtension Target! Veja o passo 3 para mais informações.

​
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:
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)
        }
    }
}
Você deve ver um erro porque o pacote OneSignal não está instalado. Isso será resolvido no próximo passo.

​
7. Adicione OneSignal ao NSE target

Atualize seu ios/Podfile para incluir: 
target 'OneSignalNotificationServiceExtension' do
  pod 'OneSignalXCFramework', '>= 5.0.0', '< 6.0'
end
Abra seu projeto no terminal e execute:
shell
cd ios pod install cd ..

​
Erros comuns do pod install

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é o momento, o lançamento mais recente do xcodeproj não reconhece a versão de objeto 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 para o arquivo ios/<your-app>.xcodeproj/project.pbxproj do seu projeto.
  3. Mude esta linha: objectVersion = 70;
  4. Substitua por: objectVersion = 55;
  5. Salve, feche e execute novamente cd ios pod install cd ..

​
Build para iOS

Você deve agora ser capaz de fazer build e executar seu app em um dispositivo iOS real ou simulador iOS (16.2+).

​
Erros comuns de build iOS

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

Após confirmar que seu build iOS funciona, continue com Testando a integração do OneSignal SDK.

​
Testando a integração do OneSignal SDK

Este guia ajuda você a verificar se sua integração do OneSignal SDK está funcionando corretamente testando notificações push, registro de inscrição e mensagens in-app.
Se você está testando com um emulador Android, ele deve iniciar com um cold boot.
  1. Vá para Device Manager no Android Studio.
  2. Selecione seu dispositivo emulador e clique em Edit.
  3. Vá para Additional Settings ou More.
  4. Defina a Boot option para Cold Boot.
  5. Salve as alterações e reinicie o emulador.

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

Inscrições de teste são úteis para testar uma notificação push antes de enviar uma mensagem.
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.
2

Nomeie sua inscrição.

Nomeie a inscrição para que você possa identificar facilmente seu dispositivo depois 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 depois).
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 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.
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:
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.
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

Mensagens in-app permitem que você se comunique com usuários enquanto eles estão usando seu 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.
3

Personalize o conteúdo da mensagem se desejar.

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.
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:
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.
Você configurou com sucesso o OneSignal SDK e aprendeu conceitos importantes como:Continue com este guia para identificar usuários no seu app e configurar recursos adicionais.

​
Identificação de usuário

Anteriormente, demonstramos como criar Inscrições móveis. Agora vamos expandir para identificar Usuários através de todas as suas inscrições (incluindo push, email e SMS) usando o OneSignal SDK. Cobriremos External IDs, tags, inscrições multicanal, privacidade e rastreamento de eventos para ajudá-lo a unificar e engajar usuários através de plataformas.

​
Atribua External ID

Use um External ID para identificar usuários consistentemente através de dispositivos, endereços de email e números de telefone usando o identificador de usuário do seu backend. Isso garante que suas mensagens permaneçam unificadas através de canais e sistemas de terceiros (especialmente importante para Integrações). Defina o External ID com o método login do nosso SDK cada vez que eles são identificados pelo seu app.
OneSignal gera IDs únicos somente leitura para inscrições (Subscription ID) e usuários (OneSignal ID).À medida que usuários baixam seu app em diferentes dispositivos, se inscrevem no seu website e/ou fornecem endereços de email e números de telefone fora do seu app, novas inscrições serão criadas.Definir o External ID via nosso SDK é altamente recomendado para identificar usuários através de todas as suas inscrições, independentemente de como elas são criadas.

​
Adicione Tags

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 de usuário). Tags potencializam Personalização de Mensagem avançada e Segmentação permitindo casos de uso mais avançados. Defina tags com os métodos addTag e addTags do nosso SDK conforme eventos ocorrem no seu app. 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:


​
Adicione inscrições de email e/ou SMS

Anteriormente vimos como nosso SDK cria inscrições móveis para enviar push e mensagens in-app. Você também pode alcançar usuários através de canais de email e SMS criando as inscrições correspondentes. Se o endereço de email e/ou número de telefone já existem no app OneSignal, o SDK adicionará ao usuário existente, não criará duplicatas. Você pode visualizar usuários unificados via Audience > Users no dashboard ou com a API View user.
Melhores práticas para comunicação multicanal
  • Obtenha consentimento explícito antes de adicionar inscrições 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 usuários possam selecionar quais canais eles preferem.

​
Privacidade e consentimento do usuário

Para controlar quando OneSignal coleta dados de usuário, use os métodos de controle de consentimento do SDK: Veja nossos documentos de Privacidade e segurança para mais sobre:

​
Solicite permissões push

Em vez de chamar requestPermission() imediatamente ao abrir o app, adote uma abordagem mais estratégica. Use uma mensagem in-app para explicar o valor das notificações push antes de solicitar permissão. Para melhores práticas e detalhes de implementação, veja nosso guia Solicite permissões push.

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

Use listeners do SDK para reagir a ações de usuário e mudanças de estado. O SDK fornece vários event listeners para você conectar. Veja nosso guia de referência do SDK para mais detalhes.

​
Eventos de notificação push

Para personalização completa, veja Mobile Service Extensions.

​
Mudanças de estado do usuário

​
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

Explore mais capacidades para melhorar sua integração:

​
Configuração e referência do Mobile SDK

Certifique-se de que você habilitou todos os recursos principais revisando o guia Configuração de mobile push. Para detalhes completos sobre métodos disponíveis e opções de configuração, visite a referência do Mobile SDK.
Parabéns! Você completou com sucesso o guia de configuração do Mobile SDK.
Precisa de ajuda?Converse com nossa equipe de Suporte ou envie email para support@onesignal.comPor favor inclua:
  • Detalhes do problema que você está enfrentando e passos para reproduzir se disponível
  • Seu OneSignal App ID
  • O External ID ou Subscription ID se aplicável
  • A URL para a mensagem que você testou no Dashboard OneSignal se aplicável
  • Quaisquer logs ou mensagens de erro relevantes
Estamos felizes em ajudar!