Getting Started with the C# SDK

Overview of the EOS C# SDK.

Overview

Design Philosophy

The C# SDK allows for applications built with .NET to easily interact with Epic online services. It differs from the native SDK primarily in that it has been streamlined to adopt C# best practices while following a more object oriented approach.

Interfaces

Modular, service-specific interfaces group supported features together. For example, the Auth interface handles authenticating user credentials within Epic's ecosystem, the Friends interface handles everything related to your friends list, and so on.

Naming Conventions

All EOS SDK interfaces use consistent naming conventions to help communicate usage and intent. In C#, names have been logically transformed to better suit C# usage, but directly correlate with their native counterparts. For example, the function EOS_Auth_Login is now accessible under Epic.OnlineServices.Auth.AuthInterface.Login.

Handles

In the native SDK, interface usage is driven by opaque handles. Under the hood, this is no different in C#, but for the sake of simplifying usage, they have been hidden such that you are dealing with instances of interfaces rather than the handles themselves.

Function Signatures

Every function in the SDK has a very similar signature. Function parameters follow a predictable pattern. Usually, the first parameter provides a set of options for the operation. In the native SDK, each options structure must be provided with an API version, but this is not required in the C# SDK where it is automatically provided. Functions which take a callback will also accept user-defined context information for processing. The callback will always be invoked whether the operation succeeds or fails, and may also run in response to delays caused by connectivity issues.

Error Handling

Some functions return an Epic.OnlineServices.Result indicating the state of the requested operation. Similarly, callbacks usually return a result code in their returned info, so be sure to make use of these codes to ensure operations complete as you expect.

Releasing Memory

Instances of certain types that are received via out parameters, such as Epic.OnlineServices.Presence.PresenceModification, have an indefinite lifetime due to the nature of their usage. They contain a Release method which must be called when you are finished with them to prevent leaks in the SDK.

Getting Started

Setting Up an Account

Before you begin, you'll need to set up a developer account and download the SDK. The Developer Portal contains setup information about your products. Each product has a Product ID and a Sandbox ID. These will be passed into the SDK to identify your product with the backend services.

Integration

Include the source files in your project, and ensure the native dll is placed in a location where it is accessible by your built application. Your project will fail to build unless you have set the appropriate compilation symbol for your target architecture. If targeting x64, you must set PLATFORM_64BITS, and if targeting x86, you must set PLATFORM_32BITS.

Unity Integration

  1. Add a define symbol to Player Settings for your target architecture - PLATFORM_32BITS for x86, or PLATFORM_64BITS for x64. The wrapper will fail to build without this.

Configuration

  1. Copy the source files into the Assets folder. You must include both the Core and Generated folders.

  2. Copy the appropriate DLL into the Assets folder for your target architecture. I.e. for x64, include EOSSDK-Win64-Shipping.dll.

  3. Create a new script to control the SDK, for example EOSSDKComponent.

New script Component

  1. Add the component on to an entity so it will be created when needed. You can add it to the Main Camera for testing.

Add component

  1. Write SDK code in the component.

    1. You can perform the following functions inside Start():

      • Epic.OnlineServices.Platform.PlatformInterface.Initialize

      • Epic.OnlineServices.Platform.PlatformInterface.Create

      • Epic.OnlineServices.Auth.AuthInterface.Login

    2. You can perform Epic.OnlineServices.Platform.PlatformInterface.Tick inside Update() every 100ms.

Initializing and Cleaning Up the SDK

First, you must call Epic.OnlineServices.Platform.PlatformInterface.Initialize with some basic information about your application, then call Epic.OnlineServices.Platform.PlatformInterface.Create to get an instance of the Epic.OnlineServices.Platform.PlatformInterface. You must store and use this instance for as long as you intend to keep interacting with online services. This instance provides access to other interfaces in the SDK. For example, you can retrieve an Epic.OnlineServices.Auth.AuthInterface by calling Epic.OnlineServices.Platform.PlatformInterface.GetAuthInterface.

You must call Epic.OnlineServices.Platform.PlatformInterface.Tick on a regular interval, for example every 100 milliseconds.

When you are finished, make sure to call Epic.OnlineServices.Platform.PlatformInterface.Release so that the SDK is given adequate time to clean up the platform, then finally call Epic.OnlineServices.Platform.PlatformInterface.Shutdown to indicate that the SDK is no longer needed.

Trying Out the Sample

Samples have been provided which demonstrate the use of various features of the SDK. A WPF sample showcases how authentication and user presence works, and another sample demonstrates how to initiate a purchasing flow using an in-game overlay.

Examples

Setting Up the Platform

var initializeOptions = new Epic.OnlineServices.Platform.InitializeOptions();
initializeOptions.ProductName = "MyCSharpApplication";
initializeOptions.ProductVersion = "1.0";
Epic.OnlineServices.Result result = Epic.OnlineServices.Platform.PlatformInterface.Initialize(initializeOptions);
if (result != Epic.OnlineServices.Result.Success)
{
    throw new Exception("Failed to initialize platform");
}

var clientCredentials = new Epic.OnlineServices.Platform.ClientCredentials();
clientCredentials.ClientId = "my client id";
clientCredentials.ClientSecret = "my client secret";

var options = new Epic.OnlineServices.Platform.Options();
options.ClientCredentials = clientCredentials;
options.ProductId = "my product id";
options.SandboxId = "my sandbox id";
options.DeploymentId = "my deployment id";

var platformInterface = Epic.OnlineServices.Platform.PlatformInterface.Create(options);
if (platformInterface == null)
{
    throw new Exception("Failed to create platform");
}

Logging In

var authInterface = platformInterface.GetAuthInterface();
if (authInterface == null)
{
    throw new Exception("Failed to get auth interface");
}

var credentials = new Epic.OnlineServices.Auth.Credentials();
credentials.Type = LoginCredentialType.AccountPortal;

var loginOptions = new Epic.OnlineServices.Auth.LoginOptions();
loginOptions.Credentials = credentials;
loginOptions.ScopeFlags = Epic.OnlineServices.Auth.AuthScopeFlags.BasicProfile | Epic.OnlineServices.Auth.AuthScopeFlags.FriendsList | Epic.OnlineServices.Auth.AuthScopeFlags.Presence;

authInterface.Login(loginOptions, null, (Epic.OnlineServices.Auth.LoginCallbackInfo callbackInfo) =>
{
    if (callbackInfo.ResultCode == Epic.OnlineServices.Result.Success)
    {
        // We logged in!
    }
});