Unity Cloud Services APIs

This package provides low-level access to Unity Cloud Services APIs.

This includes game and admin APIs.

See https://services.docs.unity.com/ for more information on all APIs.

CAUTION This package is experimental. APIs are generated based on the open api specifications. The specifications are subject to change which may lead to breaking changes.

API Clients

The APIs are offered through four clients:

  • Game Client: To perform game operations as a player.
  • Server Client: To perform game operations from a server using a server token or service account exchange token.
  • Trusted Client: To perform game operations as a trusted user using service account exchange token.
  • Admin Client: To perform administration operations.

Use Cases

These APIs can be used for various use cases:

  • Editor Tooling
  • Game Server Logic
  • Game Client Logic

Game API Client

The Game API Client can be used to build your own custom runtime solutions.

Availability

The game APIs are always available.

Authorization

  • SignUpAnonymously
    • This creates an account and returns a session token for future logins.
  • SignInWithSessionToken
    • This uses a session token to authenticate.
  • SignInWithExternalToken
    • This uses a token from an external identity provider to authenticate.

API List

List of APIs available:

  • Analytics
  • Cloud Code
  • Cloud Content Delivery
  • Cloud Save Data
  • Cloud Save Files
  • Economy
  • Friends
  • Leaderboards
  • Lobby
  • Matchmaker
  • Player Authentication
  • Player Names
  • Qos Discovery
  • Relay Allocations
  • Remote Config
  • UGC

Server Api Client

The Server API Client can be used to perform game operations using an access token obtained with service account or obtained from a server.

API List

List of APIs available:

  • Cloud Code Api
  • Cloud Save Data Api
  • Cloud Save Files Api
  • Economy Configuration Api
  • Economy Currencies Api
  • Economy Inventory Api
  • Economy Purchases Api
  • Leaderboards Api
  • Lobby Api
  • Matchmaker Backfill Api
  • Matchmaker Tickets Api

Availability

The following preprocessor directives determine the availability of the trusted API client (any of):

  • UNITY_EDITOR
  • UNITY_SERVER
  • ENABLE_SERVER_APIS

CAUTION Never publish game clients with ENABLE_SERVER_APIS enabled.

Authorization

  • SignInWithServiceAccount
    • This exchanges service account credentials for an access token which will be used by the trusted APIs.
  • SignInFromServer
    • This uses a local proxy running on the server host to retrieve an access token. Only usable when hosted on Multiplay or when using a local proxy during development.

Trusted API Client

The Trusted API client can be used to perform game operations using an access token obtained with service account.

API List

List of APIs available:

  • Cloud Code
  • Cloud Content Delivery
  • Cloud Save
  • Economy
  • Leaderboards
  • Player Authentication
  • Player Names

Availability

The following preprocessor directives determine the availability of the admin game API client (any of):

  • UNITY_EDITOR
  • ENABLE_RUNTIME_TRUSTED_APIS

CAUTION Never publish game clients with ENABLE_RUNTIME_TRUSTED_APIS enabled.

Authorization

  • SignInWithServiceAccount
    • This exchanges service account credentials for an access token which will be used by the trusted APIs.

Admin API Client

The Admin API Client can be used to build custom tooling in management context like in the Unity Editor.

Availability

The following preprocessor directives determine the availability of the admin API client (any of):

  • UNITY_EDITOR
  • ENABLE_RUNTIME_ADMIN_APIS

CAUTION Never publish game clients with ENABLE_RUNTIME_ADMIN_APIS enabled.

API List

List of APIs available:

  • Cloud Code
  • Cloud Content Delivery
  • Cloud Save
  • Economy
  • Environment
  • Game Overrides
  • Leaderboards
  • Logs
  • Multiplay
  • Player Authentication
  • Player Policy
  • Project Policy
  • RemoteConfig
  • Scheduler
  • Service Authentication
  • Triggers
  • UGC

Authorization

Admin APIs use service account credentials to authorize operations.

  • SetServiceAccount(string apiKey, string apiSecret)

Service Accounts and Security

Precautions must be taken when using service accounts to avoid leaking service account information.

CAUTION Service account information should never appear in the published versions of your games.

Overrides

For more control, you can pass a Custom API Client implementation when creating the clients.

The provided api client implementation can also be created with a custom retry policy.

Operation Handling

API operations can be handled in many ways.

Tasks

Operations can be handled using async/await.

	async Task SignUpAsync()
	{
		var client = ApiService.CreateGameClient();
		var response = await client.SignUpAnonymously("project_id", "environment");
		Debug.Log($"IsSuccessful: {response.IsSuccessful}");
	};

Events

Operations can be handled by registering callback methods.

	void SignUp()
	{
		var client = ApiService.CreateGameClient();
		var operation = client.SignUpAnonymously("project_id", "environment_name");
		operation.Completed += (response) =>
		{
			Debug.Log($"IsSuccessful: {response.IsSuccessful}");
		}
	}

Coroutine

Operations can be handled in coroutines.

	IEnumerator SignUp()
	{
		var client = ApiService.CreateGameClient();
		var operation = client.SignUpAnonymously("project_id", "environment_name");
		yield return operation.WaitForCompletion();
		Debug.Log($"IsSuccessful: {operation.Response.IsSuccessful}");
	}

Error Handling

Operations do not throw exceptions when they fail. You can check the state of an operation's response with IsSuccessful().

	public async Task AnonymousSignupAsync()
	{
		var response = await PlayerAuthentication.AnonymousSignup(ProjectId, new PlayerAuthAnonymousSignupRequestBody());
		
		if (response.IsSuccessful)
		{
			// Success Logic
		}
		else
		{
			// Error Logic
		}
	}

You can trigger an exception in cases of error by using EnsureSuccessful(), .

	public async Task AnonymousSignupAsync()
	{
		try
		{ 
			var response = await PlayerAuthentication.AnonymousSignup(ProjectId, new PlayerAuthAnonymousSignupRequestBody());
			response.EnsureSuccessful();			
			// Success Logic
		}
		catch (ApiException exception)
		{
			// Error Logic
		}
	}

Usage Examples

Game APIs

  • Use game operations in editor context
  • Integration tests with multiple players
  • Extend beyond the base functionality or cloud SDKs

Server APIs

  • Update Player CloudSave Data from a server
  • Update Player Economy Data from a server
  • Submit Player Leaderboard Scores from a server
  • Iterate on a local server before moving to Multiplay dedicated servers

Trusted APIs

  • Manage your players & game Cloud Save Data & Files
  • Manage your players Economy Inventories
  • Manage your players Leaderboard Scores

Admin APIs

  • Player Management
  • Environment Management
  • Leaderboards Management
  • Access Control Management
  • Configuration Replication across projects and environments

Couch Coop

  • Represent multiple players concurrently in the same app.

Customer Support

  • Build a unity app for customer support offering a tailored and safe interface