Getting started with the event handler

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

This document provides a step-by-step guide on how to use AccelByte Gaming Services (AGS) events handler to listen on the UserLogin event and grant in-game entitlement whenever a user login event is triggered.

Prerequisites

Go

1. Windows 11 WSL2 or Linux Ubuntu 22.04 with the following tools installed:

   • Make
   • Docker v23.x
   • Go v1.20

C#

1. Windows 11 WSL2 or Linux Ubuntu 22.04 with the following tools installed:

   • Bash
   • Make
   • Docker v23.x
   • .NET SDK 6.0

Java

1. Windows 11 WSL2 or Linux Ubuntu 22.04 with the following tools installed:

   • Bash
   • Make
   • Docker v23.x
   • JDK 8

Python

1. Windows 11 WSL2 or Linux Ubuntu 22.04 with the following tools installed:

   • Bash
   • Make
   • Docker v23.x
   • Python 3.10

2. Access to the 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
   • 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.

3. You have downloaded and set up the extend-helper-cli. Download here.

   • To use this tool, refer to its documentation on GitHub.

info

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.

Download the sample app

Go

1. Clone the event handler sample app.

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

2. In the sample app repository, open the README.md file, then follow the Setup, Building, and Running sections.

C#

1. Clone the event handler sample app.

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

2. In the sample app repository, open the README.md file, then follow the instructions in the Setup, Building, and Running sections. 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.EventHandler.Demo.Server
   dotnet run

Java

1. Clone the event handler sample app.

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

2. In the sample app repository, open the README.md file, then follow the instructions in the Setup, Building, and Running sections.

Python

1. Clone the event handler sample app.

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

2. In the sample app repository, open the README.md file, then follow the instructions in the Setup, Building, and Running sections.

info

These steps are mandatory as you will need to add the following additional permission to the Client ID you're using.

• For AGS Premium customers:
  • ADMIN:NAMESPACE:{namespace}:USER:*:ENTITLEMENT [CREATE]
• For AGS Starter customers:
  • Platform Store > Entitlement (Create)

Run and test Extend app locally

Go

To develop the Extend app faster, you can test it using grpcui.

For more details, refer to the README.md file in Extend sample app for golang.

C#

To develop the Extend app faster, you can test it using grpcui.

For more details, refer to the README.md file in Extend sample app for C#.

Java

To have faster iteration on developing the extend app, you can test it using grpcui.

For more details, refer to the README.md in Extend sample app for Java.

Python

To have faster iteration on developing the extend app, you can test it using grpcui.

For more details, refer to the README.md in Extend sample app for Python.

Register and integrate Extend sample app to AGS

1. In the AGS Admin Portal, go to the namespace where wish to create your gRPC Plugin.

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

   

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

   

4. You will be redirected back to Event Handler app list page. Click the app name in the list to see the details page.

   

Create an Extend app that listens to the UserLogin event

In this tutorial, we will create an Extend app that will listen to UserLogin event then grant an entitlement to that user on that specific namespace.

Set up and publish the store

1. Create a new store if the same namespace as this app. You can use your existing store if you already configured your own. For more details about creating and publishing stores, see Store and Entitlements.

   

2. After you've created and published your store, copy the item ID in the published store you want to grant as an entitlement.

   

Walkthrough of the Extend app

Go

As covered in the previous topic about AGS events' descriptor using protobuf file, this sample app will show you how to leverage the protobuf file.

Now, let's get back to the sample app we've cloned previously.

In the sample project, you will have the pkg/proto and pkg/pb and you have to put any directory containing protobuf. This example uses the UserLogin event, so put the iam directory to pkg/proto.

...
├───pkg
│   ├───proto                             
│   │   └───accelbyte-asyncapi            # Place the proto file from previous chapter here.
│   │       └───iam
│   └───pb
│       └───accelbyte-asyncapi            # This is where the generated code from protobuf will be placed.  
│           └───iam
...

To generate the protobuf code, run this command:

make proto

C#

As covered in the previous topic about AGS events' descriptor using protobuf file, this sample app will show you how we leverage that protobuf file.

Now, let's get back to the sample app we've cloned previously.

In the sample project, you will have src/AccelByte.PluginArch.EventHandler.Demo.Server/Protos directory. What we need to do is just put any directory containing protobuf we've mentioned on previous chapter as needed. In this case, we only interested on UserLogin event, so we only put the iam directory to src/AccelByte.PluginArch.EventHandler.Demo.Server/Protos

