Getting started with Cloud Save validator customization

Last updated on May 3, 2024
info

Extend is in Open Beta for AGS Premium Clients! This means that the Extend add-on is available for you to try in your development environment. You can submit your feedback via our Extend Open Beta feedback form.

Overview​

AccelByte Gaming Services (AGS) has the capability to provide custom logic for Cloud Save. Cloud Save can be customized to validate the eligibility of JSON records to be stored or accessed using AGS Extend integration.

In this guide, we will go through the workflow of creating and using a simple custom Cloud Save validator for AGS.

Prerequisites​

  1. Windows 11 WSL2 or Linux Ubuntu 22.04 with the following tools installed:
    • Bash
    • Make
    • Docker v23.x
    • Go v1.19
    • ngrok

  1. Access to the AccelByte Gaming Services environment.

    • Base URL: <your environment's domain URL>
      • Example for AGS Starter customer: https://spaceshooter.prod.gamingservices.accelbyte.io
      • Example for AGS Premium customer: https://dev.customer.accelbyte.io
    • Create a namespace if you don't have one yet. Keep the Namespace ID.
    • Create an OAuth Client with confidential client type. Keep the Client ID and Client Secret.

  2. You have downloaded and set up the extend-helper-cli. Download here.

    • To use this tool, refer to its documentation on GitHub.
    • Be aware that from this setup you will add more permission to your Client ID and User ID.

Download a sample app​

  1. Clone the sample app.

    git clone https://github.com/AccelByte/cloudsave-validator-grpc-plugin-server-go.git

  2. Open the README.md file, then follow the instructions on the Setup, Building, and Running sections. Alternatively, you can use the following go command to run the server. Ensure that the server is running locally before moving onto the next section.

    From sample app root directory (go command):

    make proto
    go run main.go

  3. Start ngrok and expose the port specified within the sample app. The following command assumes you have not changed the port in the sample app:

    ngrok tcp localhost:6565

Test your local Cloud Save validator sample app​

We will test the sample app locally by utilizing ngrok to expose localhost to the internet and using the address for Cloud Save validator gRPC URL configuration. Lastly, we'll try one of the validation inside the sample app to test against the real environment.

Register a local custom function​

  1. Copy the forwarding address from ngrok. An example of this will look like:

    <number>.tcp.ngrok.io:<port>

  2. Go to the AGS Admin Portal and use the namespace you wish to use when creating your customization. On the left pane, click on Game Management, then Cloud Save, and then Customization. Click Add Configuration if you haven't added any.

    Image shows Cloud Save configuration page

  3. Select the Locally hosted for testing purpose optionand put the ngrok address above and finally click Save.

    Image shows the modal for adding Cloud Save overridable configuration

Test the Cloud Save validation​

There are several custom validation implemented on the sample app. In this test, we will try to test one of the validations, which expects the game record with a key that has the suffix map. It should follow this schema:

{
  "locationId": "string,required",
  "name": "string, required",
  "totalResources": "int, required",
  "totalEnemy": "int, required"
}

Create and test a valid game record​

  1. Enable the Before Write Game Record on the Cloud Save customization.

    Image shows Game Record configuration page

  2. On the left pane, click on Game Records, then click the Add Record button. If this is your first time adding a game record, the Create Game Record button will appear instead.

    Image shows modal of adding new Game Records

  3. Create a valid map game using the key, tutorial_map, and the following JSON configuration:

    {
      "locationId": "tutorial",
      "name": "Tutorial Map",
      "totalResources": 100,
      "totalEnemy": 5
    }

    Image show JSON for Game Record mapping

  4. Click Add to save the game record.

    Image show Game Record page

Create and test an invalid game record​

  1. Create an invalid map game record using the key, invalid_map, and the following JSON configuration:

    {
      "foo": "bar"
    }

    Image shows invalid JSON mapping

  2. Click Add to save the game record. An error message should appear. This means that the custom validation is working.

    Image shows a failed save of an invalid game record

Inspect the network​

If you want, you could also inspect the network call to check the error response. Here is the example error response:

