One of the joys of working on the SDK team is finding better ways to improve our existing technology. And today is one of those days where I get to highlight some of the hard work that our team has been doing to keep the Unity SDK cross-platform compatible. We have a new Beta of the Unity SDK that we will be introducing today (you can find the download info at the end of this blog). It comes with some fantastic improvements, which I will be talking about in this blog post, but some of these great new features come with small upgrade pains. So please bear with with me as I walk you through the new features of the SDK and how to safely upgrade from your previous version to the Beta. And please note that this will be a one time thing - moving from Beta to release will not require any additional work.
Okay, let's dive right in shall we? Below you will find a list of changes that we have made to the Unity SDK.
- [Fix] SimpleJson fixes for IL2CPP & Mono 2.x
- [Fix] Reflection issues are now resolved for all platforms
- [Feature] ISerializer - Allows you to replace the existing JSON serializer with any JSON library of choice
- [Feature] Introduced the IPlayFabHttp wrapper to provide cleaner separation and implementations of the HTTP interfaces (PlayFabHttp, WWW, and HttpWebRequest), as well as enabling mock object usage for testing purposes
- [Update] Android Push plugin removed - now available as a Unity package and are available for Unity 4.7 & 5.0+
- [Feature / Upgrade] Plugins no longer needed for IDFA support
- [Feature / Upgrade] Complete replacement of the underlying event system for simplification and to provide event binding
ISerializer, SimpleJSON & Reflection Issues
While JSON.net for Unity is a very good product which we were able to provide free as part of our SDK previously, this required some extra maintenance work from the JSON.net for Unity team which wasn't really sustainable, so we've elected to move off the JSON.net serializer in order to remove that burden (but you can still purchase it via the Unity Asset Store). Instead, we took the time to evaluate the available JSON serializers and find one that we could integrate and maintain going forward.
As a result, we chose SimpleJson. It is a lightweight, easily maintained library which, while not perfect, does have the key functionality needed - and we will continue to make updates and fixes in that code going forward. But that said, it was still important for us to provide a way to allow developers to continue using JSON.net if they chose to. So with our latest release, we have introduced the ISerializer. Our current SimpleJson serializer is an implementation of ISerializer and with minimal effort you can create your own wrapper for any JSON serializer of choice, including JSON.net.
Before we get into usage examples and what changes you’ll need to make. I wanted to share with you a couple of the benefits that you will gain as a developer. You will get ultimate flexibility on what type of serializer is used in our SDK. In addition, we know that overall file size of your game or application is important. JSON.net is quite a large library, so the overall footprint is smaller using our new SimpleJson solution. The last benefit I want to mention about the new serializer is the added cross platform stability. We know cross platform issues are difficult to deal with and we have gone through great lengths through hard work and testing to ensure that our serializer works on all platforms.
For developers updating projects from an older PlayFab SDK version, there are a couple of changes that you will need to make:
First, the serialization strategy is a different object, so in places were you were making calls like this:
JsonConvert.DeserializeObject<[SomeType]>([string of json], Util.JsonSettings)
You will need to replace those with calls to PlayFab SimpleJson like so:
JsonWrapper.DeserializeObject<[SomeType]>([string of json], Util.ApiSerializerStrategy);
Also if you were using JsonUtils, that is no longer part of the SDK. To update that, you will need to either create your own converters, or do basic type casting. For example, this line:
var bool = JsonUtil.Get<bool>( myBooleanValue.toString() );
Could be re-written like this:
var bool = bool.parse( myBooleanValue.toString() );
But as I said, you can also continue using JSON.net if you prefer, via the ISerializer. To do so, you would:
For other JSON serializers, the ISerializer package for JSON.net can be used as the framework & example for integration of any other library.
Finally, we fixed some issues in switching to the SimpleJson solution that resolved reflection issues with both Mono 2.x and the Windows Phone platform. Due to limited generics support in Mono2.x, and limited support for reflection and generic types in both, we rebuilt the PlayFab Unity SDK from the ground up, replacing generic types that were passed in via Methods with lambda expressions. An example of this would be as shown in this code snippet:
Web Requests Using IPlayFabHttp
The update to IPlayFabHttp allowed us to split out Unity WWW and HttpWebRequest into their own implementations. But it also now provides a way to implement new web request technologies as they are introduced. For example, in Unity 5.2 + added UnityWebRequest, which is not currently supported across all platforms, though it does aim to replace Unity WWW eventually. With that in mind, we felt the need to provide a way to deprecate WWW when its time comes. The IPlayFabHttp wrapper will allow us to do this once UnityWebRequest is ready to become the primary method for making web requests by replacing the wrapped calls, but with zero impact to our project code.
Note that in making IPlayFabHttp, we made some slight changes to the directory structure. Where PlayFabHttp was previously located in PlayFabSDK/Internal, there is now a sub-folder of PlayFabHttp which contains the following files.
Important Upgrade Step:
If you are upgrading from our previous version it is therefore important that you delete the PlayFabSDK directory, and re-import the PlayFabSDK folder. This will prevent any issues with duplicate files or files being left over in the wrong file structure.
For those of you that are really into writing unit tests and load testing, there is a huge benefit to the IPlayFabHttp interface. By creating your own IPlayFabHttp Wrapper you can now Mock the PlayFabAPI Responses without having any external dependencies to PlayFab. This technique allows you to setup test case scenarios without having to perform any complex steps to setup account / player data, ( e.g. Catalogs, CloudScript, TitleData ), for the test scenario.
Finally, we removed the native iOS WebRequests implementation, as this update makes it superfluous.
IDFA, Android Push Notifications, and iOS Plugins Removed
In addition to issues with maintaining backwards compatibility, plugins in Unity have historically been problematic. This is especially true on Android, and while Google recently made the smart decision to allow developers to only include services that they are using, conflicts still tend to occur. For that reason, we have opted to remove some plugins from our base SDK, in order to simplify the development process.
For users of the Android Push Notification plugin, this functionality has moved to a Unity package which you can download and import. As part of this, we made certain to remove all dependencies to the plugin from the SDK, in order to make it a standalone product. To continue using the Android Push plugin, simply import the AndroidPushPlugin.unitypackage appropriate for your Unity version.
As an added bonus, while moving Android Push Notifications out to a separate project, we also updated to use the built-in methods in Unity to obtain the IDFA. The Advertising Identifier (IDFA) is a unique ID for each iOS device that mobile ad networks typically use to serve targeted ads. Users can choose to limit ad tracking by turning off this setting on their devices. Thanks to our update to how we acquire the IDFA Id, there is no longer any need to do anything special to get IDFA working. If you're not using IDFA, of course, you should be sure to disable it in the SDK by setting DISABLE_IDFA in your build settings, in the Scripting Define Symbols section. This is a requirement for passing Apple certification for titles that aren't legitimately using the IDFA for advertising purposes, so it's important to bear in mind.
Last but not least, there is no more iOS plugin at all. Everything for iOS is now accomplished directly within Unity, eliminating the need for the old plugin when building for iOS!
New Event System in Unity SDK
Even though we didn't post about the event system we added to the Unity SDK last spring, we have seen that a number of you did spot it, and started using it. For those of you that did not know about our event system, let me introduce it to you.
What we did was add an underlying C# event system (not to be confused with PlayFab Events) that allows you to subscribe to PlayFab API requests and responses outside of the standard callback system. This is extremely useful for tying into API calls and responses from other systems and modules in your code. It is also really great if you already have an event driven game, but even if you don’t it is still really useful to be able to monitor API responses from two different classes (or monobehaviours) and not have to couple your code by the current callback system.
To use the event system, first create an instance of the event object:
var playFabEvents = PlayFabEvents.Init();
Then bind to one of the available events
playFabEvents.OnLoginResultEvent += OnLogin;
If you're one of those developers that had spotted the previous event system, there are a few changes to the event system that you need to be aware of.
Previously, if you wanted to bind to an event you would do something like:
Now, you can use the event system by creating an event object and then binding your event to a delegate as you normally would:
var playFabEvents = PlayFabEvents.Init();
playFabEvents.OnLoginWithEmailAddressRequestEvent += OnLoginWithEmailRequest;
playFabEvents.OnLoginResultEvent += OnLogin;
This design change reduces the learning curve of using our C# Event system because it is an exact mirror of the C# industry standard of how event delegates work in C#. Also it is important to note that you can still use the normal callbacks within the API signature and we do recommend that usage of the API calls:
PlayFabClientAPI.[API METHOD]( [Request], [Result Callback], [Error Callback]);
However, if you choose to use this event system, you can specify null as your result callback and error callback, allowing you to bind to the events using the event delegates system (as seen below), or use both at the same time.
PlayFabClientAPI.[API METHOD]( [Request], null, null);
Getting the Beta
Getting the beta is very easy. As with all of our SDKs we have uploaded it to a public repository located at: https://github.com/PlayFab/UnitySDKV2Beta once we move the SDK out of Beta, the previous version of our SDK will be deprecated and we will drop beta off the repository name. Once we deprecate the old Unity SDK, we will still maintain updates to it to keep the API up to date, but we urge everyone to move off of it and onto our new SDK as any new features will only go into the V2 version.
It has been a lot of fun refactoring the Unity SDK and it has certainly opened up some doors for us in what we can do with the SDK moving forward. Stay tuned in the upcoming weeks as we plan to release some new and exciting tech revolving around the Unity SDK, Editor Extensions for PlayFab and more.