OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Discussions

Xamarin SDK Setup

Instructions for adding the OneSignal Xamarin SDK to your Xamarin app for iOS, Android, and derivatives like Amazon

Required For Setup

  • A OneSignal account, if you do not already have one
  • Your OneSignal App ID, available in Settings > Keys & IDs in the OneSignal dashboard

Generate Credentials

While setting up the Xamarin SDK, you must generate the appropriate credentials for the platform(s) you are releasing on:

The Xamarin OneSignal SDK works for both Xamarin Forms and Xamarin Single View projects.

Setup SDK

1. Add NuGet Package

1.1 Under your Android and/or iOS targets, right-click on Packages, then select Add Packages....

1.2 Search for OneSignalSDK and click Add Package.

2. Add Code

Xamarin Forms Project

2.1A Add the following to your App.xaml.cs.

using Com.OneSignal;
using Com.OneSignal.Abstractions;

public App()
{
  InitializeComponent();
  MainPage = new OneSignalXamarinFormsExamplePage();
  
  //Remove this method to stop OneSignal Debugging  
  OneSignal.Current.SetLogLevel(LOG_LEVEL.VERBOSE, LOG_LEVEL.NONE);
  
  OneSignal.Current.StartInit("YOUR_ONESIGNAL_APP_ID")
  .Settings(new Dictionary<string, bool>() {
    { IOSSettings.kOSSettingsKeyAutoPrompt, false },
    { IOSSettings.kOSSettingsKeyInAppLaunchURL, false } })
  .InFocusDisplaying(OSInFocusDisplayOption.Notification)
  .EndInit();
    
  // The promptForPushNotificationsWithUserResponse function will show the iOS push notification prompt. We recommend removing the following code and instead using an In-App Message to prompt for notification permission (See step 7)
  OneSignal.Current.RegisterForPushNotifications();
}

Xamarin Single View App

2.1B Android - Add OneSignal to your MainActivity.cs in your OnCreate method.

using Com.OneSignal;
using Com.OneSignal.Abstractions;

protected override void OnCreate(Bundle savedInstanceState)
{
  base.OnCreate(savedInstanceState);
  SetContentView(Resource.Layout.Main);
  
  //Remove this method to stop OneSignal Debugging  
  OneSignal.Current.SetLogLevel(LOG_LEVEL.VERBOSE, LOG_LEVEL.NONE);
  
  OneSignal.Current.StartInit("YOUR_ONESIGNAL_APP_ID")
  .Settings(new Dictionary<string, bool>() {
    { IOSSettings.kOSSettingsKeyAutoPrompt, false },
    { IOSSettings.kOSSettingsKeyInAppLaunchURL, false } })
  .InFocusDisplaying(OSInFocusDisplayOption.Notification)
  .EndInit();
    
  // The promptForPushNotificationsWithUserResponse function will show the iOS push notification prompt. We recommend removing the following code and instead using an In-App Message to prompt for notification permission (See step 7)
  OneSignal.Current.RegisterForPushNotifications();
}

2.1B iOS - Add OneSignal to your AppDelegate.cs in your FinishedLaunching method.

using Com.OneSignal;
using Com.OneSignal.Abstractions;

public override bool FinishedLaunching(UIApplication application, NSDictionary launchOptions)
{

  //Remove this method to stop OneSignal Debugging  
  OneSignal.Current.SetLogLevel(LOG_LEVEL.VERBOSE, LOG_LEVEL.NONE);
  
  OneSignal.Current.StartInit("YOUR_ONESIGNAL_APP_ID")
  .Settings(new Dictionary<string, bool>() {
    { IOSSettings.kOSSettingsKeyAutoPrompt, false },
    { IOSSettings.kOSSettingsKeyInAppLaunchURL, false } })
  .InFocusDisplaying(OSInFocusDisplayOption.Notification)
  .EndInit();
    
  // The promptForPushNotificationsWithUserResponse function will show the iOS push notification prompt. We recommend removing the following code and instead using an In-App Message to prompt for notification permission (See step 7)
  OneSignal.Current.RegisterForPushNotifications();

  return true;
}

3. Android Setup

3.1 Add the following permissions to AndroidManifest.xml.

