Get started with rotating shop items customization

Last updated on December 18, 2023
note

Extend is in Open Beta for AGS Premium Clients! This means Extend available for you to try on your development environment. You can submit your feedback through this link.

note

Extend is currently available for AGS Starter Closed Beta partners only.

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​

  1. Windows 10 WSL2 or Linux Ubuntu 20.04 with the following tools installed:

    • Bash
    • Make
    • Docker v23.x
    • docker-compose v2
    • Python 3.9
    • ngrok

  2. Access to AGS demo environment.

    • Base URL: https://demo.accelbyte.io.

    • 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 the Client ID and Client Secret.

      ADMIN:NAMESPACE:{namespace}:CATALOG:CONFIG - READ, UPDATE, DELETE

  3. The extend-helper-cli (download here) downloaded, installed, and set up.

Download the sample app​

First, clone the rotating shop items gRPC plugin sample app.

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
note

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.

Clicking to add new item rotation configuration

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

enter ngrok address 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.

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.

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

AB_BASE_URL=https://demo.accelbyte.io
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.

clicking to create new extend app

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

filling out and create new extend app

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

new extend app pending in list

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

extend app details page

Please note the Namespace, App Name, and the App Repository URL 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 temporary Docker credentials for uploading your Docker image.

Use the Namespace and App Name used to create your extend app for the following extend-helper-cli command.

extend-helper-cli dockerlogin --namespace <game namespace> --app <app name> -p | docker login -u AWS --password-stdin https://342674635073.dkr.ecr.us-west-2.amazonaws.com
important

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

  • ADMIN:NAMESPACE:{namespace}:EXTEND:REPOCREDENTIALS [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.

  • ADMIN:NAMESPACE:{namespace}:EXTEND:REPOCREDENTIALS [READ]

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>
note

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.

click to deploy latest extend app image

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.

click the edit icon in the overridden by section

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

select extend app and save

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​

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