Unity Gaming Services

https://docs.unity.com/en-us/services
Admin
Unity Gaming Services provides cloud-based tools and backend infrastructure to help developers...
Tokens:212,096
Snippets:2,186
Trust Score:10
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Set up the Unity Authentication service - JSON response example

Source: https://docs.unity.com/en-us/services-web-apis/client-auth

Example JSON response from the Unity Authentication service setup, showing user ID, tokens, and external IDs.

```json
{
    "userId": "WIIXBaxb5g1Y5ZPwbZErapmbOcTl",
    "idToken": "",
    "sessionToken": "",
    "expiresIn": 0,
    "user": {
        "id": "WIIXBaxb5g1Y5ZPwbZErapmbOcTl",
        "disabled": false,
        "externalIds": [
            {
                "providerId": "<Id Provider>",
                "externalId": "<External Id>"
            }
        ]
    }
}
```

--------------------------------

### Get UGS CLI Help

Source: https://docs.unity.com/en-us/services-cli/latest/manual/general/get-started/install-the-cli

Displays help information for the UGS CLI after installation.

```bash
ugs -h
```

--------------------------------

### Install UGS CLI with Bash Installer

Source: https://docs.unity.com/en-us/services-cli/1.9.0/manual/general/get-started/install-the-cli

Downloads and verifies the UGS CLI installer using shasum, then runs it to install the latest version. After installation, use 'ugs -h' to get help.

```bash
curl -sLo ugs_installer ugscli.unity.com/v1 && shasum -c <<<"3bbc507d4776a20d5feb4958be2ab7d4edcea8eb  ugs_installer" && bash ugs_installer
```

```bash
ugs -h
```

--------------------------------

### Example: make bucket promote-only

Source: https://docs.unity.com/en-us/services-cli/1.9.0/manual/cloud-content-delivery/commands/buckets/permissions/update

Example that makes a bucket 'promote-only' by denying Write permission for User (developer clients).

```bash
ugs ccd buckets permissions update myBucketName -a Write -m Deny -r User

```

--------------------------------

### Verify CLI installation

Source: https://docs.unity.com/en-us/services-cli/1.9.0/manual/general/get-started/install-the-cli

After installation, run this command to verify the CLI is available and check its version.

```bash
ugs --version
```

--------------------------------

### Install and verify UGS CLI with npm

Source: https://docs.unity.com/en-us/services-cli/latest/manual/general/get-started/install-the-cli

Install the Unity Gaming Services CLI globally via npm, then verify the installation by checking the version.

```bash
npm install -g ugs
```

```bash
ugs
```

```bash
ugs --version
```

--------------------------------

### Install CLI via npm

Source: https://docs.unity.com/en-us/services-cli/1.9.0/manual/general/get-started/install-the-cli

Run this command in a terminal with Node.js and npm installed to install the Unity Gaming Services CLI globally as an npm package.

```bash
npm install -g ugs
```

--------------------------------

### Get Player API example - JSON object response

Source: https://docs.unity.com/en-us/services-web-apis/client-auth

Example JSON response from the get player API, containing user details such as ID, disabled status, external IDs, creation time, last login time, and username.

```json
{
    "id": "Tg1m3aq3nVEb9o9kG4vNeqcixLH8",
    "disabled": false,
    "externalIds": [],
    "createdAt": "302899439",
    "lastLoginAt": "302899439",
    "username": "Current_User_57"
}
```

--------------------------------

### Get Player API example - curl command

Source: https://docs.unity.com/en-us/services-web-apis/client-auth

Curl command to call the get player API, retrieving user information. Requires the player ID, project ID, and an ID token from Unity Authentication.

```bash
curl --location --request GET 'https://player-auth.services.api.unity.com/v1/users/<playerId>' \
--header 'Content-Type: application/json' \
--header 'ProjectId: <projectId>' \
--header 'Authorization: Bearer <Id Token from Unity Authentication>'
```

--------------------------------

### Trigger a Build

Source: https://docs.unity.com/en-us/services-web-apis/unity-version-control-cm/examples/java-example

Example demonstrating how to trigger a build for a specific project.

