후크 사용

후크는 특정 서버 이벤트가 발생하기 전이나 후에 사용자 지정 서버 코드를 실행할 수 있게 해주는 Nakama 서버 런타임의 기능입니다. 이는 여러 시나리오에서 유용할 수 있으며, 그 중 일부는 아래에 예를 참조하십시오.

후크 및 사용 방법에 대한 자세한 내용은 후크 문서를 참조하고 후크의 이점을 얻을 수 있는 서버 메시지의 전체 목록은 메시지 이름 목록을 참조하세요.

아래의 모든 등록 호출은 InitModule 함수 내에서 실행되어야 합니다.

사전 후크 #

이러한 후크는 특정 서버 런타임 이벤트가 발생하기 _전_에 실행됩니다. 이는 특정 함수에 대한 입력을 수정하거나, 특정 함수가 발생하기 전에 추가 조치를 취하는 데 사용할 수 있습니다.

그룹을 만들기 전에 #

이 후크는 그룹 이름을 만들기 전에 욕설이 포함되어 있는지 확인합니다. 욕설 검사 기능은 Nakama에서 제공하지 않습니다.

Server
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
initializer.registerBeforeCreateGroup(beforeCreateGroup);

let beforeCreateGroup : nkruntime.BeforeHookFunction<nkruntime.CreateGroupRequest> = function (ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, data: nkruntime.CreateGroupRequest) : nkruntime.CreateGroupRequest {
  // Check the group name does not contain profanity (containsProfanity implementation not provided)
  if (containsProfanity(data.name)) {
    throw new Error("Profanity detected.")
  }

  return data;
};

Server
1
2
3
4
5
6
7
initializer.RegisterBeforeCreateGroup(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.CreateGroupRequest) (*api.CreateGroupRequest, error) {
  if containsProfanity(in.Name) {
    return nil, runtime.NewError("profanity detected", 3)
  }
  
  return in, nil
})

그룹을 삭제하기 전에 #

이 후크는 여전히 2명 이상의 사용자가 포함된 그룹을 삭제하려는 시도를 거부합니다.

Server
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
initializer.registerBeforeDeleteGroup(beforeDeleteGroup);

let beforeDeleteGroup : nkruntime.BeforeHookFunction<nkruntime.DeleteGroupRequest> = function (ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, data: nkruntime.DeleteGroupRequest) : nkruntime.DeleteGroupRequest {
  // Deny the delete request if the group still has more than one user
  const result = nk.groupUsersList(data.groupId, null, null, null);
  if (result.groupUsers.length > 1) {
      throw new Error("Group still has users.")
  }

  return data;
};

Server
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
initializer.RegisterBeforeDeleteGroup(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.DeleteGroupRequest) (*api.DeleteGroupRequest, error) {
  groupUsers, _, err := nk.GroupUsersList(ctx, in.GroupId, 100, nil, "")
  if err != nil {
    return nil, runtime.NewError("error retrieving group users", 13)
  }

  if len(groupUsers) > 1 {
    return nil, runtime.NewError("group still has users", 9)
  }
  
  return in, nil
})

사후 후크 #

이러한 후크는 특정 서버 런타임 이벤트가 발생한 _후_에 실행됩니다. 이는 이벤트가 발생한 후 적절하게 대응하는 데 사용할 수 있습니다.

친구 추가 후 #

이 후크는 다른 사용자에 의해 친구로 추가된 각 사용자에게 알림을 보내 친구 요청을 수신했음을 알립니다.

Server
1
2
3
4
5
6
7
8
initializer.registerAfterAddFriends(afterAddFriends);

let afterAddFriends: nkruntime.AfterHookFunction<void, nkruntime.AddFriendsRequest> = function (ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, data: void, request: nkruntime.AddFriendsRequest) {
  // Notify each user that they have received a friend request
  request.ids.forEach(function (id) {
    nk.notificationSend(id, 'Friend Request Received', { message: `You have received a friend request from ${ctx.username}.` }, 1, null, true);
  });
};

Server
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
initializer.RegisterAfterAddFriends(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.AddFriendsRequest) error {
  username, ok := ctx.Value(runtime.RUNTIME_CTX_USERNAME).(string)
  if !ok {
    return runtime.NewError("error getting username", 13)
  }
  
  for _, friendId := range in.Ids {
    content := map[string]interface{} {
      "message": fmt.Sprintf("You have received a friend request from %s", username),
    }
    
    nk.NotificationSend(ctx, friendId, "Friend Request Received", content, 1, nil, true)
  }
  
  return nil
})

