.NET SDK Setup

Instructions for adding OneSignal .NET SDK to your cross-platform MAUI app for iOS, Android, and Desktop.

Requirements

iOS Requirements

  • An iOS 9+ or iPadOS device (iPhone, iPad, iPod Touch) to test on. Xcode 14+ simulator works running iOS 16+.
  • A Mac with Xcode 12+.
  • An iOS Push Certificate.

Android Requirements

Amazon & Huawei Requirements

Follow these instructions if your app is distributed on the Amazon AppStore and the Huawei AppGallery.

Step 1 – Install Packages

1.1 From Solution Explorer, context-click Dependencies and choose Manage NuGet Packages…

768768

1.2 Choose "nuget.org" as the Package source in the bottom left corner of the dialog.
1.3 Search for “OneSignalSDK.DotNet” and select that package in the list.

18021802

1.4 Choose Add Packages.

Step 2 – Add Source Code

.NET MAUI

Initialize OneSignal in App.xaml.cs in your MAUI project as follows:

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

public App() {
  InitializeComponent();
  MainPage = new AppShell();
  
  OneSignal.Default.Initialize("YOUR_ONESIGNAL_APP_ID");
  OneSignal.Default.PromptForPushNotificationsWithUserResponse();
}

.Net for Android

2.1A Install the OneSignalSDK.DotNet NuGet package in the Android project.
2.2A Initialize OneSignal in MainActivity.cs inside the OnCreate method.

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

protected override void OnCreate(Bundle savedInstanceState) {
  base.OnCreate(savedInstanceState);

  //... Leave the existing code here

  OneSignal.Default.Initialize("YOUR_ONESIGNAL_APP_ID");
  OneSignal.Default.PromptForPushNotificationsWithUserResponse();
}

.Net for iOS

2.1B Install the OneSignalSDK.DotNet NuGet package in the iOS project.
2.2B Initialize OneSignal in AppDelegate.cs inside the FinishedLaunching method.

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

public override bool FinishedLaunching(UIApplication app, NSDictionary options) {
  //... Leave existing code here

  OneSignal.Default.Initialize("YOUR_ONESIGNAL_APP_ID");
  OneSignal.Default.PromptForPushNotificationsWithUserResponse();

  return base.FinishedLaunching(app, options);
}

Step 3A – Android Project Setup

3A.1 Open the Android project properties by context-clicking on the project and selecting properties.
3A.2 Select Build > Android Application and set Target Android version to “Android 13.0 (API level 33)” or later.

18501850

Step 3B – iOS Project Setup

A Notification Service Extention and App Group must be set up to:

  • Display rich media – such as images and UI – in notifications
  • Confirm Delivery of notifications
  • Update Badges through push notifications

🚧

Notification Service Extension Support in MAUI

Notification Service Extensions are not currently supported although there is a workaround; see the example in GitHub

3B.1 Search for “OneSignalSDK.DotNet” and select that package in the list.

18021802

3B.2 Choose Add Packages.
3B.3 Replace the source code in NotificationService.cs with the following

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

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

      (OneSignal.Default as OneSignalImplementation).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.

      (OneSignal.Default as OneSignalImplementation).ServiceExtensionTimeWillExpireRequest(ReceivedRequest, BestAttemptContent);

      ContentHandler(BestAttemptContent);
    }
  }
}

3B.4 Open info.plist inside the OneSignalNotificationServiceExtension project and ensure the deployment target is iOS 10 or higher.
3B.5 Enable App Groups by editing Entitlements.plist inside the main app project. Add a new key named com.apple.security.application-groups and set the value to a Group ID of the form “group.{your_bundle_id}.onesignal”.
3B.6 Repeat the previous step for the OneSignalNotificationServiceExtension project, setting the app group to the same value in the main app’s entitlements.

Step 4 – Send Notification

4.1 The iOS Simulator does not support receiving remote push notifications. You’ll need to run your app on a physical device to confirm it builds and runs correctly. Upon the app's first launch, you’ll receive a prompt to accept push notifications if you follow this walkthrough guide.
4.2 Validate that you can view the Device Record on your OneSignal Dashboard: Audience > All Users.
4.3 To send a message, navigate to Messages > New Push in your OneSignal dashboard to Send your first Push Notification.

Optional - Implement a soft-prompt in-app message

We recommend your apps display an alert, modal view, or other UI to describe the type of information you intend to send and give users a straightforward way to opt into future notifications.
We provide an easy option for soft-prompting using In-App Messages, enabling you to ask for permission again since the native permission prompt can no longer be shown in your app if the user chooses not to accept.

See our How to Prompt for Push Permissions with an In-App Message Guide for details on implementing this.

Troubleshooting

We provide a reference implementation of this guide on GitHub. If you run into any issues, please open an issue.