Working with protobuf event descriptor

Last updated on April 17, 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 guide, is designed to provide in-depth coverage on the handling of protobuf event descriptors for AccelByte Gaming Services (AGS) event callback

The following topics are covered in this guide:

  • Identifying and downloading the protobuf event descriptor for a specific AGS event
  • Generating a stub from the downloaded protobuf event descriptor
  • Creating a new file to serve as the callback or event handler by extending a generated stub
  • Registering the callback or event handler implementation into the gRPC server in the service

Prerequisites​

This guide assumes you're using the Go event-handler sample app. Please download or clone the event handler sample app from our Extend event handler repo.

Identify and download specific event descriptors​

Here's how you can get the correct protobuf event descriptor for the AGS event you're interested in:

  • Identify your AGS event: You can go to the API-events page to get the details of the event you're interested in.

  • Locate the Protobuf event descriptor: In the page referenced in previous step, you will see the protobuf URL related to your event.

  • Download the protobuf event descriptor: Once you've found the correct descriptor, put it in pkg/proto/accelbyte-asyncapi. We suggest you to copy the directory that contains the protobuf file that you're interested in rather than a single proto file in pkg/proto/accelbyte-asyncapi. For example, if you're interested in userLoggedIn event, please copy the whole IAM directory. This will ensure the generated stub maintains the proper namespace as the namespace is often dictated by the directory structure.

Generate a stub from event descriptor​

Once you have the protobuf descriptor saved in the correct directory structure, you are ready to generate a stub. A "stub" refers to the code generated from the protobuf event descriptor that provides a basic structure for your callback implementation. For example, if you're interested on event that belongs to IAM directory, your directory structure should be look like this

...
├── main.go
└── pkg
    ...
    ├── proto
    │   └── accelbyte-asyncapi
    │       └── iam              # Directory containing protubuf files
    ├── pb
    ...
...

Here's how you can generate the stub:

  • Using any Go Integrated Development Environment (IDE), open the event handler sample app where you added the event descriptor.

  • Run the make proto command, and you will see your stub generated at pkg/pb/accelbyte-asyncapi. For example, if you used the IAM protobuf directory you will see this iam directory pkg/pb/accelbyte-asyncapi/iam. The file structure will look something like this:

...
├── main.go
└── pkg
    ...
    ├── proto
    │   └── accelbyte-asyncapi
    │       └── iam              # Directory containing protubuf files
    ├── pb
    │   └── accelbyte-asyncapi
    │       └── iam              # Directory containing "stub" generated code
    ...
...

Creating your callback implementation​

Now that you have a stub generated from your protobuf event descriptor, it's time to create a callback struct that embed the generated stub. The callback struct is where you'll implement logic for handling AGS events.

Here are the steps to create your callback class:

  • Create a New Go File: In this example, you will use the event handler sample app. Go to directory pkg/service and create a new Go file. For example loginHandler.go

  • Embed the Generated Stub: In the new Go file, define a struct type that embeds the stub type. For example, if your event is userLoggedIn you will see UnimplementedUserAuthenticationUserLoggedInServiceServer stub and your struct declaration might look something like this:

import pb "extend-event-handler/pkg/pb/accelbyte-asyncapi/iam/account/v1"

type LoginHandler struct {
    pb.UnimplementedUserAuthenticationUserLoggedInServiceServer
    // your fields here
}
  • Define OnMessage Methods: Define a method on your new struct named OnMessage. This method should have the same signature as the OnMessage method in the stub, but with your own implementation. This is the method that will be invoked when the AGS event occurs. For example, something like this for userLoggedIn event:
import pb "extend-event-handler/pkg/pb/accelbyte-asyncapi/iam/account/v1"


func (o *LoginHandler) OnMessage(ctxt context.Context, msg *pb.UserLoggedIn) (*emptypb.Empty, error) {

   // your event handling code here
   
   return &emptypb.Empty{}, nil
}

Registering the event handler struct into the service​

The last step in this process is to register your newly created event handler struct into the service. This makes it possible for your event handler struct to receive and handle AGS events as they occur.

To do that you can go to main.go in the event handler sample app, and register your struct would be like this:

import "extend-event-handler/pkg/service"

// gRPC server that you already initialized in the service
s := grpc.NewServer(...)

// Register IAM Handler
loginHandler := service.LoginHandler{} // or service.NewLoginHandler() if you created the constructor method
pb.RegisterUserAuthenticationUserLoggedInServiceServer(s, loginHandler)

You have now registered your event handler struct into the service. Your struct's OnMethod method will now be triggered when the AGS events described by your protobuf descriptor occur.

Last updated on

On this page