그룹 탈퇴 후 #

이 후크는 특정 사용자가 탈퇴했음을 그룹 사용자에게 알리는 메시지를 그룹에 보냅니다.

Server
1
2
3
4
5
6
7
initializer.registerAfterLeaveGroup(afterLeaveGroup);

let afterLeaveGroup: nkruntime.AfterHookFunction<void, nkruntime.LeaveGroupRequest> = function (ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, data: void, request: nkruntime.LeaveGroupRequest) {
  // Send a message to the group to say the player left
  const channelId = nk.channelIdBuild(null, request.groupId, nkruntime.ChanType.Group);
  nk.channelMessageSend(channelId, { message: `${ctx.username} left the group.` }, null, null, true);
};

Server
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
initializer.RegisterAfterLeaveGroup(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.LeaveGroupRequest) error {
  username, ok := ctx.Value(runtime.RUNTIME_CTX_USERNAME).(string)
  if !ok {
    return runtime.NewError("error getting username", 13)
  }
  
  channelId, err := nk.ChannelIdBuild(ctx, nil, in.GroupId, runtime.Group)
  if err != nil {
    return runtime.NewError("error getting channel id", 13)
  }
  
  content := map[string]interface{}{
    "message": fmt.Sprintf("%s left the group.", username),
  }
  
  nk.ChannelMessageSend(ctx, channelId, content, nil, nil, true)
  return nil
})

장치 ID로 인증 후 #

이 후크는 플레이어에게 10개의 코인을 보상합니다(장치 ID로 인증할 때마다 가상 지갑으로).

Server
1
2
3
4
5
6
initializer.registerAfterAuthenticateDevice(afterAuthenticateDevice);

let afterAuthenticateDevice: nkruntime.AfterHookFunction<nkruntime.Session, nkruntime.AuthenticateDeviceRequest> = function (ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, data: nkruntime.Session, request: nkruntime.AuthenticateDeviceRequest) {
  // Give the player 10 coins for logging in
  nk.walletUpdate(ctx.userId, { coins: 10 }, null, true);
};

Server
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
initializer.RegisterAfterAuthenticateDevice(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, out *api.Session, in *api.AuthenticateDeviceRequest) error {
  // Give the player 10 coins for logging in
  userId, ok := ctx.Value(runtime.RUNTIME_CTX_USER_ID).(string)
  if !ok {
    return runtime.NewError("error getting userId", 13)
  }
  
  changeset := map[string]int64{
    "coins": 10,
  }
  
  nk.WalletUpdate(ctx, userId, changeset, nil, true)
  return nil
})

이벤트 후크 #

이 후크는 순위표 재설정 또는 토너먼트 종료와 같은 특정 이벤트가 발생한 후에 실행됩니다.

순위표 재설정 시 #

이 후크는 순위표가 재설정될 때마다 순위표에서 득점 상위 3명의 플레이어에게 1,000 코인을 보상합니다.

Server
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
initializer.registerLeaderboardReset(onLeaderboardReset);

let onLeaderboardReset : nkruntime.LeaderboardResetFunction = function (ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, leaderboard: nkruntime.Leaderboard, reset: number) {
  // Reward top 3 players with 1,000 coins and send them a notification telling them what their rank was
  const topRecords = nk.leaderboardRecordsList(leaderboard.id, null, 3, null, null);
  topRecords.records.forEach(function (record) {
    nk.walletUpdate(record.ownerId, { coins: 1000 }, null, true);
    nk.notificationSend(record.ownerId, 'Congratulations', { message: `Well done, you ranked ${record.rank}!` }, 2, null, true);
  });
};

Server
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
initializer.RegisterLeaderboardReset(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, leaderboard *api.Leaderboard, reset int64) error {
  // Reward top 3 players with 1,000 coins and send them a notification telling them what their rank was
  topRecords, _, _, _, err := nk.LeaderboardRecordsList(ctx, leaderboard.Id, nil, 3, "", 0)
  if err != nil {
    return runtime.NewError("error getting leaderboard records", 13)
  }

  for _, record := range topRecords {
    changeset := map[string]int64 {
      "coins": 1000,
    }
    
    content := map[string]interface{} {
      "message": fmt.Sprintf("Well done, you ranked %d!", record.Rank),
    }
    
    nk.WalletUpdate(ctx, record.OwnerId, changeset, nil, true)
    nk.NotificationSend(ctx, record.OwnerId, "Congratulations", content, 2, "", true)
  }
  
  return nil
})

