Get started with rotating shop items customization
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 ability to customize the logic for rotating shop items. In this guide, we will provide a simple custom rotating shop item and add shop section item backfilling for AGS.
Prerequisites
- Go
- Python
- C#
- Java
- Windows 11 WSL2 or Linux Ubuntu 22.04 with the following tools installed:
- Bash
- Make
- Docker v23.x
- Go v1.19
- ngrok
- Windows 11 WSL2 or Linux Ubuntu 22.04 with the following tools installed:
- Bash
- Make
- Docker v23.x
- Python 3.10
- ngrok
- Windows 11 WSL2 or Linux Ubuntu 22.04 with the following tools installed.
- Bash
- Make
- Docker v23.x
- .NET SDK 6.0
- ngrok
- Windows 11 WSL2 or Linux Ubuntu 22.04 with the following tools installed.
- Bash
- Make
- Docker v23.x
- JDK 17
- ngrok
Access to AGS demo 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
- Example for AGS Starter customer:
- Create a Game Namespace if you don't have one yet. Keep the
Namespace ID
. - Create an OAuth Client with a
confidential
client type. Keep theClient ID
andClient Secret
.
- Base URL:
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
First, clone the rotating shop items gRPC plugin sample app.
- Go
- Python
- C#
- Java
Rotating Shop Items - Sample App
git clone https://github.com/AccelByte/rotating-shop-items-grpc-plugin-server-go.git
Follow the Setup
, Building
, and Running
sections of the repository README.md
. Alternatively, you can use the following go
command to run the server:
From the sample app root directory:
go run main.go
Rotating Shop Items - Sample App
git clone https://github.com/AccelByte/rotating-shop-items-grpc-plugin-server-python.git
Follow the Setup
, Building
, and Running
sections of the repository README.md
. Alternatively, you can use the following python
command to run the server:
From the sample app root directory:
PYTHONPATH=src python -m src.app
Rotating Shop Items - Sample App
git clone https://github.com/AccelByte/rotating-shop-items-grpc-plugin-server-csharp.git
Follow the Setup
, Building
, and Running
sections of the repository README.md
. Alternatively, you can use the dotnet
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:
cd src/AccelByte.PluginArch.ItemRotation.Demo.Server
dotnet run
Rotating Shop Items - Sample App
git clone https://github.com/AccelByte/rotating-shop-items-grpc-plugin-server-java.git
Follow the Setup
, Building
, and Running
sections of the repository README.md
. Ensure that the server is running locally before moving onto the next section.
Ensure that the server is running locally before moving onto the next section.
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 rotating shop items sample app
Next, we will test the sample app locally by using ngrok
to expose localhost to the internet and use the address for item rotation gRPC URL configuration. Then, we'll use the demo/cli
inside the sample app to test against real environment.
Register the gRPC plugin
Copy the forwarding
address from ngrok
. Here's an example:
<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 the menu option E-Commerce on the left and click Custom Configuration. Click the Item Rotation menu option. Click Add Configuration if you haven't added any.
Select the option Locally hosted (for testing purpose), enter the ngrok address from above, and click Create.
Test using gRPCurl
Testing with gRPCurl is optional, but it will ensure that your proxy is working correctly.
Download and install grpcurl. Run the command as shown below using your ngrok TCP forwarding address, which will print out the list of gRPC services served by the forwarded local sample app.
grpcurl -plaintext <number>.tcp.ngrok.io:<port> list
Sample output:
accelbyte.platform.catalog.section.v1.Section
grpc.health.v1.Health
grpc.reflection.v1alpha.ServerReflection
Test sample app using the demo CLI app
The demo CLI will create an e-commerce store, category, display, and section items, enabling a custom rotation and backfilling mechanism programmatically to verify the flow.
- Go
- Python
- C#
- Java
The demo CLI can be found in demo/cli in the sample app repo. Please follow the README to get more details. Alternatively, you can use cd
to navigate to demo/cli
and follow the commands shown below.
The demo CLI can be found in demo/cli in the sample app repo. Please follow the README to get more details. Alternatively, you can use cd
to navigate to demo/cli
and follow the commands shown below.
Demo CLI can be found inside src/AccelByte.PluginArch.ItemRotation.Demo.Client in the sample app. Please follow the readme to get more details. Alternatively, you can use cd
to navigate to src/AccelByte.PluginArch.ItemRotation.Demo.Client
and follow the commands below.
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 demo/cli
directory in the sample app:
AB_BASE_URL=<your environment's 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 your AGS Admin Portal and use the namespace in which you wish to create your gRPC plugin. Hover over Extend menu option on the left and click Overridable Features. Click Create New to create a new extend app.
Type in the App Name and the Description (optional) and click Create.
You will be redirected back to the Overridable Features app list page with the newly created app with the Provisioning in Progress status.
Wait until the status says UNDEPLOYED and click the app name in the list to see details page.
Please note 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.
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 provided make script. Inside the sample app directory, run this:
make imagex_push IMAGE_TAG=v0.0.1 REPO_URL=<app-repository-url>
The REPO_URL can be copied from the app details.
Deploy the Extend app
Back in the AGS Admin Portal, inside the Extend App Details page, click Deploy Latest Image and wait until the deployment is successful.
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 AGS Admin Portal and update the Item Rotation custom configuration. Click the edit icon by the Overridden by section to edit the existing configuration.
Select the AccelByte hosted option and choose one of the Extend apps. Click Save to finish.
Test extend app 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
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
.