```python
build = client.builds.trigger(
    project_id='YOUR_PROJECT_ID',
    target='Android'
)
```

--------------------------------

### OnSetupFailed with error string

Source: https://docs.unity.com/en-us/services/release-notes

New setup failed callback that provides an error string when OnSetupFailed is invoked.

```csharp
IStoreCallback.OnSetupFailed(InitializationFailureReason, string)
```

--------------------------------

### Get player module help

Source: https://docs.unity.com/en-us/services-cli/1.9.0/manual/player

Displays help on how to use the player module.

```bash
ugs player -h
```

--------------------------------

### ugs multiplay-hosting build installs <build-id>

Source: https://docs.unity.com/en-us/services-cli/1.9.0/manual/game-server-hosting/commands/builds/build-installs

Documentation for the Unity Gaming Services CLI command to retrieve installs for a Multiplay Hosting build.

```APIDOC
## [ugs] multiplay-hosting build installs <build-id>

### Description
Retrieve installs for a Multiplay Hosting build.

### Command
`ugs multiplay-hosting build installs <build-id> [options]`

### Authentication
Required: Yes

### Arguments
- **build-id** (string) - Required - The unique ID of the build.

### Options
- **-p, --project-id** (string) - Optional - The Unity cloud project ID.
- **-e, --environment-name** (string) - Optional - The services environment name.
- **-?, -h, --help** (boolean) - Optional - Display help and usage information.
- **-q, --quiet** (boolean) - Optional - Reduce logging to a minimum.
- **-j, --json** (boolean) - Optional - Use JSON as the output format.
```

--------------------------------

### Example Config Body

Source: https://docs.unity.com/en-us/services-cli/1.9.0/manual/lobby/commands/config-update

Example JSON body for the config update command. Must include the type and values array, with no other data.

```json
{
    "type": "lobby",
    "value": [
        {
            "key": "lobbyConfig",
            "type": "json",
            "schemaId": "lobbyv3",
            "value": {
                "socialProfilesEnabled": false,
                "activeLifespanSeconds": 30,
                "disconnectRemovalTimeSeconds": 120,
                "disconnectHostMigrationTimeSeconds": 120,
                "playerSlots": {
                    "maximum": 8,
                    "minimum": 4
                }
            }
        }
    ]
}
```

--------------------------------

### Unity-RateLimit header example

Source: https://docs.unity.com/en-us/services-web-apis/headers

Shows the Unity custom rate limit header that returns all possible limits with different time windows, separated by semicolons. The example includes two sets of limits.

```http
Unity-RateLimit: limit=20, remaining=19, reset=1; limit=4000, remaining=3994, reset=1579
```

--------------------------------

### Check Build Status

Source: https://docs.unity.com/en-us/services-web-apis/unity-version-control-cm/examples/java-example

Example showing how to poll the status of a build.

```python
status = client.builds.status(build_id=build.id)
print(f'Build status: {status.status}')
```

--------------------------------

### Async Task RefreshPlayerWallet Example

Source: https://docs.unity.com/en-us/services/key-concepts

Example of an async method that updates a player's currency data. It activates a wait indicator, awaits the EconomyManager.RefreshWalletData() task, refreshes the wallet view, and deactivates the indicator. Demonstrates the use of async and await keywords in Unity.

```csharp
async Task RefreshPlayerWallet()
{
	// Use an animation to show the player something is happening.
	waitIndicator.gameObject.SetActive(true);

	// Download this player's currency statuses from UGS;
	// this asynchronous task won't interrupt the animation.
	var newWalletData = await EconomyManager.RefreshWalletData();

	// Once you have the downloaded data, update your UI.
	walletView.Refresh(newWalletData);

	waitIndicator.gameObject.SetActive(false);
}
```

--------------------------------

### Delete player API example - JSON object response

Source: https://docs.unity.com/en-us/services-web-apis/client-auth

Example JSON response from the delete player API, which is an empty object because the user information has been deleted.

```json
{}
```

--------------------------------

### External token API response example

Source: https://docs.unity.com/en-us/services-web-apis/client-auth

Example JSON response from the external token API, including userId, idToken, sessionToken, expiresIn, and user object.

