Getting started with the event handler

Last updated on August 13, 2024
info

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​

This article walks you through how to set up an Extend Event Handler app. For this purpose, the Extend Event Handler app template is used. It listens to the AccelByte Gaming Services (AGS) UserLogin event and grants in-game entitlement when a user logs in.

Prerequisites​

  1. Windows 11 WSL2 or 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.20

    e. grpcui

    • Use binary available here

      grpcui --version

      grpcui v1.4.1

    f. extend-helper-cli

    • Use binary available here

  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
    • Create a game namespace if you don't have one yet. Take note of the namespace ID.
    • Create an OAuth Client with confidential client type containing the following permissions:
      • For AGS Private Cloud customers:
        • ADMIN:NAMESPACE:{namespace}:USER:*:FULFILLMENT [CREATE]
      • For AGS Shared Cloud customers:
        • Platform Store -> Fulfillment (Create) Keep the Client ID and Client Secret.

  2. Set up the store and the item to grant.

    1. Create and publish a new store in your namespace. You can also use your existing store if any. For more details about creating and publishing stores, see Store and Entitlements.

      Store in AGS Admin Portal

    2. After you have created and published your store, take a note of the Item ID in the published store you want to grant when a user logs in.

      Published Item in AGS Admin Portal

Clone the app template​

git clone https://github.com/AccelByte/extend-event-handler-go.git

Set up, run, and test an Extend app​

This section covers how to set up, build, run, and then test an 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.

    note

    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 properly, 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'                 # Client ID from the Prerequisites section
    AB_CLIENT_SECRET='xxxxxxxxxx'             # Client Secret from the Prerequisites section
    AB_NAMESPACE='xxxxxxxxxx'                 # Namespace ID from the Prerequisites section

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​

The custom function in this app can be tested locally using grpcui. Follow these steps:

  1. Run this Extend Event Handler app by using the following command:

    docker compose up --build

  2. Run grpcui with the following command:

    grpcui -plaintext localhost:6565

  3. Now, in grpcui, send a sample of kafka event you are interested in. In this case, we are interested in userLoggedIn event. So, we are using sample payload.

    {
      "payload": {
         "userAccount": {
            "userId": "string",
            "emailAddress": "string",
            "country": "string",
            "namespace": "string"
         },
         "userAuthentication": {
            "platformId": "string",
            "refresh": true
         }
      },
      "id": "string",
      "version": 0,
      "name": "string",
      "namespace": "string",
      "parentNamespace": "string",
      "timestamp": "2019-08-24T14:15:22Z",
      "clientId": "string",
      "userId": "string",
      "traceId": "string",
      "sessionId": "string"
    }
    note

    You can change the field value you are interested in to suit your needs, e.g., namespace, userId, etc.

    Finally, make sure to select the right service name and method name and click Invoke to send the request.

    GRPC Web UI

  4. If successful, you will see a response similar to the image below. You can also see the item granted to the user you are using for this test.

    grpcui response

    granted entitlement

Deploy in AGS​

Create the Extend app​

  1. In the AGS Admin Portal, go to the namespace where wish to create your Extend Event Handler app.

  2. On the sidebar menu, hover over Extend and click Event Handler. Click Create New to create a new Extend Event Handler app.

    Event handler configuration page in AGS Admin Portal

  3. In app creation page, type in the App Name and the Description. Then, click Create

    create event handler configuration in AGS Admin Portal

Upload the Extend app​

  1. Set up an OAuth Client for extend-helper-cli.Create an OAuth 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.

    Image shows the Repository authentication command under 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
    important

    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
    important

    If you get the following error, 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 -w parameter. For 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>
    info

    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 shows the 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
  • ITEM_ID_TO_GRANT

Event handler environment variable in AGS 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.

Event handler deploy image in AGS Admin Portal

Test the deployed Extend app​

Create a new user in your namespace and login using that user. Check if the Item ID has been granted in that user's entitlement page in Admin Portal.

Event handler entitlement in Admin Portal

Next steps​

Last updated on

On this page