Using Hooks
#
Hooks are a feature of the Nakama server runtime that allow you to run custom server code before or after certain server events happen. This can be useful in a number of scenarios, some of which are given below as examples.
For more information on hooks and how they can be used see the hooks documentation and for a full list of server messages that can benefit from hooks see the message names list.
All registration calls below are to be run inside the InitModule
function.
Before hooks
#
These hooks run before a particular server runtime event occurs. This can be used to modify the input to a particular function or take additional actions before it occurs.
Before creating a group
#
This hook checks that a group name does not contain profanity before allowing it to be created. Note that profanity checking functionality is not provided by Nakama.
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;
};
|
Before deleting a group
#
This hook denies an attempt to delete a group that still contains more than 1 user.
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;
};
|
After hooks
#
These hooks run after a particular server runtime event occurs. This can be used to respond to an event appropriately after it has happened.
After adding friends
#
This hook sends a notification to each user that has been added as a friend by another user, letting them know that they have received a friend request.
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);
});
};
|
After leaving a group
#
This hook sends a message to a group notifying the group users that a particular user has left.
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);
};
|
After authenticating by device ID
#
This hook rewards a player with 10 coins (in their virtual wallet whenever they authenticate by device ID.
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);
};
|
Event hooks
#
These hooks run after a particular event has happened, such as a leaderboard being reset or a tournament ending.
On leaderboard reset
#
This hook rewards the top 3 scoring players in a leaderboard with 1,000 coins whenever the leaderboard resets.
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);
});
};
|
On tournament end
#
This hook rewards the winner of a tournament with 10,000 coins and gives them a rare item when the tournament ends.
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]);
};
|
Before realtime hooks
#
These hooks run before a specific realtime message is processed by the server.
Before channel join
#
This hook checks to see if a user is trying to join a Direct Message channel for a non-friend. If so, it blocks their request to join the channel.
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;
};
|
After realtime hooks
#
These hooks run after a specific realtime message is processed by the server.
After channel leave
#
This hook lets a recipient know that the other user has left the channel after that user has left.
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 notification to the channel after leaving, notifying others that the user left
nk.channelMessageSend(input.channelLeave.channelId, { message: `${ctx.userId} left the channel.` }, null, null, true);
};
|