JourneysUsersSDKIntegrations
Log InSign Up

.NET MAUI SDK Setup

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

Suggest Edits

Requirements

iOS Requirements

Android Requirements

Amazon & Huawei Requirements

Setup

1. Add SDK

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

Choose Add Packages.

2. Initialization

.NET MAUI

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

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

.Net for Android

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

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

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

  //... Leave the existing code here

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

  // OneSignal Initialization
  OneSignal.Initialize("YOUR_ONESIGNAL_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);
}

.Net for iOS

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

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

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

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

  // OneSignal Initialization
  OneSignal.Initialize("YOUR_ONESIGNAL_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);

  return base.FinishedLaunching(app, options);
}

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

📘

iOS Bundle ID

The Bundle ID for the service extension must use the Bundle ID of the main application with “.OneSignalNotificationServiceExtension” appended (e.g., if the main application Bundle ID is com.example.test, then the Bundle ID for the NSE will be com.example.test.OneSignalNotificationServiceExtension)

Find the extension project in Solution Explorer, context-click Dependencies, and choose Manage NuGet Packages…

Choose "nuget.org" as the Package source in the bottom left corner of the dialog.

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

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

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

Open info.plist inside the OneSignalNotificationServiceExtension project and ensure the deployment target is iOS 10 or higher.

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

Repeat the previous step for the OneSignalNotificationServiceExtension project, setting the app group to the same value in the main app’s entitlements.

3. Testing

Run your app on a physical device to make sure it builds correctly.

If you used the provided code, then the RequestPermissionAsync method, should prompt you to subscribe to push notifications. You can change this later.

Check your OneSignal Dashboard Audience > Subscriptions to see your User & Subscription Record.

Then head over to Messages > New Push to Send your first Push Notification from OneSignal.

Please note that Identity Verification is coming soon to v5 of the .NET MAUI SDK.

📘

Troubleshooting

If running into issues, see our Mobile Troubleshooting Guide.

Try our example projects on our Github repository.

If stuck, contact support directly or email [email protected] for help.

For faster assistance, please provide:

  • Your OneSignal App ID
  • Details, logs, and/or screenshots of the issue.
  • Steps to reproduce

Recommended

Push permission with In-App Message

You can continue to opt-in users to push via the RequestPermissionAsync method. However, Apple's Human Interface Guidelines recommends that apps "Create an alert, modal view, or other interface that describes the types of information they want to send and gives people a clear way to opt in or out."

OneSignal provides In-App Messages to meet this recommendation and have a better user experience. This also permits you to ask for permission again in the future, since the native permission prompt is limited to how many times it can show and cannot be shown again if the user clicks deny.

See How to Prompt for Push Permissions with In-App Messages for details on implementing this.

Identify Users

Required if using integrations.
Recommended for messaging across multiple channels (push, email, sms).

OneSignal creates subscription-level records under a unique ID called the subscription_id. A single user can have multiple subscription_id records based on how many devices, email addresses, and phone numbers they use to interact with your app.

If your app has its own login system to track users, call login at any time to link all channels to a single user. For more details, see Aliases & External ID.

Set Email & Phone Number

Recommended for messaging across multiple channels (push, email, sms).

Use the provided SDK methods to capture one or more email/phone numbers for the user. Follow the channel quickstart guides for setup:

Add Data Tags

Optional

Tags are custom key : value pairs of String data used for tracking user events and properties. Setting tags is required for more complex segmentation and message personalization.

Updated 15 days ago