토너먼트 종료 시 #

이 후크는 토너먼트 우승자에게 10,000 코인을 보상하고 토너먼트가 종료되면 레어 아이템을 제공합니다.

Server
 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
initializer.registerTournamentEnd(onTournamentEnd);

let onTournamentEnd : nkruntime.TournamentEndFunction = function (ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, tournament: nkruntime.Tournament, end: number, reset: number) {
  // Reward tournament leader with 10,000 coins and a rare item
  const topRecord = nk.tournamentRecordsList(tournament.id, null, 1, null, null);
  const winnerId = topRecord.records[0].ownerId;

  // Give the player 10,000 coins
  nk.walletUpdate(winnerId, { coins: 10000 }, null, true);

  // Get the player's existing inventory
  const storageRead : nkruntime.StorageReadRequest = {
    collection: "inventory",
    key: winnerId,
    userId: winnerId
  };

  const result = nk.storageRead([storageRead]);
  let inventory = {};

  if (result.length > 0) {
    inventory = result[0].value;
  }

  // Add the rare item or increase quantity
  if (!inventory["rare-sword"]) {
    inventory["rare-sword"] = 1;
  } else {
    inventory["rare-sword"]++;
  }

  // Write the updated inventory to the storage engine
  const storageWrite : nkruntime.StorageWriteRequest = {
    collection: "inventory",
    key: winnerId,
    userId: winnerId,
    permissionWrite: 0,
    permissionRead: 1,
    value: inventory
  }

  nk.storageWrite([storageWrite]);
};

Server
 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
54
55
56
57
58
59
60
61
62
63
64
65
66
67
initializer.RegisterTournamentEnd(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, tournament *api.Tournament, end, reset int64) error {
  // Reward tournament leader with 10,000 coins and a rare item
  topRecord, _, _, _, err := nk.TournamentRecordsList(ctx, tournament.Id, nil, 1, "", 0)
  if err != nil {
    return runtime.NewError("error getting tournament records", 13)
  }

  winnerId := topRecord[0].OwnerId

  // Give the player 10,000 coins
  changeset := map[string]int64 {
    "coins": 10000,
  }
  nk.WalletUpdate(ctx, winnerId, changeset, nil, true)

  // Get the player's existing inventory
  storageRead := &runtime.StorageRead{
    Collection: "inventory",
    Key: winnerId,
    UserID: winnerId,
  }

  result, err := nk.StorageRead(ctx, []*runtime.StorageRead { storageRead })
  if err != nil {
    return runtime.NewError("error reading player inventory", 13)
  }

  var inventory map[string]int

  if len(result) > 0 {
    if err := json.Unmarshal([]byte(result[0].Value), &inventory); err != nil {
      logger.Error("error unmarshaling inventory", err)
      return runtime.NewError("error unmarshaling inventory", 13)
    }
  } else {
    inventory = make(map[string]int)
  }

  // Add the rare item or increase quantity
  if _, ok := inventory["rare-sword"]; !ok {
    inventory["rare-sword"] = 1
  } else {
    inventory["rare-sword"] += 1
  }
  
  // Write the updated inventory to the storage engine
  inventoryJson, err := json.Marshal(inventory)
  if err != nil {
    return runtime.NewError("error marshaling inventory", 13)
  }
  
  storageWrite := &runtime.StorageWrite{
    Collection: "inventory",
    Key: winnerId,
    UserID: winnerId,
    PermissionWrite: 0,
    PermissionRead: 1,
    Value: string(inventoryJson),
  }
  
  _, err = nk.StorageWrite(ctx, []*runtime.StorageWrite { storageWrite })
  if err != nil {
    return runtime.NewError("error writing inventory", 13)
  }

  return nil
})

사전 실시간 후크 #

이러한 후크는 특정 실시간 메시지가 서버에서 처리되기 _전_에 실행됩니다.

채널 가입 전 #

