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 three 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 Api
  • Cloud Code Api
  • Cloud Content Delivery Api
  • Cloud Save Data Api
  • Cloud Save Files Api
  • Economy Configuration Api
  • Economy Currencies Api
  • Economy Inventory Api
  • Economy Purchases Api
  • Friends Messaging Api
  • Friends Notifications Api
  • Friends Presence Api
  • Friends Relationships Api
  • Leaderboards Api
  • Lobby Api
  • Matchmaker Tickets Api
  • Player Authentication Api
  • Player Names Api
  • Qos Discovery Api
  • Relay Allocations Api
  • Remote Config Api
  • UGC Api

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 admin game 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 Api
  • Cloud Content Delivery Api
  • Cloud Save Data Api
  • Cloud Save Files Api
  • Economy Configuration Api
  • Economy Currencies Api
  • Economy Inventory Api
  • Economy Purchases Api
  • Leaderboards Api
  • Player Authentication Api

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 Modules Admin Api
  • Cloud Code Scripts Admin Api
  • Cloud Content Delivery Admin Api
  • Cloud Save Data Admin Api
  • Economy Admin Api
  • Environment Admin Api
  • Game Overrides Admin Api
  • Leaderboards Admin Api
  • Logs Admin Api
  • Multiplay Admin Api
  • Player Authentication Admin Api
  • Player Policy Admin Api
  • Project Policy Admin Api
  • RemoteConfig Admin Api
  • Scheduler Admin Api
  • Service Authentication Admin Api
  • Triggers Admin Api
  • UGC Admin Api

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 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.

Async

Operations can be handled using async/await.

	public async Task AnonymousSignupAsync()
	{
		var response = await PlayerAuthentication.AnonymousSignup(ProjectId, new PlayerAuthAnonymousSignupRequestBody
		ProcessResponse(response);
	}

Callback

Operations can be handled by registering callback methods.

	public void OnSignUpCallbackClick()
	{
		var operation = PlayerAuthentication.AnonymousSignup(ProjectId, new PlayerAuthAnonymousSignupRequestBody());
		operation.Register(ProcessResponse);
	}

Coroutine

Operations can be handled in coroutines.

	public void OnSignUpCoroutineClick()
	{
		StartCoroutine(StartSignUp());
	}
	
	public IEnumerator StartSignUp()
	{
		var operation = PlayerAuthentication.AnonymousSignup(ProjectId, new PlayerAuthAnonymousSignupRequestBody());
		yield return new WaitUntil(() => operation.IsCompleted);
		ProcessResponse(operation.Response);
	}

Error Handling

By default, operations do not throw exceptions when they fail. You must look at the

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

By using EnsureSuccessful, you can trigger an exception in cases of error.

	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 apis in editor context
  • Support multiple concurrent players
  • Integration tests with multiple players
  • Extend the cloud service SDK's base functionality

Server Apis

  • Update Player CloudSave Data
  • Update Player Economy Data
  • Submit Player Leaderboard Scores

Trusted

  • Manage Player & Game CloudSave Data
  • Manage Player Leaderboard Scores

Admin Apis

  • Player Management
  • Environment Management
  • Leaderboards Management
  • Access Control Management
  • Configuration Replication