{
 "errorCode": 20002,
 "errorMessage": "unable to create_game_record: unable to save record, user ID: 04268814c7af4ba5b3acd26603a12009, from GRPC server: errorCode: 1, errorMessage: locationId cannot be empty;name cannot be empty;totalEnemy cannot be empty;totalResources cannot be empty"
}

Create the Extend app​

We're going to test the sample app and deploy it on the AccelByte-hosted environment called Extend App.

  1. To create the Extend app, go to the AGS Admin Portal and use the namespace you wish to create in your gRPC plugin. On the left pane hover over Extend and click Overridable Features. Click Create New to create a new extend app.

    Image shows Extend Service page

  2. Fill in the App Name and the Description (optional), then click Create.

    Image shows Extend create new app

  3. You will be redirected back to Overridable Features app list page with the newly created app with the Provisioning in Progress status.

    Image shows extend Overridable Feature page

  4. Wait until the status says UNDEPLOYED and click the app name in the list to see its details page.

    Image shows status of app name in Extend page

Please take note of the Namespace, App Name, and the App Repository URI since we're going to use it in the next section.

Build and push the Extend app image​

The extend-helper-cli is required to get the temporary docker credentials for uploading your docker image.

Run the following extend-helper-cli command. Replace the namespace and app name with what you used to create your Extend app.

extend-helper-cli dockerlogin --namespace <game namespace> --app <app name> --login

For your convenience, the above extend-helper-cli command can also be copied from Repository Authentication Command under the corresponding app detail page.

Image showing repository authentication command under admin portal

info

Create an OAuth Client with confidential client type with the following permission. Keep the Client ID and Client Secret.

  • For AGS Premium customers:
    • ADMIN:NAMESPACE:{namespace}:EXTEND:REPOCREDENTIALS [READ]
  • For AGS Starter customers:
    • Extend > Extend app image repository access (Read)

If you use extend-helper-cli v0.0.3 or lower, create a user if you don't have any with the following permission. Keep the Username and Password.

Go to the extend-helper-cli README for more details.

To directly build and push the sample app docker image, you can use the provided make script. Inside the sample app directory, run this:

make imagex_push IMAGE_TAG=v0.0.1 REPO_URL=<app-repository-url>
note

The REPO_URL can be copied from the app details page App Repository URI.

Deploy the Extend app​

Log in to the AGS Admin Portal. On the Extend App Details page, click Deploy Latest Image and wait until the deployment is successful.

Image shows the Extend App details page

Important

If your Extend Override app is based on sample apps before release v2024.02.13: Make sure to set PLUGIN_GRPC_SERVER_AUTH_ENABLED environment variable to true. Otherwise, the access token validation in the Extend app is disabled and your Extend app may be accessed without a valid access token.

Since release v2024.02.13: PLUGIN_GRPC_SERVER_AUTH_ENABLED in Extend Override sample apps is set to true by default. The access token validation can only be disabled when PLUGIN_GRPC_SERVER_AUTH_ENABLED is explicitly set to false. To align with this, all new Extend apps created through the Admin Portal will not have PLUGIN_GRPC_SERVER_AUTH_ENABLED enviroment variable set by default. Previously, PLUGIN_GRPC_SERVER_AUTH_ENABLED=false is added on all new Extend apps created through admin portal.

Test the Extend app​

Update the customization with the Extend App​

  1. In the Admin Portal, update the Cloud Save customization. Go to the Overridden by section to edit existing configuration.

    Image shows the Extend App details page with the overriden detail

  2. Select the AccelByte hosted option and choose one of the extend app. Click Save to finish.

    Image shows the edit app configuration modal

Test the Cloud Save validation (Extend)​

Testing the Extend app is similar to a locally hosted app. You can follow the steps in the Test the Extend app section.

A note on Extend App behavior​

important

In the deployment setup, there's a timeout mechanism for the gRPC Extend app managed by Envoy. This timeout occurs when there's no incoming/outgoing data or request, allowing the system to free up resources. By default, the timeout duration is 300s for streamIdleTimeout and 30s for routeTimeout.

Last updated on

On this page