Events

Most games need to send behavioral data and analytics to services like ad networks, analytics platforms, and purchase verification systems. Typically, each service requires its own SDK in the game client, adding download size, network overhead, and ongoing maintenance burden.

Events let you capture this data once and route it server-side. Your game client sends lightweight event data to Nakama, which processes it in the background and forwards it to whichever third-party services you’ve configured. Players experience minimal interruption, and you avoid embedding multiple SDKs into your client.

This approach gives you three practical benefits: a smaller game client (which improves your first-time user experience and download conversion), less network traffic from the client to external services, and significantly lower integration and maintenance cost for your team.

Generate Events #

Events can be sent to the server by game clients or created on the server. An event has a name and a map of properties which decorate the event with more information.

Send Events #

Use the event API to send to the server.

1

curl -vvv -H "Authorization: Bearer $SESSION"  http://127.0.0.1:7350/v2/event -d '{"name": "my_event", "properties": {"my_key": "my_value"}}'

1

yield(client.event_async(session, "my_event", {"my_key": "my_value"}), "completed")

1

await client.event_async(session, "my_event", {"my_key": "my_value"})

1
2
3
4

local external = true
local name = "my_event"
local properties = { my_key = "my_value" }
local result = nakama.event(client, external, name, properties)

Create Events #

Use the server side module to generate events in your Go code.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

// import "github.com/heroiclabs/nakama-common/api"
// import "github.com/heroiclabs/nakama-common/runtime"

// ctx context.Context, nk runtime.NakamaModule
evt := &api.Event{
    Name:       "event_name"
    Properties: map[string]string{
       "my_key": "my_value",
    },
    External:   true,
}
if err := nk.Event(ctx, evt); err != nil {
    // Handle error.
}

1
2
3
4
5
6
7
8
9

local nk = require("nakama")

local properties = {
  my_key = "my_value"
}
local timestamp = nk.time
local external = false

nk.event("event_name", properties, timestamp, external)

1
2
3
4
5

let properties = {
  my_key: "my_value",
};

nk.event("event_name", properties);

You can also take advantage of after hooks in the server runtime when you want to send events from other features in the server. For example when a user account is updated and you might want to send an event to be processed.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

func afterUpdateAccount(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.UpdateAccountRequest) error {
    evt := &api.Event{
        Name:       "account_updated",
        Properties: map[string]string{},
        External:   false, // used to denote if the event was generated from the client
    }
    return nk.Event(context.Background(), evt)
}

func InitModule(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, initializer runtime.Initializer) error {
    if err := initializer.RegisterAfterUpdateAccount(afterUpdateAccount); err != nil {
        return err
    }
    return nil
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

local nk = require("nakama")

local function after_update_account(ctx, payload)
  local properties = {
    my_key = "my_value"
  }
  local timestamp = nk.time
  local external = false  -- used to denote if the event was generated from the client
  return nk.event("event_name", properties, timestamp, external)
end

nk.register_req_after(after_update_account, "UpdateAccount")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

function InitModule(
  ctx: nkruntime.Context,
  logger: nkruntime.Logger,
  nk: nkruntime.Nakama,
  initializer: nkruntime.Initializer,
) {
  let afterUpdateAccount: nkruntime.AfterHookFunction<
    void,
    nkruntime.UserUpdateAccount
  > = function (
    ctx: nkruntime.Context,
    logger: nkruntime.Logger,
    nk: nkruntime.Nakama,
    data: void,
    payload: nkruntime.UserUpdateAccount,
  ) {
    let properties = {
      my_key: "my_value",
    };

    nk.event("event_name", properties);
  };
  initializer.registerAfterUpdateAccount(afterUpdateAccount);
}

Built-in Events #

The server will generate built-in events which can be processed specifically for the SessionStart and SessionEnd actions. These special events occur when the server has a new socket session start and when it ends. See below for how to process these events.

Process Events #

Events can be processed with a function registered to the runtime initializer at server startup. Events will have its external field marked as true if its been generated by clients.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

func processEvent(ctx context.Context, logger runtime.Logger, evt *api.Event) {
    switch evt.GetName() {
    case "account_updated":
        logger.Debug("process evt: %+v", evt)
        // Send event to an analytics service.
    default:
       logger.Error("unrecognised evt: %+v", evt)
    }
}

// initializer runtime.Initializer
if err := initializer.RegisterEvent(processEvent); err != nil {
    return err
}

Built-in Events #

Events which are internally generated have their own registration functions. The SessionStart is created when a new socket connection is opened on the server.

1
2
3
4
5
6
7
8

func eventSessionStart(ctx context.Context, logger runtime.Logger, evt *api.Event) {
    logger.Debug("process event session start: %+v", evt)
}

// initializer runtime.Initializer
if err := initializer.RegisterEventSessionStart(eventSessionStart); err != nil {
    return err
}

The SessionEnd event is created when the socket connection for a session is closed. The socket could have closed for a number of reasons but can be observed to react on.

1
2
3
4
5
6
7
8

func eventSessionEnd(ctx context.Context, logger runtime.Logger, evt *api.Event) {
   logger.Debug("process event session end: %+v", evt)
}

// initializer runtime.Initializer
if err := initializer.RegisterEventSessionEnd(eventSessionEnd); err != nil {
   return err
}

Advanced Settings #

To protect the performance of the server the event processing subsystem is designed to limit the resources allocated to process events. You can adjust the resources allocated to this subsystem with these configuration settings.

To review other configuration settings, see Server configuration.

Example #

This is a complete sample plugin which processes SessionStart, SessionEnd, and events generated when a user account is updated.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

package main

import (
    "context"
    "database/sql"
    "github.com/heroiclabs/nakama-common/api"
    "github.com/heroiclabs/nakama-common/runtime"
)

func afterUpdateAccount(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.UpdateAccountRequest) error {
    evt := &api.Event{
        Name:       "account_updated",
        Properties: map[string]string{},
        External:   false,
    }
    return nk.Event(context.Background(), evt)
}

func processEvent(ctx context.Context, logger runtime.Logger, evt *api.Event) {
    switch evt.GetName() {
    case "account_updated":
        logger.Debug("process evt: %+v", evt)
        // Send event to an analytics service.
    default:
        logger.Error("unrecognised evt: %+v", evt)
    }
}

func eventSessionEnd(ctx context.Context, logger runtime.Logger, evt *api.Event) {
   logger.Debug("process event session end: %+v", evt)
}

func eventSessionStart(ctx context.Context, logger runtime.Logger, evt *api.Event) {
    logger.Debug("process event session start: %+v", evt)
}

//noinspection GoUnusedExportedFunction
func InitModule(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, initializer runtime.Initializer) error {
    if err := initializer.RegisterAfterUpdateAccount(afterUpdateAccount); err != nil {
       return err
    }
    if err := initializer.RegisterEvent(processEvent); err != nil {
        return err
    }
    if err := initializer.RegisterEventSessionEnd(eventSessionEnd); err != nil {
       return err
    }
    if err := initializer.RegisterEventSessionStart(eventSessionStart); err != nil {
       return err
    }
    logger.Info("Server loaded.")
    return nil
}