Extend Challenge goals assignment customization

Last updated on October 31, 2024
備考

Extend is in Open Beta for AGS Private Cloud 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 Service (AGS) Extend allows you to provide custom logic for AGS Challenge to customize challenge goal assignment rules.

This article provides steps to walk you through how to set up custom goals assignment rules for AGS Challenge using the AGS Extend Override app template.

Prerequisites​

  1. Windows 11 WSL2, Linux Ubuntu 22.04, or macOS 14+ with the following tools installed:

    a. Bash

    • On Windows WSL2 or Linux Ubuntu:

      bash --version

      GNU bash, version 5.1.16(1)-release (x86_64-pc-linux-gnu)
      ...

    • On macOS:

      bash --version

      GNU bash, version 3.2.57(1)-release (arm64-apple-darwin23)
      ...

    b. Make

    • On Windows WSL2 or Linux Ubuntu:

      To install from the Ubuntu repository, run sudo apt update && sudo apt install make.

      make --version

      GNU Make 4.3
      ...

    • On macOS:

      make --version

      GNU Make 3.81
      ...

    c. Docker (Docker Desktop 4.30+/Docker Engine v23.0+)

    • On Linux Ubuntu:

      1. To install from the Ubuntu repository, run sudo apt update && sudo apt install docker.io docker-buildx docker-compose-v2.
      2. Add your user to the docker group: sudo usermod -aG docker $USER.
      3. Log out and log back in to allow the changes to take effect.

    • On Windows or macOS:

      Follow Docker's documentation on installing the Docker Desktop on Windows or macOS.

      docker version

      ...
      Server: Docker Desktop
         Engine:
         Version:          24.0.5
      ...

    d. Go v1.19

    e. Curl

    • On Windows WSL2 or Linux Ubuntu:

      To install from the Ubuntu repository, run sudo apt update && sudo apt install curl.

      curl --version

      curl 7.81.0 (x86_64-pc-linux-gnu)
      ...

    • On macOS:

      curl --version

      curl 8.4.0 (x86_64-apple-darwin23.0) ...
      ...

    f. Jq

    • On Windows WSL2 or Linux Ubuntu:

      To install from the Ubuntu repository, run sudo apt update && sudo apt install jq.

      jq --version

      jq-1.6
      ...

    • On macOS:

      To install using Homebrew, run brew install jq.

      jq --version

      jq-1.7.1

    g. Postman

    • Use the available binary from Postman.

    h. ngrok

    i. extend-helper-cli

  1. Access to the AGS Admin Portal environment.
    • Base URL: <your environment's domain URL>
      • Example for AGS Shared Cloud customer: https://spaceshooter.prod.gamingservices.accelbyte.io
      • Example for AGS Private Cloud customer: https://dev.customer.accelbyte.io
    • A game namespace created.
    • An IAM client created with confidential client type. Keep track of the Client ID and Client Secret.

Clone an app template​

git clone https://github.com/AccelByte/challenge-assignment-plugin-server-go.git

Set up, build, run, and test an Extend app​

This section covers how to set up, build, run, and test an AGS Extend app.

Set up the Extend app​

To be able to run this app, follow these setup steps:

  1. Create a docker compose .env file by copying the content of the .env.template file.

    注記

    The host OS environment variables have higher precedence compared to the .env file variables. If the variables in the .env file do not seem to take effect, check if there are host OS environment variables with the same name. For more details, refer to Docker's documentation about the docker compose environment variables precedence.

  2. Fill in the required environment variables in the .env file as shown below:.

    AB_BASE_URL=https://test.accelbyte.io     # Base URL of AGS environment
    AB_CLIENT_ID='xxxxxxxxxx'                 # IAM Client ID
    AB_CLIENT_SECRET='xxxxxxxxxx'             # IAM Client Secret
    AB_NAMESPACE='xxxxxxxxxx'                 # Game Namespace ID
    PLUGIN_GRPC_SERVER_AUTH_ENABLED=true      # Enable or disable access token validation
    注記

    In this app, PLUGIN_GRPC_SERVER_AUTH_ENABLED is true by default. If it is set to false, the gRPC server can be invoked without the AccelByte Gaming Services access token. This option is provided for development purposes only. It is recommended to enable gRPC server access token validation in the production environment.

Build the Extend app​

To build this app, run the following command:

make build

Run the Extend app​

To build and run this app in a container, run the following command:

docker compose up --build

Test the Extend app​

You can test the Extend app in a local development environment or with AGS.

Test in a local development environment​

important

Before testing, make sure PLUGIN_GRPC_SERVER_AUTH_ENABLED is set to false. Otherwise, the gRPC request will be rejected by the gRPC server.