<permission android:name="${manifestApplicationId}.permission.C2D_MESSAGE"
            android:protectionLevel="signature" />
<uses-permission android:name="${manifestApplicationId}.permission.C2D_MESSAGE" />

3.2 In your application tag, add the following.

<application ....>

  <receiver android:name="com.onesignal.GcmBroadcastReceiver"
            android:permission="com.google.android.c2dm.permission.SEND" >
    <intent-filter>
      <action android:name="com.google.android.c2dm.intent.RECEIVE" />
      <category android:name="${manifestApplicationId}" />
    </intent-filter>
  </receiver>
  
</application>

3.3 Replace all 3 of instances of ${manifestApplicationId} with your package name in AndroidManifest.xml.

4. iOS Setup

4.1 In your application's __Info.plist__, verify that your _Bundle Identifier_ matches your App Settings' Bundle ID, and that _Enable Background Modes_ and allow _Remote notifications_ are enabled.

4.2 Under __Entitlements.plist__, enable __Push Notifications__.

5. iOS - Add the Notification Service Extension

In order for your application to display images/buttons on notifications, use Confirmed Deliveries and increment/decrement Badges through push notifications, you'll first need to set up a Notification Service Extension and App Groups.

❗️

Warning

Recent versions of Visual Studio have introduced a bug where the Notification Extension Service will only work correctly when you run in Release mode. If you follow the steps below and images/buttons still do not appear in your push notifications, please make sure you are running in Release mode.

5.1 Right-click on your project solution and click Add > Add New Project.

5.2 Click iOS > Extension > Notification Service Extension and select Next.

5.3 Enter the name OneSignalNotificationServiceExtension and click Next.

🚧

Important

The Bundle ID for this extension should be the same as the Bundle ID for your main application with .OneSignalNotificationServiceExtension added to the end.

For example, if your primary application's Bundle ID is com.example.test, the Bundle ID for your extension should be com.example.test.OneSignalNotificationServiceExtension.

5.4 Click Create to add the extension service to your project.

5.5 Right click on Packages for your new OneSignalNotificationServiceExtension and select Add Packages...

5.6 Enter Com.OneSignal and click Add Package.

5.7 Select the NotificationService.cs source file and replace the contents with this code:

using System;
using Foundation;
using UIKit;
using UserNotifications;
using Com.OneSignal;
using Com.OneSignal.Abstractions;

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.Current as OneSignalImplementation).DidReceiveNotificationExtensionRequest(request, BestAttemptContent);

      ContentHandler(BestAttemptContent);
    }

    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.Current as OneSignalImplementation).ServiceExtensionTimeWillExpireRequest(ReceivedRequest, BestAttemptContent);

      ContentHandler(BestAttemptContent);
    }
  }
}

5.8 Open your extension's Info.plist file, and make sure the deployment target is at least iOS 10 or higher. If your deployment target is higher than the device you attempt to run it on, rich push notifications will not work.

5.9 For your iOS app, select Entitlements.plist and enable App Groups as follows. Please add an app group using your Bundle Identifier - this will be something similar to com.yourcompany.yourapp.

The full name of the app group needs to be in the following format: group.{your_bundle_id}.onesignal:

5.10 Using the exact same app group name you specified above, repeat the same procedure for your OneSignalNotificationServiceExtension, which will have its own Entitlements.plist file:

That's it! Now, your application will be able to display push notification images, action buttons, and more.

6. iOS (Optional) - only required for iOS Simulator builds

The following is required to prevent crashes when using the iOS Simulator.

6.1 Right-click on your iOS project and select Options.

6.2 Select Build > iOS Build, then make sure iPhoneSimulator is selected under Platform at the top.

6.3 Under Additional mtouch arguments: enter --registrar:static.

7. Prompt Your Users to Subscribe (Recommended for iOS)

Apple's Human Interface Guidelines recommend 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 an easy option for a "soft-prompt" using 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 can no longer be shown in your app if the user clicks deny.

See our iOS Push Opt-In Prompt for details on implementing this.


Troubleshooting

If run into any issues please see our Troubleshooting section

Updated 4 months ago



Xamarin SDK Setup


Instructions for adding the OneSignal Xamarin SDK to your Xamarin app for iOS, Android, and derivatives like Amazon

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.