Use case sample: Initialize newly signed-up players with default configuration values

The use case sample demonstrates how to use Triggers to initialize new players with a default health and stamina values in Cloud Save when they first sign up. It uses the signedUp event emitted by the Authentication service, and records the value in Cloud Save.

Prerequisites

You must first create a service account with required access roles and configure the UGS CLI.

Authenticate using a Service Account

Before you can call the Triggers service, you must authenticate using a Service Account.

  1. Navigate to the Unity Cloud Dashboard.
  2. Select Administration > Service Accounts.
  3. Select the New button and enter a name and description for the Service Account.
  4. Select Create.

Add Product roles and create a key:

  1. Select Manage product roles.
  2. Add the following roles to the Service Account:
    • From the LiveOps dropdown, select Triggers Configuration Editor and Triggers Configuration Viewer.
    • From the Admin dropdown, select Unity Environments Viewer.
  3. Select Save.
  4. Select Add Key.
  5. Encode the Key ID and Secret key using base64 encoding. The format is “key_id:secret_key”. Note this value down.

For more information, refer to Authentication.

Configure the UGS CLI

Follow the steps below to get stated with the UGS CLI:

  1. Install the UGS CLI.

  2. Configure your Project ID and Environment as such:
    ugs config set project-id <your-project-id>
    ugs config set environment-name <your-environment-name>

  3. Authenticate using the Service account you created earlier. Refer to Get Authenticated.

Examine the signed-up event

The Authentication service emits a signed-up event when a new player is created. The event payload looks like this:

{
  "playerId": "string",
  "providerId": "string",
  "createdAt": "string"
}

The event payload is passed on to Cloud Code as parameters.

Refer to Authentication: Signed up for more information.

Set up Cloud Code

Define a module endpoint or a script that calls Cloud Save to initialize a newly authenticated player with default health and stamina values.

Cloud Code C# module

Create a InitializeNewPlayer module function with required string argument playerId with contents as below:

C#

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Unity.Services.CloudCode.Core;
using Unity.Services.CloudCode.Apis;
using Unity.Services.CloudCode.Shared;
using Unity.Services.CloudSave.Model;

public class ModuleSample
{
    private const string HealthKey = "HEALTH";
    private const string StaminaKey = "STAMINA";
    private const int DefaultValue = 100;

    private readonly ILogger<ModuleSample> _logger;
    public ModuleSample(ILogger<ModuleSample> logger)
    {
        _logger = logger;
    }

    [CloudCodeFunction("InitializeNewPlayer")]
    public async Task InitializeNewPlayer(IExecutionContext ctx, IGameApiClient gameApiClient, string playerId)
    {
        try
        {
            var response = await gameApiClient.CloudSaveData.GetItemsAsync(ctx, ctx.ServiceToken, ctx.ProjectId, playerId, new List<string>() { HealthKey, StaminaKey });
            if (response.Data.Results.Count == 0)
            {
                await gameApiClient.CloudSaveData.SetItemBatchAsync(ctx, ctx.ServiceToken, ctx.ProjectId, playerId,
                    new SetItemBatchBody(new List<SetItemBody>{new (HealthKey, DefaultValue), new (StaminaKey, DefaultValue)}));

                _logger.LogInformation("The player has been initialized with the {HealthKey} and {StaminaKey} keys with values of {DefaultValue}", HealthKey, StaminaKey, DefaultValue);

            }
        } catch (ApiException e)
        {
            _logger.LogError("Failed to initialize player data in Cloud Save. Error: {Error}", e.Message);
            throw new Exception($"Failed to initialize {playerId} data in Cloud Save. Error: {e.Message}");
        }
    }

    public class ModuleConfig : ICloudCodeSetup
    {
        public void Setup(ICloudCodeConfig config)
        {
            config.Dependencies.AddSingleton(GameApiClient.Create());
        }
    }

}

Deploy the module.

Refer to Deploying Hello World to learn how to deploy a module.

Note: If you are deploying the module using the UGS CLI, don't forget to add additional Service Account role of Cloud Code Editor.

Cloud Code JavaScript script

Create a InitializeNewPlayer script with a required string parameter playerId using the contents as below:

JavaScript

const { DataApi } = require("@unity-services/cloud-save-1.4");

const CLOUD_SAVE_HEALTH_KEY = "HEALTH";
const CLOUD_SAVE_STAMINA_KEY = "STAMINA";
const DEFAULT_VALUE = 100;

