Azure Event Hubs SDK for Unity 2017

Article
11/26/2017

Note

This is a Sandbox project. The content in this article is unsupported, and therefore may be out of date or not in a working state. That said, we still think it was awesome enough to include here. Enjoy!

Important

This is an experimental Unity SDK for Azure Event Hubs. As such, please note that this SDK is not supported and is not provided by the Azure Event Hubs team. If you run into problems, please let us know using the GitHub Issues page for this fork.

Azure Event Hubs for Gaming

Azure Event Hubs is a real-time custom event ingestion service that can collect and store millions of events per second. Events can then be analyzed in real-time using Azure Stream Analytics or stored to Azure Storage or Azure Data Lake Store for processing at a later time. Analysis of this data could reveal various insights about player's performance/behavior during the game as well as be utilized in creation of other types of metrics (e.g. daily/weekly/monthly active users, churn, user sessions, transactions etc.).

Requirements

Unity 2017.1 (or greater)
- Unity 2017.1 includes a new scripting runtime that supports .NET 4.6. This feature allows us to use the existing Azure SDKs with some tweaks. Please see this blog post from Unity for more information.
An Azure Event Hubs account (Sign up for free!)

Compatibility

This has been tested with the following Unity exporters. Others may work -- we haven't tested every platform, so please let us know if you've had success!

Windows Standalone
Mac Standalone (with Unity 2017.2.0p3)
UWP (.NET)
Android (Mono)
Unity Editor
iOS (the link.xml file in the Assets sample folder works around an IL2CPP issue dealing with bytecode stripping)

Known Issues and Limitations

There are a few known issues and workarounds.

Unity and SSL support

Warning

Due to a Unity limitation, HTTPS requests using the standard .NET networking stack (i.e. not using UnityWebRequest) will fail due to Mono's empty certificate store. To workaround this, you will need to modify the ServicePointManager.CertificatePolicy with a custom CertificatePolicy which will accept all certificates as shown.

This means that data transfer will happen in an insecure manner.

    public class CustomCertificatePolicy : ICertificatePolicy
    {
        public bool CheckValidationResult(ServicePoint sp,
            X509Certificate certificate, WebRequest request, int error)
        {
            return true;
        }
    }

    //...

    ServicePointManager.CertificatePolicy = new CustomCertificatePolicy();

iOS Builds

If you hit the known issue where Unity iOS exports fail with an error of:

IL2CPP error for method 'System.Void System.Data.ConstraintCollection::Clear()'

...please update to Unity 2017.3, 2017.2.0p2, or 2017.1.1p2 (or higher).

UWP Builds

To build for UWP, ensure that the DLLs in the root Plugins directory are excluded from the build, while the DLLs in the WSA directory are included in the build. To do this:

In the Project window, select all DLLs that are in the root Plugins\<SDK> directory (note that the DLLs and SDK directory name will vary based on the SDK).
In the Inspector window at the right, make sure both Any Platform and WSAPlayer are not selected.
In the Project window, select all DLLs that are in the root Plugins\<SDK>\WSA directory (note that the DLLs and SDK directory name will vary based on the SDK).
In the Inspector window at the right, make sure Any Platform is not selected and WSAPlayer is selected.

With these selections, you should be able to export your UWP build without issue. To go back to building for another platform, reverse the process -- make sure both Any Platform and WSAPlayer are selected and then export.

Other Platforms

We have not had success in compiling or running games using the following platforms:

UWP (IL2CPP)
Android (IL2CPP)
WebGL - System.Threading is used in Event Hubs DLLs and Unity WebGL does not support this

We will continue working on these and update the documentation as soon as we find fixes.

Import the SDK

To import the SDK into your own project, make sure you have downloaded the latest .unitypackage from GitHub. Then, do the following:

Open Unity and select Edit > Project Settings > Player to open the PlayerSettings panel.
Select Experimental (.NET 4.6 Equivalent) from the Scripting Runtime Version dropdown in the Configuration section.
Add the .unitypackage you downloaded in the first step to Unity by using the Assets > Import Package > Custom Package menu option.
In the Import Unity Package box that pops up, you can select which things you'd like to import. By default everything will be selected. If you don't care to use the sample, you can uncheck that box.
Click the Import button to add the items to your project.

With the package added, you can now use the normal API in your scripts as you would in any other application. Please take a look at the corresponding sample (also included in each .unitypackage) which demonstrates how to use each of the services to perform simple tasks.

Please refer to the Azure Event Hubs Docs for even more samples and tutorials on using the API.

Try the Sample

To use the sample, you will need to have an Azure Event Hubs account with a valid Event Hubs connection string. You'll also need to create an event hub on this account. You can check the Event Hubs documentation here to understand how to complete this task.

To use the sample, do the following:

Download the Unity SDKs repo from GitHub (or import it from the .unitypackage and continue to step 4).
Unzip to a location on your hard drive.
Open Unity 2017.1 (or greater) and point it to the EventHubs directory inside the unzipped package.
In the Project window, double-click the EventHub scene inside the Assets\AzureSamples\EventHubs directory to open the main scene for the sample.
In this scene, select the EventHubsObject item in the Hierarchy window.
With EventHubsObject selected, you'll notice that there are two blank entries in the Inspector window, called Eh Connection String and Eh Entity Path. Fill in these entries with your own Event Hubs connection string and Event Hub name, respectively. You can find them both in the Azure Portal as shown below.
Run the project from within the Unity Editor by clicking the Play button. Alternatively, you can export to the platform of your choosing and run there.
To test that the events you are sending are correctly arriving to your Event Hubs account, you can use Event Hubs capture and monitor your Storage/Data Lake Store account. Alternatively, you can create a simple .NET console app with a class that implements the IEventProcessor interface, like the one described here.

Share via