​

Overview

​

Requirements

• .NET 7.0+
• Visual Studio 2019 or newer
• Configured OneSignal app and platform

• macOS with Xcode 14+ (setup instructions use Xcode 16.2)
• Device with iOS 12+, iPadOS 12+, or Xcode simulator running iOS 16.2+
• CocoaPods 1.16.2+

• Android 7.0+ device or emulator with Google Play Store (Services) installed

​

Configure your OneSignal app and platform

​

SDK Setup

​

1. Add SDK

 dotnet add package OneSignalSDK.DotNet

​

Optional: Disable the location module

<PropertyGroup>
 <OneSignalDisableLocation>true</OneSignalDisableLocation>
</PropertyGroup>

dotnet build -f net10.0-ios -p:OneSignalDisableLocation=true
dotnet build -f net10.0-android -p:OneSignalDisableLocation=true

​

2. Initialize 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. Adding an iOS Service Extension

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

​

Android setup

​

iOS setup

​

1. Add Push Notifications capability to app target

1. Open your app’s .xcworkspace file in Xcode.
2. Select your app target > Signing & Capabilities
3. Click + Capability and add Push Notifications capability

​

2. Add Background Modes capability to app target

1. Add Background Modes capability
2. Enable Remote notifications

​

3. Add app target to App Group

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

​

4. Add Notification Service Extension

1. In Xcode: File > New > Target…
2. Select Notification Service Extension, then Next.
3. Set the product name to OneSignalNotificationServiceExtension and press Finish.
4. Press Don’t Activate on the Activate scheme prompt.

​

5. Add NSE target to app group

1. Go to OneSignalNotificationServiceExtension > Signing & Capabilities
2. Add App Groups
3. Add the exact same group ID

​

6. Update NSE code

1. Navigate to the OneSignalNotificationServiceExtension folder
2. Replace the contents of the NotificationService.swift or NotificationService.m file with the following:

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

​

7. Add OneSignal to the NSE target

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

cd ios pod install cd ..

​

Common pod install errors

​

Build for iOS

​

Common iOS build errors

​

Testing the OneSignal SDK integration

​

Check mobile subscriptions

​

Set up test users

​

Send test push via API

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

​

Send an in-app message

​

User identification

​

Assign External ID

​

Add Tags

​

Add email and/or SMS subscriptions

• Use the addEmail method to create email subscriptions.
• Use the addSms method to create SMS subscriptions.

​

Privacy & user consent

• setConsentRequired(true): Prevents data collection until consent is given.
• setConsentGiven(true): Enables data collection once consent is granted.

• Data collected by the SDK
• Handling personal data

​

Prompt for push permissions

​

Listen to push, user, and in-app events

​

Push notification events

• addClickListener(): Detect when a notification is tapped. Helpful for Deep Linking.
• addForegroundLifecycleListener(): Control how notifications behave in foreground.

​

User state changes

• addObserver() for user state: Detect when the External ID is set.
• addPermissionObserver(): Track the user’s specific interaction with the native push permission prompt.
• addObserver() for push subscription: Track when the push subscription status changes.

​

In-app message events

• addClickListener(): Handle in-app click actions. Ideal for deep linking or tracking events.
• addLifecycleListener(): Track full lifecycle of in-app messages (shown, clicked, dismissed, etc.).

​

Advanced setup & capabilities

• 🔁 Migrating to OneSignal from another service
• 🌍 Location tracking
• 🔗 Deep Linking
• 🔌 Integrations
• 🧩 Mobile Service Extensions
• 🛎️ Action buttons
• 🌐 Multi-language messaging
• 🛡️ Identity Verification
• 📊 Custom Outcomes
• 📲 Live Activities

​

Mobile SDK setup & reference