Get started with lootbox roll 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 different requirements when players open loot boxes. In this guide, we will provide a simple custom loot box roll function for AGS.

Prerequisites​

  1. Windows 11 WSL2 or Linux Ubuntu 22.04 with the following tools installed:
    • Bash
    • Make
    • Docker v23.x
    • Python 3.10
    • 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 Game 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.

Download the sample app​

Clone the loot box roll function gRPC plugin sample apps. loot box roll - sample app

git clone https://github.com/AccelByte/lootbox-roll-function-grpc-plugin-server-python.git

Follow the Setup, Building, and Running sections of the repository README.md. Alternatively, you can use the python command shown below to run the server. Ensure that the server is running locally before moving onto the next section.

From sample app root directory (python command):

PYTHONPATH=src python -m src.app

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 loot box roll sample app​

Next, we will test the sample app locally by utilizing ngrok to expose localhost to the internet and use the address for loot box gRPC url configuration. Lastly, we'll use the demo/cli inside the sample app to test against the real environment.

Register the gRPC plugin​

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

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

Go to the AGS Admin Portal and use the namespace in which you wish to create your gRPC Plugin. Hover over left sidebar menu option E-Commerce and click Custom Configuration. Click the Loot Box Roll side menu. Click Add Configuration if you haven't added any.

loot box roll custom configuration page in AGS Admin Portal

Select the option Locally hosted (for testing purpose) and put the ngrok address from above. Then, click Create.

custom configuration for testing purposes

Test using gRPCurl​

Testing with gRPCurl is optional, but it will ensure your proxy is working correctly.

Download and install grpcurl and run the following command that will print out the list of gRPC services served by the forwarded local sample app:

Use your ngrok tcp forwarding address below:

grpcurl -plaintext <number>.tcp.ngrok.io:<port> list

Sample output:

accelbyte.platform.entitlement.lootbox.v1.lootbox
grpc.health.v1.Health
grpc.reflection.v1alpha.ServerReflection

Test using demo CLI app​

Demo CLI will basically create an e-commerce store, category, loot box items, and will also consume the loot box programmatically to verify the flow.

Demo CLI can be found inside demo/cli in the sample app. Please follow the readme to get more details. Alternatively, you can use cd to navigate to demo/cli and follow the commands below.

Create a .env file containing your AccelByte account and IAM client inside the demo/cli directory in the sample app:

AB_BASE_URL='<your environment domain URL>'
AB_CLIENT_ID='<AccelByte IAM Client ID>'
AB_CLIENT_SECRET='<AccelByte IAM Client Secret>'
AB_NAMESPACE='namespace'
AB_USERNAME='<AccelByte account username>'
AB_PASSWORD='<AccelByte account password>'

Finally, run the demo

make run ENV_FILE_PATH=.env

Create the Extend app​

Next, we're going to test the sample app and deploy it on the AccelByte hosted environment called Extend App.

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

click create new in onverridable features

Type in the App Name and the Description (optional) and click Create.

fill out and create extend app

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

overridable features list with created app

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

extend app details page

note

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

:::Important 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

Note that REPO_URL can be copied from the app detail page App Repository URI.

Deploy the Extend app​

Back in the Admin Portal, inside the Extend App Details page, click Deploy Latest Image and wait until the deployment is successful.

app deployment successful on 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​

Register the gRPC plugin with the Extend app​

Go back to the Admin Portal and update the Loot Box Roll custom configuration. Click the Overridden by section to edit the existing configuration.

click to edit the overridden by option

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

choose an AccelByte hosted extend apps

Test using the demo CLI app​

Reuse the command from the previous steps to test the Extend app.

make run ENV_FILE_PATH=.env

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