The custom functions in this app can be tested locally using Postman. To test the Extend app using Postman, follow these steps:

  1. Run this app by using the following command:

    docker compose up --build

  2. In Postman, create a new gRPC request, then type in localhost:6565 as the server URL. For more information, see Postman's guide about supporting gRPC.

  3. Continue by selecting AssignmentFunction/Assign method and invoke it with the following sample message:

    With a VALID payload

    {
       "goals": [
          {
                "code": "goal-code",
                "challengeCode": "challenge-code",
                "name": "goal name",
                "isActive": true,
                "tags": [
                   {
                      "name": "big goal"
                   }
                ],
                "requirements": [
                   {
                      "operator": "AND",
                      "predicates": [
                            {
                               "parameterName": "mmr",
                               "parameterType": "STATISTIC",
                               "matcher": "GREATER_THAN",
                               "targetValue": 100
                            }
                      ]
                   }
                ],
                "rewards": [
                   {
                      "type": "STATISTIC",
                      "itemId": "mmr",
                      "itemName": "more mmr",
                      "quantity": 10
                   }
                ],
                "createdAt": {
                   "seconds": "5095510",
                   "nanos": 728418711
                },
                "updatedAt": {
                   "seconds": "7873407235",
                   "nanos": -217262300
                }
          }
       ],
       "namespace": "namespace",
       "userId": "dcd3fc9c238a4c6d9cd8c5da2f595bd6"
    }

    The response will be the list of goals chosen to be assigned to the player.

    {
       "assignedGoals":  [
          {
                "code": "goal-code",
                "challengeCode": "challenge-code",
                "name": "goal name",
                "isActive": true,
                "tags": [
                   {
                      "name": "big goal"
                   }
                ],
                "requirements": [
                   {
                      "operator": "AND",
                      "predicates": [
                            {
                               "parameterName": "mmr",
                               "parameterType": "STATISTIC",
                               "matcher": "GREATER_THAN",
                               "targetValue": 100
                            }
                      ]
                   }
                ],
                "rewards": [
                   {
                      "type": "STATISTIC",
                      "itemId": "mmr",
                      "itemName": "more mmr",
                      "quantity": 10
                   }
                ],
                "createdAt": {
                   "seconds": "5095510",
                   "nanos": 728418711
                },
                "updatedAt": {
                   "seconds": "7873407235",
                   "nanos": -217262300
                }
          }
       ],
       "namespace": "namespace",
       "userId": "dcd3fc9c238a4c6d9cd8c5da2f595bd6"
    }

Test with AGS​

To test the app, which runs locally with AGS, the gRPC server needs to be connected to the internet. To do this without requiring the public IP, you can use ngrok.

  1. Run this by using the command below.

    docker compose up --build

  2. Sign-in to ngrok and get your auth token in ngrok dashboard.

  3. In this app root directory, expose the gRPC server port in the local development environment to the internet by running the following command:

    make ngrok NGROK_AUTHTOKEN=xxxxxxxxxxx

    Take note of the ngrok forwarding URL, e.g., http://0.tcp.ap.ngrok.io:xxxxx.

  4. In the Admin Portal, go to the correct namespace for this configuration and do the following:

    1. Go to Engagement > Challenges > Customization.

    2. Click Add Configuration.

    3. Select the option Locally hosted for testing purpose. Put the ngrok forwarding URL from the previous step and click Register.

      modal for adding Challenge overridable configuration

  5. Create an IAM Client with the confidential client type and containing the following permissions:

    • For AGS Private Cloud customers:
      • ADMIN:NAMESPACE:{namespace}:CHALLENGE:PLUGIN [CREATE,READ,UPDATE,DELETE]
      • ADMIN:NAMESPACE:{namespace}:INFORMATION:USER:* [DELETE]
    • For AGS Shared Cloud customers:
      • Challenge -> Customization (Read, Create, Update, Delete)
      • IAM > Users (Delete)
    備考
    • You will not be able to access the Client Secret after you complete the creation of your IAM client, so make sure you save it.
    • The IAM client created in this step is different from the one mentioned in the Prerequisites section. It is required by the CLI demo app for the next step.

  6. Run the demo.sh script to simulate Challenge operation, which calls this app using the Client ID and Client Secret created in the previous step. Pay attention to this app console log when the script is running. The gRPC Server methods should get called.

    export AB_BASE_URL='https://test.accelbyte.io'
    export AB_CLIENT_ID='xxxxxxxxxx'         # Use Client ID from the previous step
    export AB_CLIENT_SECRET='xxxxxxxxxx'     # Use Client Secret from the previous step    
    export AB_NAMESPACE='accelbyte'          # Use your Namespace ID
    export GRPC_SERVER_URL='0.tcp.ap.ngrok.io:xxxxx'  # Use your ngrok forwarding URL

    bash demo.sh
    備考
    • Make sure the demo.sh has Unix line-endings (LF)**: If this repository was cloned in Windows, for example, the demo.sh may have Windows line-endings (CRLF) instead. In this case, use tools like dos2unix to change the line-endings to Unix (LF). Invalid line-endings may cause errors such as demo.sh: line 2: $'\r': command not found.
    • The ngrok free plan has some limitations, so you may want to use a paid plan if the traffic is high.