module.exports = async ({ params, context, logger }) => {
  const cloudSaveApi = new DataApi(context);

  try {
    // Check if player has been initialized yet
    const cloudSaveGetResponse = await cloudSaveApi.getItems(context.projectId, params.playerId, [CLOUD_SAVE_HEALTH_KEY, CLOUD_SAVE_STAMINA_KEY]);

    if (cloudSaveGetResponse.data.results.length === 0) {
      // Record new values for player
      await cloudSaveApi.setItemBatch(context.projectId, params.playerId, {
        data: [
          {
            key: CLOUD_SAVE_HEALTH_KEY,
            value: DEFAULT_VALUE,
          },
          {
            key: CLOUD_SAVE_STAMINA_KEY,
            value: DEFAULT_VALUE,
          },
        ],
      });

      logger.info(`The player has been initialized with the ${CLOUD_SAVE_HEALTH_KEY} and ${CLOUD_SAVE_STAMINA_KEY} keys with values of ${DEFAULT_VALUE}`, { "affectedPlayerId": params.playerId });
      return;
    }

    logger.info("The player has already been initialized.", { affectedPlayerId: params.playerId });
  } catch (err) {
    logger.error("Failed to update Cloud Save data", { "error.message": err.message }, { "affectedPlayerId": params.playerId });
    throw err;
  }
};

// Uncomment the code below to enable the inline parameter definition
// - Requires Cloud Code JS dev environment setup with NodeJS (https://docs.unity3d.com/Packages/com.unity.services.cloudcode@2.5/manual/Authoring/javascript_project.html)
//
// module.exports.params = {
//   playerId: { type: "String", required: true },
// };

Note: If you are using Unity Editor to manage your scripts, you can uncomment the code at the bottom of the script to declare the required playerId parameters in-script. To learn more about how to manage in-script parameters, refer to Modify script parameters within the Unity Editor. Publish the script.

Refer to Deploying Hello World to learn how to deploy a script.

Note: If you are deploying the script using the UGS CLI, don't forget to add additional Service Account roles: Cloud Code Script Publisher and Cloud Code Editor.

Configure a trigger

To connect your Cloud Code resource to the Authentication signed-up event, create a trigger. The trigger executes the Cloud Code script or module when the event is fired, for example, every time a new player signs up.

Run the new-file command to create a trigger configuration locally:

ugs triggers new-file triggers-config

If you created a Cloud Code script, update the triggers-config.tr file with the following configuration:

{
  "$schema": "https://ugs-config-schemas.unity3d.com/v1/triggers.schema.json",
  "Configs": [
    {
      "Name": "initialize-new-player",
      "EventType": "com.unity.services.player-auth.signed-up.v1",
      "ActionUrn": "urn:ugs:cloud-code:InitializeNewPlayer",
      "ActionType": "cloud-code"
    }
  ]
}

If you created a Cloud Code module, update the triggers-config.tr file with the following configuration:

{
  "$schema": "https://ugs-config-schemas.unity3d.com/v1/triggers.schema.json",
  "Configs": [
    {
      "Name": "initialize-new-player",
      "EventType": "com.unity.services.player-auth.signed-up.v1",
      "ActionUrn": "urn:ugs:cloud-code:ModuleSample/InitializeNewPlayer",
      "ActionType": "cloud-code"
    }
  ]
}

Deploy the configuration using the UGS CLI tool:

ugs deploy triggers-config.tr

You should get a response similar to the following:

Deployed:
    triggers-config.tr

Now you have a trigger that executes your Cloud Code script or module when a player signs up.

Note: You can define multiple triggers to execute different Cloud Code scripts or modules for the same event. You can expand this use case to add more triggers to initialize other player data.

Validate the result

To validate the result, sign up a new player using the Authentication service. This can be done by calling out to any Unity Gaming Service that's authenticated as a player.

For example, to trigger the player authentication flow, you can generate a new player ID through the Cloud Code script page in the Unity Cloud Dashboard.

Given the trigger is configured to fire on the signed-up event, every new player that signs up, their values are initialized in Cloud Save.

  1. Navigate to the Unity Cloud Dashboard.
  2. Select Products > Player Management.
  3. Select one of the players from the list.
  4. Navigate to the Cloud Save > Data tab.
  5. You should find the HEALTH and STAMINA keys with the default values of 100.
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.