```json
{
    "userId": "Z1bNra4q4LSnyl3P9HM2ohb6Ub3f",
    "idToken": "eyJhbG...Tj0ew",
    "sessionToken": "YgYyi...KbrU",
    "expiresIn": 3599,
    "user": {
        "id": "Z1bNra4q4LSnyl3P9HM2ohb6Ub3f",
        "disabled": false,
        "externalIds": [
            {
                "providerId": "<Id Provider>",
                "externalId": "<Player's External Id>"
            }
        ]
    }
}
```

--------------------------------

### Session token refresh response example

Source: https://docs.unity.com/en-us/services-web-apis/client-auth

Example JSON response from the session-token endpoint. It contains a new idToken, sessionToken, and expiration time. The sessionToken returned here should be used for subsequent refreshes.

```json
{
    "userId": "T7galGM3T1Bggbb3FfNrzMdivZOG",
    "idToken": "eyJhbGciOiJSUzI1NiIsImt...Lc_RN4mn9Hq2k3tFOX5wukCganFjA",
    "sessionToken": "t1X_x7luG7uVvfTQKp6fd2f...MV6dSZWaJOHNymkmQ-es6qOkHF8",
    "expiresIn": 3599,
    "user": {
        "id": "T7galGM3T1Bggbb3FfNrzMdivZOG",
        "disabled": false,
        "externalIds": []
    }
}
```

--------------------------------

### Anonymous authentication response example

Source: https://docs.unity.com/en-us/services-web-apis/client-auth

Example JSON response from the anonymous authentication API. Contains the idToken and sessionToken fields used for user identification and re-authentication.

```json
{
    "userId": "T7galGM3T1Bggbb3FfNrzMdivZOG",
    "idToken": "eyJhbGciOiJSUzI1NiIs...p_q74teH0MNTMQ",
    "sessionToken": "R5pKaP8kEUE2aG...pk08RGC7aM",
    "expiresIn": 3599,
    "user": {
        "id": "T7galGM3T1Bggbb3FfNrzMdivZOG",
        "disabled": false,
        "externalIds": []
    }
}
```

--------------------------------

### Get Code Information API request

Source: https://docs.unity.com/en-us/services-web-apis/client-auth

Optional API for an authenticated client to get information about a sign-in code or verify the correct unauthenticated device. No authentication is required to call this API.

```bash
curl --location --request POST 'https://player-auth.services.api.unity.com/v1/authentication/code-link/info' \
--header 'Content-Type: application/json' \
--header 'ProjectId: <projectId>' \
--data-raw '{
    "signInCode": "<string>"
}'
```

--------------------------------

### Example response from Custom ID authentication

Source: https://docs.unity.com/en-us/services-web-apis/client-auth

Example JSON response from the Custom ID authentication API. It contains the userId, idToken, sessionToken, and user details. The idToken can be used as a Bearer token in subsequent API calls.

```json
{
    "userId": "T7galGM3T1Bggbb3FfNrzMdivZOG",
    "idToken": "eyJhbGciOiJSUzI1NiIs...p_q74teH0MNTMQ",
    "sessionToken": "R5pKaP8kEUE2aG...pk08RGC7aM",
    "expiresIn": 3599,
    "user": {
        "id": "T7galGM3T1Bggbb3FfNrzMdivZOG",
        "disabled": false,
        "externalIds": [
            {
                "providerId": "custom",
                "externalId": "<GAME_SERVER_ID>"
            }
        ]
    }
}

```

--------------------------------

### JWKS response example

Source: https://docs.unity.com/en-us/services-web-apis/client-auth

Example JSON Web Key Set (JWKS) response containing two RSA public keys used to verify the idToken signature. Refresh the JWKS every 8 hours; if the idToken is not found in the cached JWKS, fetch again. Avoid refreshing too frequently to prevent rate limiting.

```json
{
    "keys": [
        {
            "use": "sig",
            "kty": "RSA",
            "kid": "public:f66a7494-5315-4ca4-8150-e846573ffc1d",
            "alg": "RS256",
            "n": "...",
            "e": "AQAB"
        },
        {
            "use": "sig",
            "kty": "RSA",
            "kid": "public:c2f38f4a-a115-40a4-a530-10d08211b6ac",
            "alg": "RS256",
            "n": "...",
            "e": "AQAB"
        }
    ]
}
```

