Unity Cloud Services APIs

This package provides low-level access to Unity Cloud Services APIs. This includes Game, Server, Trusted, and Admin APIs.

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

CAUTION The Unity Cloud Services APIs package is experimental. APIs are generated based on the OpenAPI Specifications, which are subject to change and 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

You can use the following APIs for various use cases:

Editor Tooling
Game Server Logic
Game Client Logic

Game API client

You can use the Game API client 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 sign ins.
SignInWithSessionToken
- This uses a session token to authenticate.
SignInWithExternalToken
- This uses a token from an external identity provider to authenticate.

API list

List of available APIs:

Analytics
Cloud Code
Cloud Save Data
Cloud Save Files
Economy Configuration
Economy Currencies
Economy Inventory
Economy Purchases
Leaderboards
Lobby
Player Authentication
Player Names
Qos Discovery
Relay Allocations
Remote Config

Server API client

You can use the Server API client to perform game operations using an access token obtained with service account or obtained from a server.

Availability

The following preprocessor directives determine the availability of the Server API client:

UNITY_EDITOR
UNITY_SERVER
ENABLE_SERVER_APIS

CAUTION Never publish game clients with ENABLE_SERVER_APIS enabled. These are intended for dedicated server builds or tooling.

Authorization

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

API list

List of available APIs:

Cloud Code
Cloud Save Data
Cloud Save Files
Economy Configuration
Economy Currencies
Economy Inventory
Economy Purchases
Leaderboards
Lobby
Player Names

Trusted API client

You can use the Trusted API client to perform game operations using an access token obtained with service account.

Availability

The following preprocessor directives determine the availability of the Trusted API client:

UNITY_EDITOR
ENABLE_RUNTIME_TRUSTED_APIS

CAUTION Never publish game clients with ENABLE_RUNTIME_TRUSTED_APIS enabled. These are intended for dedicated server builds or tooling.

Authorization

SignInWithServiceAccount
- This exchanges service account credentials for an access token, which is used by the trusted APIs.

API list

List of available APIs:

Cloud Code
Cloud Save Data
Cloud Save Files
Economy Configuration
Economy Currencies
Economy Inventory
Economy Purchases
Leaderboards
Lobby
Multiplay Allocations
Multiplay Fleets
Player Authentication
Player Names

Admin API client

You can use the Admin API client 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:

UNITY_EDITOR
ENABLE_RUNTIME_ADMIN_APIS

CAUTION Never publish game clients with ENABLE_RUNTIME_ADMIN_APIS enabled.

Authorization

Admin APIs use service account credentials to authorize operations.

SetServiceAccount(string apiKey, string apiSecret)

API list

List of available APIs:

Cloud Code Modules
Cloud Code Scripts
Cloud Save Data
Cloud Save Files
Economy
Environment
Remote Config
Remote Config Schemas
Game Overrides
Leaderboards
Logs
Player Authentication
Player Policy
Project Policy
Player Authentication
Player Policy
Project Policy
Scheduler
Service Authentication
Triggers

Service accounts and security

Make sure that you take any necessary precautions 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.

You can also create the provided API client implementation with a custom retry policy.

Operation handling

API operations can be handled in the following ways:

Using Tasks
Using Callbacks
Using Co-routines

Tasks

Operations can be handled using async and await.

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

Callbacks

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 Cloud Save 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, and game Cloud Save data and files.
Manage your players Economy inventories.
Manage your players Leaderboard scores.

Admin APIs

Player Management.
Environment Management.
Leaderboards Management.
Access Policy 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

Apple Privacy Manifest Guidance

When integrating Apple's privacy manifests with your Unity project, it's crucial to include only the manifests corresponding to the specific services of the APIs you are using. This ensures that your project maintains compliance with Apple's privacy requirements without inflating your project with unused manifests. The APIs package contains the privacy manifest of all the services from which it makes APIs available and it doesn't automatically add their privacy manifests into your project, so make sure to manually add them.

Step-By-Step Guidelines

The following steps provide guidance on how to include the Apple privacy manifests for your specific usage of this package:

Identify the services in use (Runtime only).

Review the APIs that your project is using from this package and which services they belongs to. For example, if you are using CloudCodeApi, it belongs to the Cloud Code package.

Locate the corresponding privacy manifests.

Each service has a corresponding privacy manifest. For example, if you are using APIs made available from Cloud Code and Remote Config services, you must focus on the privacy manifests specific to those packages. All packages manifests are found inside the folder Runtime\PrivacyManifests~.

Copy the relevant manifests into your assets folder.

For each service you are using (through the APIs), locate its privacy manifest file and copy it into your Unity project's Assets folder. For example, if you are using APIs from Cloud Code and Remote Config services, you should copy both CloudCode.xcprivacy and RemoteConfig.xcprivacy into your Assets folder.
Ensure that you do not include the privacy manifests for services that you are not using in your Assets folder. This keeps your project streamlined and avoids unnecessary declarations.