Integrating guild chat into your game allows players to coordinate with their guild inside the Kongregate Panel. Your game will be notified when new messages are received, and you can open the panel directly to the chat view. Customization of the background image is possible, and further customization will be added later.
The guild chat system requires that you have a game server which implements our Guilds API. Specifically, Kongregate needs up-to-date information about characters and guilds on your server so that it can authorize users to view guild-specific chat rooms. You should ensure that you issue a request to our Guilds API whenever a player changes guilds, usernames, or is linked to a Kongregate account.
You must be able to generate a JWT payload using the default HS256 algorithm on your game server and send that to the client as needed.
The guild chat system authorizes players utilizing a signed token that contains information about the player from your game server. This is referred to as a character token.
You can generate a signed character token using JWT to identify the player.
The token should contain the character_identifier, guild_identifier, and server_identifier for the current player, the expiration time (expressed as seconds since the epoch), and should be signed using your game’s Kongregate Server API Key, which must be the same key you use to submit data to the Guilds API. We recommend an expiration time of 12 hours. You should use the default HS256 algorithm for signing.
Here is a JSON example of a payload:
{
"character_identifier": "1234567890",
"server_identifier": "1",
"guild_identifier": "4",
"exp": 1431571334
}
An example of signing a token using the Ruby JWT library:
api_key = 'my-kongregate-server-api-key'
payload = {
'character_identifier' => '123456789',
'server_identifier' => '1',
'guild_identifier' => '4',
'exp' => 12.hours.from_now.to_i
}
character_token = JWT.encode(payload, api_key)
The character token should be sent to the game client and should be updated whenever a user changes accounts or causes their character_identifier, server_identifier, or guild_identifier to be updated.
Once the client receives the character token from the game server, it can pass it on to the Kongregate API any time after the READY event has been fired using the setCharacterToken method on the services API object.
The Kongregate API will generate a CHARACTER_TOKEN_REQUEST event when it requires a new token for authorization. It will continue to do this periodically until a new token has been received via the setCharacterToken method. When this event is received you should update the API with the latest token if you already have it on the client, or request a new one from the game server if not.
Since generating tokens is a light-weight operation, it may make sense to send new tokens to the client on each request and keep them handy in memory or on disk to avoid an additional request to the game server when a CHARACTER_TOKEN_REQUEST event is received.
If the player is logged in via Kongregate and you have submitted their character information via the Guilds API, authorization will happen automatically. However, it is still a best practice to provide a character token, as we can use character/server information to help place the user into the proper room.
Your producer can enable guild chat on the server side when you are ready to begin integrating.
Guild chat must also be enabled on the client side by setting KONGREGATE_OPTION_GUILD_CHAT to true. For Unity, this can be accomplished by setting KongregateAPI.Settings.GuildChat to true.
Users can access guild chat through the menu in the Kongregate Panel, or you can specify a target of TARGET_GUILD_CHAT in your call to openKongregateWindow.
You can customize the header of the Kongregate Panel. Please see the notification documentation section “Customized Kongregate Panel Toolbar” for more details.
The Kongregate API will generate a NOTIFICATION_COUNT_UPDATED event when any notification count changes. You can use the hasUnreadGuildMessages on the services API object to determine if there are unread guild messages. For details on how to present this information in your UI, see the notification documentation.