--------------------------------

### Install UGS CLI with Bash Installer

Source: https://docs.unity.com/en-us/services-cli/latest/manual/general/get-started/install-the-cli

Installs the latest version of the UGS CLI using the bash installer. After installation, run 'ugs -h' to get help on using the CLI.

```bash
curl -sLo ugs_installer ugscli.unity.com/v1 && shasum -c <<<"3bbc507d4776a20d5feb4958be2ab7d4edcea8eb  ugs_installer" && bash ugs_installer
```

--------------------------------

### Initialization example using Environments extension

Source: https://docs.unity.com/en-us/services/services-core-api

Initializes all services at once using the Environments initialization extension. Sets the environment name via SetEnvironmentName and calls InitializeAsync with the options. Catches any exception during initialization.

```csharp
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.
        }
    }
}
```

--------------------------------

### Create a New Project

Source: https://docs.unity.com/en-us/services-web-apis/unity-version-control-cm/examples/java-example

Example demonstrating how to create a new Unity project using the API.

```python
project = client.projects.create(
    name='My New Project',
    template='3D',
    location='us-east-1'
)
```

--------------------------------

### POST /v1/authentication/code-link/info

Source: https://docs.unity.com/en-us/services-web-apis/client-auth

Gets information about a sign-in code or verifies that you are attempting to code link to the correct unauthenticated device. No authentication is required to call this API.

```APIDOC
## POST /v1/authentication/code-link/info

### Description
Gets information about a sign-in code or verifies that you are attempting to code link to the correct unauthenticated device. No authentication is required to call this API.

### Method
POST

### Endpoint
https://player-auth.services.api.unity.com/v1/authentication/code-link/info

### Parameters
#### Request Body
- **signInCode** (string) - Required - The code that is required to get information from an authorized device.

### Request Example
```
curl --location --request POST 'https://player-auth.services.api.unity.com/v1/authentication/code-link/info' \
--header 'Content-Type: application/json' \
--header 'ProjectId: <projectId>' \
--data-raw '{
    "signInCode": "<string>"
}'
```

### Response
#### Success Response
- **identifier** (string) - Optional - Identifies the device that requested the code.

#### Response Example
```
{
  "identifier": "<string>"
}
```
```

--------------------------------

### Delete player API example - curl command

Source: https://docs.unity.com/en-us/services-web-apis/client-auth

Curl command to delete a player using the delete player API. Requires the player ID, project ID, and an ID token from Unity Authentication. The user cannot be restored after deletion.

```bash
curl --location --request DELETE 'https://player-auth.services.api.unity.com/v1/users/<playerId>' \
--header 'Content-Type: application/json' \
--header 'ProjectId: <projectId>' \
--header 'Authorization: Bearer <Id Token from Unity Authentication>'
```

--------------------------------

### Sample file structure

Source: https://docs.unity.com/en-us/services-cli/1.9.0/manual/general/deployment-definition/commands-for-deployment-definition

Directory tree showing the Deployment Definition and its files, including a Tests folder that will be excluded.

```text
Assets/
├── DeployableAssets/
│   ├── CloudCode/
│   │   ├── CloudCode.ddef
│   │   ├── scriptA.js
│   │   ├── scriptB.js
│   │   └── Tests/
│   │       ├── scriptA_test.js
│   │       └── scriptB_test.js
│   └── Remote Config/
│       ├── RemoteConfig.ddef
│       ├── configA.rc
│       └── configB.rc
```

--------------------------------

### List All Projects

Source: https://docs.unity.com/en-us/services-web-apis/unity-version-control-cm/examples/java-example

Example showing how to retrieve a list of all projects associated with the account.

```python
projects = client.projects.list()
for proj in projects:
    print(f'{proj.id}: {proj.name}')
```

--------------------------------

### Dockerfile for UGS CLI

Source: https://docs.unity.com/en-us/services-cli/1.9.0/manual/general/samples/ci-cd-pipeline-usage/docker

