Working with protobuf event descriptor
The Extend Override and Events handler is currently available for Closed Beta partners only. Please submit a ticket if you're interested to apply as a Closed Beta partner.
Overview
This guide, is designed to provide in-depth coverage on the handling of protobuf event descriptors for 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 generated stub
- Registering the callback or event handler implementation into the grpc server in the service
Prerequisites
This guide assumed to be used for go event-handler sample app. Please download/clone the event handler sample app in https://github.com/AccelByte/extend-event-handler-go
Identifying and downloading your specific event Descriptor
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 https://docs-preview.accelbyte.io/gaming-services/api-events/ to get the details of the event you're interested in
Locate the Protobuf event descriptor: In the URL page stated 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 the
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 into thepkg/proto/accelbyte-asyncapi
. For example if you're interested inuserLoggedIn
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.
Generating a stub from the downloaded protobuf 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:
Open the event handler sample app at which you already put the event descriptor in it, you can use any Go IDE.
Run the
make proto
command, and you will see your stub generated atpkg/pb/accelbyte-asyncapi
. For example, if you put IAM protobuf directory you will see thisiam
directorypkg/pb/accelbyte-asyncapi/iam
, 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 we will use the event handler sample app. Go to directory
pkg/service
, and create new Go file. For exampleloginHandler.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 seeUnimplementedUserAuthenticationUserLoggedInServiceServer
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 namedOnMessage
. This method should have the same signature as theOnMessage
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 foruserLoggedIn
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 alrady initialized in 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.