Services Core SDK API

The Services Core package provides a solution for initializing all Unity Gaming Services with a single call, and defines common components used by multiple packages. These standardized components aim to unify the overall experience of working with Unity Gaming Services packages.

Note: This API is supported in Unity Editor versions 2019.4 and higher.

UnityServices

namespace Unity.Services.Core
{
    public static class UnityServices{}
}

Use this class to initialize all Unity Gaming Services that are currently installed in your project.

InitializeAsync

public static Task InitializeAsync(InitializationOptions options)

This method initializes all Unity Gaming Services that are currently installed in your project. This method returns a Task that allows you to monitor the initialization's progression.

ParameterTypeDescription
optionsInitializationOptionsThis optional parameter acts as a key-value store that can facilitate unique SDK initialization specifications.

Note: This method is only supported at runtime.

State

public static ServicesInitializationState State

This method returns the game’s current ServicesInitializationState at runtime:

ValueDescription
UninitializedUnity Services has not been initialized.
InitializingUnity Services is in the process of initializing.
InitializedUnity Services successfully initialized.

InitializationOptions

namespace Unity.Services.Core 
{
    public class InitializationOptions{}
}

Initialization options act as a key-value store that can facilitate unique SDK initialization specifications. Pass these options through the InitializeAsync method when initializing Unity Gaming Services SDKs.

TryGetOption

public bool TryGetOption(string key, out bool option)
public bool TryGetOption(string key, out int option)
public bool TryGetOption(string key, out float option)
public bool TryGetOption(string key, out string option)

These methods return true for a specified key if any exists, and false if it doesn’t.

ParameterTypeDescription
keystringThe key of the option you want to retrieve.
optionvariousThe stored option associated with that key, if any exists.

SetOption

public InitializationOptions SetOption(string key, bool value)
public InitializationOptions SetOption(string key, int value)
public InitializationOptions SetOption(string key, float value)
public InitializationOptions SetOption(string key, string value)

These methods store the value for a specified key.

ParameterTypeDescription
keystringThe key of the option you want to store.
valuevariousThe stored option associated with that key, if any exists.

Initialization example

The following example initializes all services at once, using the Environments initialization extension:

using System;
using Unity.Services.Core;
using Unity.Services.Core.Environments;
using UnityEngine;
 
public class InitializeUGS : MonoBehaviour {
    
    public string environment = "production";
 
    async void Start() {
        try {
            var options = new InitializationOptions()
                .SetEnvironmentName(environment);
 
            await UnityServices.InitializeAsync(options);
        }
        catch (Exception exception) {
            // An error occurred during initialization.
        }
    }
}

Initialization debugging

In Services Core versions 1.4.2 and higher, you can enable a verbose mode for debugging purposes. After enabling verbose mode, the Services Core SDK will log information about the common configuration shared among all services in the Editor's console. To enable verbose:

  1. In the Unity Editor, select Edit > Project Settings > Player.
  2. In the Player settings window, click Other Settings.
  3. Under Script Compilation, add the following Scripting Define Symbol: ENABLE_UNITY_SERVICES_CORE_VERBOSE_LOGGING.
  4. Click Apply.

Exception types

ServicesInitializationException

A base exception type for errors occurring during service initialization.

CircularDependencyException

An exception that occurs when two registered IInitializablePackage instances depend on each other. This error is a must-fix as it most likely highlights design issues.

RequestFailedException

A base exception type for failed requests. Each exception returns an int ErrorCode to specify the failure reason:

NameCodeDescription
Unknown0Unable to determine the error.
TransportError1DNS, TLS, and other transport errors that result in no valid HTTP response.
Timeout2The request timed out because no response was received in the allotted time.
ServiceUnavailable3The service is unavailable. This typically means the service is overloaded.
ApiMissing4The API does not exist.
RequestRejected5The request was rejected, typically before reaching the API endpoint. See title/details for more information.
TooManyRequests50The request was rate-limited. The client is making requests too frequently.
InvalidToken51The authentication token is malformed or invalid.
TokenExpired52The authentication token is expired.
Forbidden53The user does not have permission to perform the requested operation.
NotFound54The requested resource cannot be found.
InvalidRequest55The request was understood but the API refused to process it because one or more components was invalid.