Deploy in AGS​

Deploying an Extend app in AGS involves the following steps in the Admin Portal:

  1. Create the Extend app.
  2. Upload the Extend app.
  3. Configure the Extend app.
  4. Deploy the Extend app.
  5. Set AGS to use the Extend app.

Create the Extend app​

  1. In the AGS Admin Portal, go to the namespace where you wish to create your Extend Override app.
  2. On the sidebar menu, under ADD-ONS, go to Extend > Override.
  3. On the Overridable Feature page, click on the + Create New button.
  4. On the Create App form, provide a name and description (optional) for your Extend app.
  5. Click Create. Your new Extend app is added to the Overridable Feature app list.

Upload the Extend app​

  1. Set up an IAM client for extend-helper-cli.Create an IAM client with confidential client type and containing the following permission:

    • For AGS Private Cloud customers:
      • ADMIN:NAMESPACE:{namespace}:EXTEND:REPOCREDENTIALS [READ]
      • ADMIN:NAMESPACE:{namespace}:EXTEND:APP [READ]
    • For AGS Shared Cloud customers:
      • Extend > Extend app image repository access (Read)
      • Extend > App (Read)

    Keep a copy of the Client ID and Client Secret.

  2. Copy the extend-helper-cli command to perform docker login on the Extend app details page under Repository Authentication Command.

    Repository authentication command in Admin Portal

  3. Export the required environment variables and perform docker login using extend-helper-cli. Run this command:

    # Your AGS environment base URL, e.g., https://spaceshooter.prod.gamingservices.accelbyte.io, https://dev.accelbyte.io, etc.
    export AB_BASE_URL='https://xxxxxxxxxx'
    # Client ID of OAuth Client for extend-helper-cli (from step 1)
    export AB_CLIENT_ID='xxxxxxxxxx'     
    # Client Secret of OAuth Client for extend-helper-cli (from step 1)
    export AB_CLIENT_SECRET='xxxxxxxxxx'        

    # The command to perform docker login (from step 2)
    ./extend-helper-cli-linux_amd64 dockerlogin --namespace <game namespace> --app <app name> --login
    備考

    We recommend running the above commands in a separate terminal and in a different working directory than the Extend app project. This is to reduce the chances of the extend-helper-cli picking up the environment variables for the Extend app project instead.

    The output of a successful login looks similar to the following:

    INFO[0000] signing in to https://dev.accelbyte.io 
    INFO[0001] getting docker credentials...                
    WARNING! Your password will be stored unencrypted in /home/xyz-abc/.docker/config.json.
    Configure a credential helper to remove this warning. See
    https://docs.docker.com/engine/reference/commandline/login/#credentials-store

    Login Succeeded
    備考

    If you get the error below, refer to Troubleshooting: Docker login fails for troubleshooting steps.

    Error saving credentials: error storing credentials - err: exit status 1, out: `error storing credentials - err: exit status 1, out: `The stub received bad data.`

  4. Upload the Extend app container image to AGS using extend-helper-cli image-upload command. You can specify your extend app project by using the -w parameter. For the image tag, you can put v0.0.1. For example:

    ./extend-helper-cli-linux_amd64 image-upload -n <game namespace> -a <app name> -w <extend app source dir> -t <image tag>
    備考

    You can use the --login parameter to log in and upload the image simultaneously using a single command. Refer to the extend-helper-cli README text for more details.

    If your images are successfully uploaded, you will see an image with version v0.0.1 on the Image Version History page.

    image history in AGS Admin Portal

Configure the Extend app​

Before deploying the Extend app that you uploaded, you must configure the environment variables required by the Extend app. In the app's details page, set the following environment variables with the same values that you used to run and test the Extend app locally.

  • AB_CLIENT_ID
  • AB_CLIENT_SECRET
危険

If your Extend Override app is based on the template 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 app template 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 environment variable set by default. Previously, PLUGIN_GRPC_SERVER_AUTH_ENABLED=false is added on all new Extend apps created through the Admin Portal.

Deploy the Extend app​

To deploy the Extend app, click Deploy Latest Image. Wait until the app status updates to RUNNING, which indicates that your Extend app is successfully deployed.

Set AGS to use the Extend app​

In the Admin Portal, update the Challenge customization. Go to the Overridden By section to edit the existing configuration.

Challenge customization page with the overridden detail

Select the AccelByte hosted option and choose one of the Extend apps. Click Register to finish.

edit app configuration modal

に最終更新

On this page