Build upload workflow

Warning: This content is a preview of the documentation. The full documentation, along with code samples, is still in progress. Please provide feedback via the feedback mechanism at the bottom of this page.

The build workflow includes building the binary, getting (or creating) a build, creating a list of build files, upload the build files, creating a build version, and waiting for the build to sync.

Note: Although building the game binary is out of scope for the Game Server Hosting (Multiplay) API, Build the binary provides some light guidance.

Before using the Build workflow, you must have a CCD API key and a UGS service account with the following roles:

  • Multiplay API Viewer
  • Multiplay API Editor

Refer to Project roles and Service account authentication.

Note: Throughout this workflow you need to refer to your Unity project ID and environment ID. You can find your project ID on the project settings page, and the environment ID on the environments page.

The following diagram shows a simplified version of the workflow:

build workflow diagram

Build the binary

Warning: Building your game binary is out of scope for the Game Server Hosting (Multiplay) API.

Before continuing with the rest of the build workflow, you must build your game binary if you plan to create a build. If you already have a build you want to use, you can skip this step and continue to get an existing build.

The process for building a game binary depends on the game engine and tech stack your game uses. If you’re using the Unity Engine, refer to Publishing builds and Create a build.

Get a build

The process for getting a build varies depending on whether you want to use an existing build or create a new build.

Note: A build ID and a CCD bucket ID are separate IDs with a one-to-one relationship. The bucket (identified by the bucket ID) stores the build files, and the build (identified by the build ID) wraps the files from the bucket with metadata.

Get an existing build by name

You can retrieve an existing build ID by name using the List Builds API. If you already know the build ID, continue to Create a list of files in the build.

The Build List API response body includes the CCD Bucket ID of each build in the ccd.bucketID field for each build. Make note of the buildID and ccd.bucketID field values of the build you want to use.

The following code sample shows how to get an existing build by name using curl:

curl -X GET -H "Authorization: Basic <SERVICE_ACCOUNT_CREDENTIALS>" https://services.api.unity.com/multiplay/builds/v1/projects/{projectId}/environments/{environmentId}/builds

Refer to the API documentation for example response bodies and parameter documentation.

Create a new build

You can create a new build using the Create build API.

The Create Build API response body includes the CCD Bucket ID of the build you created in the ccd.bucketID field. Make note of the buildID and ccd.bucketID field values.

The following code sample shows how to create a new build using curl:

curl -X POST -H "Authorization: Basic <SERVICE_ACCOUNT_CREDENTIALS>" -H "Content-Type: application/json" \
    -d '{"buildName":"Dev Build A", "ccd": {}, "osFamily": "LINUX"}' \
    https://services.api.unity.com/multiplay/builds/v1/projects/{projectId}/environments/{environmentId}/builds

Refer to the Create build API documentation for example response bodies and parameter documentation.

Create a list of files in the build

Warning: Creating a list of files in the build is out of scope for the Game Server Hosting (Multiplay) API.

Upload the files in the build

You can upload the files in a build using the CCD create or update entry by path API for each file in your list

  1. Create an entry. The following code sample shows how to create an entry using curl:
curl -X POST -H "Authorization: Basic <SERVICE_ACCOUNT_CREDENTIALS>" -H "Content-Type: application/json" \
    -d '{"content_type": "<FILE_CONTENT_TYPE>", "signed_url": true}' \
    https://content-api.cloud.unity.com/api/v1/environments/{environmentid}/buckets/{bucketid}/entry_by_path/?path=path/to/file
  1. Capture the signed_url from the response. You can then upload the file contents to this URL The following code sample shows how to upload a file using curl:
curl -X PUT -H "Content-Type: <FILE_CONTENT_TYPE>" --upload-file path/to/file \
<signed_url>

Refer to the CCD create or update entry by path API documentation for example response bodies and parameter documentation.

Create a build version

You can create a build version with the Create a new build version API. Be sure to set the ccd.bucketID field to the ID of the CCD bucket you noted earlier.

The following code sample shows how to create a build version using curl:

curl -X POST -H "Authorization: Basic <SERVICE_ACCOUNT_CREDENTIALS>" -H "Content-Type: application/json" \
    -d '{"ccd": { "bucketID": "<CCD_BUCKET_ID>" }, "forceRollout": false}' \
    https://services.api.unity.com/multiplay/builds/v1/projects/{projectId}/environments/{environmentId}/builds/{buildId}/versions

Refer to the Create a new build version API documentation for example response bodies and parameter documentation.

Wait for the build to sync

You can find out when the build synchronization completes by retying the Get a single build API until the syncStatus field is SYNCED.

The following code sample shows how to know when the build has synced using curl:

curl -X GET -H "Authorization: Basic <SERVICE_ACCOUNT_CREDENTIALS>" https://services.api.unity.com/multiplay/builds/v1/projects/{projectId}/environments/{environmentId}/builds/{buildId}

Refer to the Get a single build API documentation for example response bodies and parameter documentation.

Unity logo Documentation
Copyright © 2024 Unity Technologies
"Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.