Event

1. Overview

An Event is generated when something happens. For example, event_player_login_pgos will be generated when a player login. One or more Actions can be executed when an Event triggered. These Actions can be bound with specific Virtual Server or Webhook, which will be executed once the corresponding event triggered. You can configure them in the Web Portal.

By reading this chapter, you can learn:

1. How to configure Event Handler.
2. How to handle the Events.
3. How to query trigger logs of Event.

2. Configure Event Handlers

You can create Event Handlers to handle specific Events when they are triggered. Each Event handler has filter Conditions and Actions. The configuration page as shown below.

Click on an Event such as event_player_login_pgos to go to the Event Handler configuration page for the Event, as shown below.

Click + Add Event Handler to configure a new handler. Multiple handlers can be added to the Event, as shown below.

• First, enter the name of the Event Handler. The name must be unique within the game region.
• Enter a description of the Event Handler (optional).
• Configure optional filter Conditions(optional):
  • Click + Add Condition to add an "AND" logical judgment with conditional expressions.
  • Click + Add Group to add an "OR" logical judgment group.
  • If you don't configure any Filter Conditions, the Actions will be executed unconditionally whenever the event occurs.
• Configure Actions:
  • Click + Add Action to add more Actions, and there are 3 types of Action:
    • Virtual Server
    • Webhook
    • Message Bus
  • If you click the input box for Json Args, an input dialog box will pop up to allow you to enter a JSON-formatted argument for the Action.

• Finally, when you have completed all configuration items, click on the Submit button to save the current configuration.

3. Event Data Schema

Click Extension Data Schema to visit the event data schema definition.

Here are some key data fields:

• Trigger ID

  Every time an event triggered, an unique identity string TriggerId will be spawned with the corresponding event.

• Execution ID

  One or more actions can be executed when an event triggerd. The unique ExecuteionId indicate every action execution.

So, one TriggerId can be mapped to multi ExecutionId. You can also find them in the trigger log page.

4. Handle Events

4.1 Handle with Virtual Server

You can handle any Event in your Virtual Server. The following guidance shows how to do it.

• Step 1: Write Virtual Server

  Write a Virtual Server, and listen the /pgos_event URL to handle the event in the Virtual Server, such as event_player_login_pgos. Here is the Golang sample code:

// This sample use fiber web server framework to implement the server
package main

import (
    "encoding/json"
    "fmt"
    "log"
    "main/pgos_lib"
    "time"
    "github.com/gofiber/fiber/v2"
)

// EventPlayerLoginPgosEventData. Genarated by swagger
type EventPlayerLoginPgosEventData struct {
    // Player session id.
    SessionId string `json:"session_id,omitempty"`
    // Player id.
    PlayerId string `json:"player_id,omitempty"`
    // Platform.
    Platform string `json:"platform,omitempty"`
    // Player's source ip.
    IpAddr string `json:"ip_addr,omitempty"`
    // Whether is a new player.
    IsNewPlayer bool `json:"is_new_player,omitempty"`
    // Start time of player session(unix timestamp in seconds).
    StartTime int32 `json:"start_time,omitempty"`
    // Specified custom data set when login.
    CustomData string `json:"custom_data,omitempty"`
    // Country code.
    CountryCode string `json:"country_code,omitempty"`
}

// EventPlayerLoginPgos. Genarated by swagger
type EventPlayerLoginPgos struct {
    // Trigger id.
    TriggerId string `json:"trigger_id,omitempty"`
    // Event name, which is `event_player_login_pgos`
    EventName string `json:"event_name,omitempty"`
    // Date and time when event is triggered, expressed as a utc timestamp,in milliseconds.
    EventTime string `json:"event_time,omitempty"`
    EventData *EventPlayerLoginPgosEventData `json:"event_data,omitempty"`
    // Custom args that set by developers on portal.
    Args interface{} `json:"args,omitempty"`
}

func main() {

    app := fiber.New()
// pgos_event handles all event, please config the event handler in the portal in advance
    app.Post("/pgos_event", func(c *fiber.Ctx) error {
        invoker := c.Get("Invoker")
        if invoker != "event" {
            return c.SendStatus(fiber.StatusUnauthorized)
        }
    var e = &EventPlayerLoginPgos{
      EventData: &EventPlayerLoginPgosEventData{},
    }
    
        // Write your own code to handle event_player_login_pgos data 
    if err = json.Unmarshal(c.Body(), e); err != nil {
      log.Println("/pgos_event data error: ", err)
    } else {
      log.Printf("/pgos_event data: %v\n", e)
    }
        
        return nil
    })
  
  // server will listen 8081 port
  log.Fatal(app.Listen(":8081"))
}

• Step 2: Deploy Virtual Server Refer the Create and Manage Virtual Server doc , Deploy the Virtual Server to PGOS, and make sure it is in running status.
• Step 3: Bind an Action to the Virtual Server Bind the Virtual Server to handle Event. You may need refer Configure Event Handlers.

For now, all things are ready. You may need to test it by triggering an Event. For example, you can login a game client to trigger an event_player_login_pgos Event to check if it works fine.

4.2 Handle with Webhook

If you have your own game backend, you can also handle the Event with Webhook.

• Step 1: Expose the Webhook URL from your backend

  Implement your own logic to handle event, and then expose the corresponding Webhook URI

• Step 2: Create Webhook in PGOS

  Refer the doc Webhook, and then create a Webhook in PGOS.

• Step 3: Bind an action to the Webhook

  Bind the Webhook you just created, and then bind it to handle Event. You may need refer Configure Event Handlers.

For now, all things are ready. You may need to test it by triggering an Event. For example, you can login a game client to trigger an event_player_login_pgos Event to check if it works fine.

5. Log Query

You can read and query the trigger logs of all handlers for an Event, as shown below.

tip

Considering of performance, for Production Title Region, PGOS record only the failed log, and does not store the success log. So, you can only query the success log in the Dev/Test Title Region.