Guides
Log InSign Up

Step-by-Step Xamarin 3.x to 4.0.0 Upgrade Guide

Suggest Edits

Step 1 - Requirements

This guide assumes that the app has a setup for Xamarin SDK version 3.x.x and the attempt is to migrate to 4.0.0 major version

❗️

Warning

Building for iOS using Xamarin.iOS 15.4 or below may cause release build issues. Either upgrade to Xamarin.iOS 15.4+ or change the iOS project's Linker Behavior to 'Don't Link'

Step 2 - Update to Version 4

Major release version

🚧

OneSignal SDK namespace and NuGet package name and has been changed from Com.OneSignal to OneSignalSDK.Xamarin

Updating the previous release versions with the namespace Com.OneSignal will not update the package to version 4. Please remove packages with the package name Com.OneSignal and add the OneSignal SDK package with package name OneSignalSDK.Xamarin using the steps below.

  1. In the Solution window, drop down the app project, and find the Dependencies folder.
  2. Right-click the Dependencies folder and select Manage NuGet packages
  3. Remove any packages with the id Com.OneSignal
  4. In the NuGet package window, make sure the Package Source on the bottom bar of the window is set to nuget.org .
  5. Search for OneSignalSDK.Xamarin under the Browse tab and select the OneSignalSDK.Xamarin package. Here the version can be selected to 4.0.0 and then select Add package
  6. Follow the steps above for each project in the solution having Com.OneSignal under its NuGet dependencies. These may include - iOS app project, Android app project or the shared app project.
902

Step 3 - Namespaces

🚧

The Com.OneSignal and Com.OneSignal.Abstractions have been moved to OneSignalSDK.Xamarin and OneSignalSDK.Xamarin.Core.

Step 4 - Update Initialization Code

  1. Open your main app file
  2. Remove the following OneSignal initialization code
OneSignal.Current.StartInit("YOUR_ONESIGNAL_APP_ID")
  .Settings(new Dictionary<string, bool>() {
    { IOSSettings.kOSSettingsKeyAutoPrompt, false },
    { IOSSettings.kOSSettingsKeyInAppLaunchURL, false } })
  .InFocusDisplaying(OSInFocusDisplayOption.Notification)
  .EndInit();
  1. Add the new initialization code
// OneSignal Initialization
OneSignal.Default.Initialize("YOUR_ONESIGNAL_APP_ID");
  1. For any init settings you had previously, note that:
    • IOSSettings.kOSSettingsKeyAutoPrompt - has been removed and no longer needed, instead prompt the user by calling promptForPushNotificationsWithUserResponse().
    • InFocusDisplaying - is replaced by adding NotificationWillShow (see below).
    • OneSignal.kOSSettingsInAppLaunchURL - is deprecated. There is currently no replacement for it.

Step 5 - OneSignal.Default instance

The accessor to OneSignal.Current has been changed to OneSignal.Default.

  • Find and replace on OneSignal.Current with OneSignal.Default.

Step 6 - Android - AndroidManifest.xml changes

Remove the following from your AndroidManifest.xml

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

Step 7 - Update Event Listeners

The new and updated Event Listeners can be implemented as demonstrated below

  1. Notification events and listeners
void Start() {
	...
	OneSignal.Default.NotificationOpened   += _notificationOpened;
	OneSignal.Default.NotificationWillShow += _notificationReceived;
}

private void _notificationOpened(NotificationOpenedResult result) {
	//Response to Notification Opened Result
}

private Notification _notificationReceived(Notification notification) {
	//Response to Notification Received Event
	return notification; // show the notification
}
  1. In App Messages events and Listeners
void Start() {
  ...
  OneSignal.Default.InAppMessageWillDisplay += _iamWillDisplay;
  OneSignal.Default.InAppMessageDidDisplay += _iamDidDisplay;
  OneSignal.Default.InAppMessageWillDismiss += _iamWillDismiss;
  OneSignal.Default.InAppMessageDidDismiss += _iamDidDismiss;
  OneSignal.Default.InAppMessageTriggeredAction += _iamTriggeredAction;
}

private void _iamWillDisplay(InAppMessage inAppMessage) {
  //Response to IAM Will Display Event
}

private void _iamDidDisplay(InAppMessage inAppMessage) {
  //Response to IAM Did Display Event
}

private void _iamWillDismiss(InAppMessage inAppMessage) {
  //Response to IAM Will Dismiss Event
}

private void _iamDidDismiss(InAppMessage inAppMessage) {
  //Response to IAM Did Dismiss Event
}

private void _iamTriggeredAction(InAppMessageAction inAppMessageAction) {
  //Response to IAM Triggered Action
}
  1. State Change Listeners
void Start() {
  ...
  OneSignal.Default.PermissionStateChanged        += _permissionStateChanged;
  OneSignal.Default.PushSubscriptionStateChanged  += _pushStateChanged;
  OneSignal.Default.EmailSubscriptionStateChanged += _emailStateChanged;
  OneSignal.Default.SMSSubscriptionStateChanged   += _smsStateChanged;
}

private void _permissionStateChanged(PermissionState current, PermissionState previous) {
  //Response to Permission State Change
}

private void _pushStateChanged(PushSubscriptionState current, PushSubscriptionState previous) {
  //Response to Push State Change
}

private void _emailStateChanged(EmailSubscriptionState current, EmailSubscriptionState previous) {
  //Response to Email State Change
}

private void _smsStateChanged(SMSSubscriptionState current, SMSSubscriptionState previous) {
  //Response to SMS State Change
}

Step 8 - Review Full List

✅ You're setup with the new SDK!
Please review the full 4.0 API Reference - Xamarin for a full list of new and deprecated features as well as other advanced features you may need to migrate as well.

Updated over 2 years ago