Then, you need to include the exact protobuf file to be generated by .NET gRPC Tool. Modify src/AccelByte.PluginArch.EventHandler.Demo.Server/AccelByte.PluginArch.EventHandler.Demo.Server.csproj file and add or update following block.

<ItemGroup>
    <Protobuf Include="Protos\iam\account\v1\account.proto" GrpcServices="Server" />
</ItemGroup>

You can include more than one protobuf file. Just add more <Protobuf> lines inside <ItemGroup>.

To generate the code, just run dotnet build.

To put your logic in the code, follow this example file.

To learn more about how to create gRPC service .Net, see Microsoft's gRPC services with C# guide.

Java

As covered in the previous topic about AGS events' descriptor using protobuf file, this sample app will show you how we leverage that protobuf file.

Now, let's get back to the sample app we've cloned previously.

In the sample project, you will have the src/main/proto and target/protoGen, what we need to do is just put any directory containing protobuf we've mentioned on previous chapter as needed. In this case, we only interested on UserLogin event, so we only put the iam directory to src/main/proto

...

├── src
│   ├── main
│   │   ├── proto                      # Place the proto file from previous chapter here
│   │   │   └── accelbyte-asyncapi     
...
└── target
    ...
    ├── protoGen
    │   └── main
    │       ├── grpc                   # This where the generated code from protobuf will be placed
    ...     

To generate the protobuf code you can run this command

make build

Python

As covered in the previous topic about AGS events' descriptor using protobuf file, this sample app will show you how we leverage that protobuf file.

Now, let's get back to the sample app we've cloned previously.

In the sample project, you will have the src/main/proto and target/protoGen, what we need to do is just put any directory containing protobuf we've mentioned on previous chapter as needed. In this case, we only interested on UserLogin event, so we only put the iam directory to src/main/proto

...

├── src
│   ├── app
│   │   ├── proto                      # Place the proto file from previous chapter here, also this is where the generated code from protobuf will be placed

To generate the protobuf code you can run this command

make build

Prepare the required parameters for building and deploying the Extend app

Before we can build and deploy the Extend app, we need to note required parameter to our build tools in the next step.

Go to the Event-Handler page where we previously registered our Event Handler app.

Now, let's note the App Name and App Repository URI

Build and upload the Extend app

After we're ready with our sample app and all required parameters already prepared, let's build and deploy it.

First of all, we need to configure the extend-helper-cli stated in the prerequisites, since we will use it to deploy our sample app.

We will only put brief description on how we used the extend-helper-cli here, please refer to full documentation mentioned in prerequisites.

$ ./extend-helper-cli-linux_amd64 dockerlogin --namespace nngbox2 --app Event-Handler --login

INFO[0000] signing in to https://development.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

For your convenience, the above extend-helper-cli command can also be copied from Repository Authentication Command under the corresponding app detail page.

After you've successfully logged in using extend-helper-cli, you can upload the sample app.

We're using the makefile script in the sample app to upload the sample app.

make imagex_push IMAGE_TAG=v0.0.1 REPO_URL=xxxxxxxxxxxx.dkr.ecr.us-west-2.amazonaws.com/accelbyte/justice/development/extend/nngbox/event-handler

info

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

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

Deploy the Extend app

Before we deploy the app, let's configure the item ID we noted on the previous step.

To deploy the Extend app, click Deploy Latest Image.

Important

If your Extend Event Handler app is based on sample apps before release v2024.02.13: Make sure to set PLUGIN_GRPC_SERVER_AUTH_ENABLED environment variable to false. Otherwise, the access token validation in the Extend app is enabled and your Extend app may be mistakenly rejecting valid gRPC calls.

Since release v2024.02.13: The access token validation has been removed from all Extend Event Handler sample apps because it is unnecessary. To align with this, all new Extend apps created through 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 deployed Extend app

We can see a change in user's entitlement since we granted an entitlement for any user in that namespace that has successfully logged in

A note on Event Handler behavior

When initiating the Event Handler app, especially for a new deployment or after extended breaks, there might be instances where certain events don't trigger their expected callbacks.

This behavior is tied to specific lifecycle moments of the service. It's recommended to introduce a short delay before sending new events during these pivotal times. This ensures all components are ready for optimal event handling. To learn how to check whether the app is up and running, see Event Handler observability.

important

In the deployment setup, there's a timeout mechanism for the gRPC Event Handler 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.

For a deeper understanding and recommended practices, refer to the Event Handler behavior documentation.