이 후크는 사용자가 친구가 아닌 사람의 다이렉트 메시지 채널에 참여하려고 하는지 확인합니다. 그렇다면 채널 가입 요청을 차단합니다.

Server
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
initializer.registerRtBefore("ChannelJoin", beforeChannelJoin);

let beforeChannelJoin : nkruntime.RtBeforeHookFunction<nkruntime.EnvelopeChannelJoin> = function (ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, envelope: nkruntime.EnvelopeChannelJoin) : nkruntime.EnvelopeChannelJoin | void {
  // If the channel join is a DirectMessage type, check to see if the user is friends with the recipient first
  if (envelope.channelJoin.type == nkruntime.ChanType.DirectMessage) {
    const result = nk.friendsList(ctx.userId, null, 0, null);
    const filtered = result.friends.filter(function (friend) {
      return friend.user.userId == envelope.channelJoin.target;
    });

    if (filtered.length == 0) {
      throw new Error("You cannot direct message someone you are not friends with.");
    }
  }

  return envelope;
};

Server
 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
initializer.RegisterBeforeRt("ChannelJoin", func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *rtapi.Envelope) (*rtapi.Envelope, error) {
  envelope, ok := in.Message.(*rtapi.Envelope_ChannelJoin)
  if !ok {
    return nil, runtime.NewError("error getting envelope as ChannelJoin envelope", 13)
  }

  userId, ok := ctx.Value(runtime.RUNTIME_CTX_USER_ID).(string)
  if !ok {
    return nil, runtime.NewError("error getting userId", 13)
  }

  // If the channel join is a DirectMessage type, check to see if the user is friends with the recipient first
  if envelope.ChannelJoin.Type == 2 {
    state := 0
    friends, _, err := nk.FriendsList(ctx, userId, 100, &state, "")
    if err != nil {
      return nil, runtime.NewError("error getting friends list", 13)
    }

    isFriends := false
    for _, friend := range friends {
      if friend.User.Id == envelope.ChannelJoin.Target {
        isFriends = true
        break
      }
    }

    if !isFriends {
      return nil, runtime.NewError("you cannot direct message someone you are not friends with.", 9)
    }
  }

  return in, nil
})

사후 실시간 후크 #

이러한 후크는 특정 실시간 메시지가 서버에서 처리된 _후_에 실행됩니다.

채널 탈퇴 후 #

이 후크를 통해 수신자는 어떤 사용자가 채널을 탈퇴한 경우 그 사용자가 채널을 탈퇴했다는 것을 알 수 있습니다.

Server
1
2
3
4
5
6
initializer.registerRtAfter("ChannelLeave", afterChannelLeave);

let afterChannelLeave : nkruntime.RtAfterHookFunction<nkruntime.EnvelopeChannelLeave> = function (ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, output: nkruntime.EnvelopeChannelLeave | null, input: nkruntime.EnvelopeChannelLeave) {
  // Send a message to the channel after leaving, notifying others that the user left
  nk.channelMessageSend(input.channelLeave.channelId, { message: `${ctx.userId} left the channel.` }, "", "", true);
};

Server
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
initializer.RegisterAfterRt("ChannelLeave", func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, out, in *rtapi.Envelope) error {
  envelope, ok := in.Message.(*rtapi.Envelope_ChannelLeave)
  if !ok {
    return runtime.NewError("error getting envelope as ChannelLeave envelope", 13)
  }

  userId, ok := ctx.Value(runtime.RUNTIME_CTX_USER_ID).(string)
  if !ok {
    return runtime.NewError("error getting userId", 13)
  }

  // Send a message to the channel after leaving, notifying others that the user left
  content := map[string]interface{}{
    "message": fmt.Sprintf("%s left the channel.", userId),
  }

  nk.ChannelMessageSend(ctx, envelope.ChannelLeave.ChannelId, content, "", "", true)

  return nil
})

Heroic Cloud

Deploy Nakama and Satori

Company

A Heroic Ten Years: Special letter from our CEO, and invitation to our birthday party!

Heroic Labs Celebrates the Launch of FBC: Firebreak, a Co-op Shooter from Remedy Entertainment.

Realism Meets Tactics in an Open-world MMOFPS: Powering Gray Zone Warfare to Early Success.

Documentation

Community

Download and Install Nakama OSS

Learn how to use Nakama