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

Step 1. Requirements

iOS Requirements

  • An iOS 9+ or iPadOS device (iPhone, iPad, iPod Touch) to test on. The Xcode simulator doesn't support push notifications so you must test on a real device.
  • 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/or the Huawei AppGallery.

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

Step 2. Add NuGet Package

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

2.2 Search for OneSignalSDK and click Add Package.

Step 3. Add Code

Xamarin Forms Project

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

3.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)
{
  // ... Leave existing code here
  
  // Remove this method to stop OneSignal Debugging  
  OneSignal.Current.SetLogLevel(LOG_LEVEL.VERBOSE, LOG_LEVEL.NONE);
  
  OneSignal.Current.StartInit("YOUR_ONESIGNAL_APP_ID")
   .InFocusDisplaying(OSInFocusDisplayOption.Notification)
   .EndInit();
}

3.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)
{
  // ... Leave existing code here

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

Step 4. Android Setup

4.1 Add the following permissions to AndroidManifest.xml.

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

4.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="${applicationId}" />
    </intent-filter>
  </receiver>
  
</application>

Step 5. iOS Setup

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

5.2 Under Entitlements.plist, enable Push Notifications.

🚧

Set APS Environment key to Production

Make sure to set the entitlements plist APS Environment key to Production in the iOS app.

Step 6. iOS - Add the Notification Service Extension

To display Rich Media such as images and 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.

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

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

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

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

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

6.6 Enter Com.OneSignal and click Add Package.

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

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

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

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

Step 7. iOS (Optional) - only required for iOS Simulator builds

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

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

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

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

Step 8. Run Your App and Send Yourself a Notification

Run your app on a physical device to make sure it builds correctly. Note that the iOS Simulator does not support receiving remote push notifications.

  • Android devices should be subscribed to push notifications immediately upon opening the app.
  • iOS devices should be prompted to subscribe to push notifications if you used the example setup code provided.

Check your OneSignal Dashboard Audience > All Users to see your Device Record.

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

πŸ“˜

Troubleshooting

If you run into any issues please see our Xamarin troubleshooting guide.

Try the example project 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

Step 9. Prompt Your Users to Subscribe (Recommended for iOS)

Optional

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.

πŸ‘

Setup Complete!

Visit Mobile Push Tutorials for next steps.

Updated 4 days 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.