Dockerfile example for setting up a Docker image with Ubuntu, environment variables for UGS CLI authentication, and dependencies. Replace the placeholder values for UGS_CLI_PROJECT_ID, UGS_CLI_SERVICE_KEY_ID, and UGS_CLI_SERVICE_SECRET_KEY with your actual credentials.

```dockerfile
# Docker image
FROM ubuntu:latest
# Setting environment variables
ENV UGS_CLI_PROJECT_ID=your-project-id
ENV UGS_CLI_SERVICE_KEY_ID=your-service-key-id
ENV UGS_CLI_SERVICE_SECRET_KEY=your-service-secret-key
# Update and get dependency packages
RUN apt-get update
RUN apt-get install sudo
RUN apt-get install gnupg -y
RUN apt-get update; apt-get install curl -y
RUN sudo apt-get install -y libicu-dev -y
# Download and install UGS CLI from GitHub CLI here
```

--------------------------------

### UGS CLI script for Unity Build Automation

Source: https://docs.unity.com/en-us/services-cli/1.9.0/manual/general/samples/ci-cd-pipeline-usage/unity-build-automation

Example content for a .sh file used in a Unity Build Automation configuration. The script runs UGS CLI commands to check the version, get the environment, show status, list environments, and deploy service configurations. It is executed via a pre-build or post-build script hook in the Build Automation configuration.

```bash
#!/bin/bash
ugs --version
ugs config get environment
ugs status
ugs env list
ugs deploy <directory-with-service-configurations> -j
```

--------------------------------

### ugs schema-registry get command syntax

Source: https://docs.unity.com/en-us/services-cli/1.9.0/manual/schema-registry/commands/get

The command to get a schema definition. Requires authentication. The `<schema-name>` argument is the name of the schema to get.

```bash
ugs schema-registry get <schema-name> [options]
```

--------------------------------

### Deployment package check-in folders

Source: https://docs.unity.com/en-us/services/solutions/virtual-shops

In the Deployment window, check in the 'Common' and 'Virtual Shop' folders, then click 'Deploy Selection' to deploy all necessary items.

```text
Common
```

```text
Virtual Shop
```

```text
Deploy Selection
```

--------------------------------

### Install Specific UGS CLI Version

Source: https://docs.unity.com/en-us/services-cli/1.9.0/manual/general/get-started/install-the-cli

Installs a specific version of the UGS CLI by setting the 'version' environment variable (e.g., 1.0.0) before running the installer.

```bash
curl -sLo ugs_installer ugscli.unity.com/v1 && shasum -c <<<"3bbc507d4776a20d5feb4958be2ab7d4edcea8eb  ugs_installer" && version=1.0.0 bash ugs_installer
```

--------------------------------

### Deploy configurations with Deployment package

Source: https://docs.unity.com/en-us/services/solutions/in-game-mailbox

Steps to deploy configurations using the Deployment package: check in the Common and In-Game Mailbox folders, then click Deploy Selection.

```text
Common
```

```text
In-Game Mailbox
```

```text
Deploy Selection
```

--------------------------------

### Deploy configurations with Deployment package

Source: https://docs.unity.com/en-us/services/solutions/command-batching

Steps to deploy configurations using the Deployment package: open the Deployment window, check in 'Common' and 'Command Batching', then click 'Deploy Selection'.

```text
Common
```

```text
Command Batching
```

```text
Deploy Selection
```

--------------------------------

### ugs config get

Source: https://docs.unity.com/en-us/services-cli/1.9.0/manual/general/base-commands/configuration/get

Documentation for the `ugs config get` command, including its arguments and options.

```APIDOC
## [ugs config get] Get Configuration Value

### Description
Gets the value of a configuration for the given key from local configuration keys.

### Command
`ugs config get <key> [options]`

### Authentication
No authentication required.

### Arguments
- **key** (string) - Required - The key to get from local configuration keys.

### Options
- **help** (alias: -?, -h, --help) - Display help and usage information.
- **quiet** (alias: -q, --quiet) - Reduce logging to a minimum.
- **json** (alias: -j, --json) - Use JSON as the output format.
```
Tokens:
Raw