Skip to main content

Integrate groups into your game

Last updated on May 13, 2024

Overview

AccelByte Gaming Services (AGS) Group provides game developers a way to boost interaction between players that can increase overall player retention by allowing players to form a group, gather, interact, and collaborate to achieve common goals. In this guide, you will learn how to integrate groups into your game using the AGS Group service with the Client SDK.

Goals

By following this guide, you will:

  • Learn how to integrate groups into your game with Client SDKs.
  • Gain an understanding of how to allow players to manage groups.
  • Gain an understanding of how to retrieve group information.
  • Gain an understanding of how to allow players to interact with groups.
  • Gain an understanding of how to send group-related notifications to the player.

Prerequisites

You will need access to:

  • The AGS Admin Portal.
  • The AccelByte Unreal or Unity SDK, including the required permissions:
    • Client ID
    • Client Secret
  • The AGS Group API documentation for reference.

Manage groups

The following sections detail how to integrate group management into your game.

Create a new group

You can allow your players to create a new group once you have a group configuration in your namespace. The player who created the group will be group admin by default. Use the following function to create a new group:

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FAccelByteModelsCreateGroupRequest RequestContent = {};
RequestContent.ConfigurationCode = "YourGroupConfigurationCode";
RequestContent.GroupName = "YourGroupName";
RequestContent.GroupDescription = "YourGroupDescription";
RequestContent.GroupMaxMember = 50;
RequestContent.GroupType = EAccelByteGroupType::PUBLIC;

ApiClient->Group.CreateGroup(RequestContent, THandler<FAccelByteModelsGroupInformation>::CreateLambda([](const FAccelByteModelsGroupInformation& Result)
{
// Do something if CreateGroup is successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// Do something if CreateGroup has an error
}));

Update group information

Information that is tied to a specific group, such as a group name, icon, description, region, or type, can be updated. Only members with an admin role can update the group’s information. Use this function to update group information:

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString GroupId = "YourGroupId";
bool bCompletelyReplace = true;

FAccelByteModelsGroupUpdatable UpdateContent = {};
UpdateContent.GroupName = "UpdatedGroupName";
UpdateContent.GroupDescription = "UpdatedGroupDescription";
UpdateContent.GroupType = EAccelByteGroupType::PRIVATE;

ApiClient->Group.UpdateGroup(GroupId, bCompletelyReplace, UpdateContent, THandler<FAccelByteModelsGroupInformation>::CreateLambda([](const FAccelByteModelsGroupInformation& Result)
{
// Do something if UpdateGroup is successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// Do something if UpdateGroup has an error
}));

Update a group’s custom attributes

You can update a group’s custom attributes separately using this function. Just like updating group information, only members with an admin role can update the group’s custom attributes.

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString GroupId = "YourGroupId";

FJsonObjectWrapper UpdatedCustomAttributes;
UpdatedCustomAttributes.JsonObject = MakeShared<FJsonObject>();
UpdatedCustomAttributes.JsonObject->SetStringField("Attribute String Key", "Updated Attribute");

FAccelByteModelsUpdateGroupCustomAttributesRequest UpdateContent = {};
UpdateContent.CustomAttributes = UpdatedCustomAttributes;

ApiClient->Group.UpdateGroupCustomAttributes(GroupId, UpdateContent, THandler<FAccelByteModelsGroupInformation>::CreateLambda([](const FAccelByteModelsGroupInformation& Result)
{
// Do something if UpdateGroupCustomAttributes is successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// Do something if UpdateGroupCustomAttributes has an error
}));

Display group information

The following sections detail how to display different types of group information.

Retrieve a list of groups

You can allow your players to search the available groups created by the players by searching using a group name or region. The results will be appear in pages, and you can use offset and limit parameters to limit the list. Use the following function to retrieve a list of groups:

note

The function below only shows PUBLIC and OPEN groups. You can learn more about group types in the section on group interactions.

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FAccelByteModelsGetGroupListRequest FilterContent = {};
FilterContent.GroupName = "YourGroupName";
FilterContent.GroupRegion = "US";

ApiClient->Group.GetGroupList(FilterContent, THandler<FAccelByteModelsGetGroupListResponse>::CreateLambda([](const FAccelByteModelsGetGroupListResponse& Result)
{
// Do something if GetGroupList is successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// Do something if GetGroupList has an error
}));

Retrieve group information by group ID

To give more clear information about the group to the players, you can use the following function to get information about a group by using the group ID:

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString GroupId = "YourGroupId";

ApiClient->Group.GetGroup(GroupId, THandler<FAccelByteModelsGroupInformation>::CreateLambda([](const FAccelByteModelsGroupInformation& Result)
{
// Do something if GetGroup is successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// Do something if GetGroup has an error
}));

Retrieve group information by user ID

You can let your players get their group information by using their user Id with the following function:

note

If the player you requested doesn't belong to any group, the returned status will be ErrorCode.UserNotBelongToAnyGroup, and the player will be able to be invited to a group.

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString UserId = "YourUserId";

ApiClient->Group.GetUserGroupInfoByUserId(UserId, THandler<FAccelByteModelsGetUserGroupInfoResponse>::CreateLambda([](const FAccelByteModelsGetUserGroupInfoResponse& Result)
{
// Do something if GetUserGroupInfoByUserId is successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// Do something if GetUserGroupInfoByUserId has an error
}));

Retrieve a player’s group information

You can allow your player to retrieve the group information of the user with a specific user Id.

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString UserId = "YourUserId";

ApiClient->Group.GetUserGroupInfoByUserId(UserId, THandler<FAccelByteModelsGetUserGroupInfoResponse>::CreateLambda([](const FAccelByteModelsGetUserGroupInfoResponse& Result)
{
// Do something if GetUserGroupInfoByUserId is successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// Do something if GetUserGroupInfoByUserId has an error
}));

Retrieve a group’s member list

You can let your players retrieve a list of members within a specific group. Use the following function to get a group’s member list by using a group Id.

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString GroupId = "YourGroupId";

FAccelByteModelsGetGroupMembersListByGroupIdRequest RequestContent = {};
RequestContent.Limit = 100;
RequestContent.Offset = 0;
RequestContent.SortBy = EAccelByteGroupListSortBy::ASCENDING;

ApiClient->Group.GetGroupMembersListByGroupId(GroupId, RequestContent, THandler<FAccelByteModelsGetGroupMemberListResponse>::CreateLambda([](const FAccelByteModelsGetGroupMemberListResponse& Result)
{
// Do something if GetGroupMembersListByGroupId is successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// Do something if GetGroupMembersListByGroupId has an error
}));

Interact with groups

The follow sections details players' interactions with groups.

Join a group

Players can request to join OPEN or PUBLIC groups. Each group type will have a different behavior:

  • OPEN groups will allow players to automatically join.
  • PUBLIC groups will require players to make a join request which needs to be approved by a group admin before the player can join.

Use the following function to allow players join to a specific group.

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString GroupId = "YourGroupId";

ApiClient->Group.JoinGroup(GroupId, THandler<FAccelByteModelsJoinGroupResponse>::CreateLambda([](const FAccelByteModelsJoinGroupResponse& Result)
{
// Do something if JoinGroup is successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// Do something if JoinGroup has an error
}));

Cancel a join request

After a player requests to join a PUBLIC group, that request can be canceled.

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString GroupId = "YourGroupId";

ApiClient->Group.CancelJoinGroupRequest(GroupId, THandler<FAccelByteModelsMemberRequestGroupResponse>::CreateLambda([](const FAccelByteModelsMemberRequestGroupResponse& Result)
{
// Do something if CancelJoinGroupRequest is successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// Do something if CancelJoinGroupRequest has an error
}));

Leave a group

To allow players to leave a group, you can use the following function:

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

ApiClient->Group.LeaveGroup(THandler<FAccelByteModelsMemberRequestGroupResponse>::CreateLambda([](const FAccelByteModelsMemberRequestGroupResponse& Result)
{
// Do something if LeaveGroup is successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// Do something if LeaveGroup has an error
}));

Invite a player to a group

Group admins can invite players to join their group. A PRIVATE group can use this function to add new members. Players need to accept the invitation before they can join the group.

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString UserId = "YourUserId";

ApiClient->Group.InviteUserToGroup(UserId, THandler<FAccelByteModelsMemberRequestGroupResponse>::CreateLambda([](const FAccelByteModelsMemberRequestGroupResponse& Result)
{
// Do something if InviteUserToGroup is successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// Do something if InviteUserToGroup has an error
}));

Remove/kick a group member

Group admins can also remove (kick) group members from the group.

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString UserId = "YourUserId";

ApiClient->Group.KickGroupMember(UserId, THandler<FAccelByteModelsKickGroupMemberResponse>::CreateLambda([](const FAccelByteModelsKickGroupMemberResponse& Result)
{
// Do something if KickGroupMember is successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// Do something if KickGroupMember has an error
}));

Get a list of group invitation requests

Players can get the list of group invitation requests to either accept or reject these invitations.

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FAccelByteModelsLimitOffsetRequest RequestContent = {};
RequestContent.Limit = 100;
RequestContent.Offset = 0;

ApiClient->Group.GetGroupInvitationRequests(RequestContent, THandler<FAccelByteModelsGetMemberRequestsListResponse>::CreateLambda([](const FAccelByteModelsGetMemberRequestsListResponse& Result)
{
// Do something if GetGroupInvitationRequests is successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// Do something if GetGroupInvitationRequests has an error
}));

Accept a group invitation request

After getting the invitation list, players can accept an invitation.

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString GroupId = "YourGroupId";

ApiClient->Group.AcceptGroupInvitation(GroupId, THandler<FAccelByteModelsMemberRequestGroupResponse>::CreateLambda([](const FAccelByteModelsMemberRequestGroupResponse& Result)
{
// Do something if AcceptGroupInvitation is successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// Do something if AcceptGroupInvitation has an error
}));

Reject a group invitation request

Players can reject any invitation request.

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString GroupId = "YourGroupId";

ApiClient->Group.RejectGroupInvitation(GroupId, THandler<FAccelByteModelsMemberRequestGroupResponse>::CreateLambda([](const FAccelByteModelsMemberRequestGroupResponse& Result)
{
// Do something if RejectGroupInvitation is successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// Do something if RejectGroupInvitation has an error
}));

Get a list of group member join requests

Group admins can get a list of group member join requests to either approve or reject them.

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString GroupId = "YourGroupId";

FAccelByteModelsLimitOffsetRequest RequestContent = {};
RequestContent.Limit = 100;
RequestContent.Offset = 0;

ApiClient->Group.GetGroupJoinRequests(GroupId, RequestContent, THandler<FAccelByteModelsGetMemberRequestsListResponse>::CreateLambda([](const FAccelByteModelsGetMemberRequestsListResponse& Result)
{
// Do something if GetGroupJoinRequests is successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// Do something if GetGroupJoinRequests has an error
}));

Accept a group member join request

After getting the list of join requests, a group admin can accept them to the group.

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString UserId = "YourUserId";

ApiClient->Group.AcceptGroupJoinRequest(UserId, THandler<FAccelByteModelsMemberRequestGroupResponse>::CreateLambda([](const FAccelByteModelsMemberRequestGroupResponse& Result)
{
// Do something if AcceptGroupJoinRequest is successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// Do something if AcceptGroupJoinRequest has an error
}));

Reject a group member join request

Group admins can reject any member join request.

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString UserId = "YourUserId";

ApiClient->Group.RejectGroupJoinRequest(UserId, THandler<FAccelByteModelsMemberRequestGroupResponse>::CreateLambda([](const FAccelByteModelsMemberRequestGroupResponse& Result)
{
// Do something if RejectGroupJoinRequest is successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// Do something if RejectGroupJoinRequest has an error
}));

Manage group roles

Every group member has roles assigned to them which can be used to restrict or allow access to features such as inviting a member or kicking a member, among others. Every group member will be automatically assigned to the default member role that is already defined in the group configuration. This can either be an admin group role or a member group role.

Get a list of group member roles

An admin can get a list of the member roles that have already been created in the AGS Admin Portal.

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FAccelByteModelsLimitOffsetRequest RequestContent = {};
RequestContent.Limit = 100;
RequestContent.Offset = 0;

ApiClient->Group.GetMemberRoles(RequestContent, THandler<FAccelByteModelsGetMemberRolesListResponse>::CreateLambda([](const FAccelByteModelsGetMemberRolesListResponse& Result)
{
// Do something if GetMemberRoles is successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// Do something if GetMemberRoles has an error
}));

Promote a member to a role

A group admin can promote a group member to a specific role if the role has been defined for that group.

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString MemberRoleId = "YourMemberRoleId";

FAccelByteModelsUserIdWrapper RequestContent = {};
RequestContent.UserId = "YourUserId";

ApiClient->Group.AssignMemberRole(MemberRoleId, RequestContent, THandler<FAccelByteModelsGetUserGroupInfoResponse>::CreateLambda([](const FAccelByteModelsGetUserGroupInfoResponse& Result)
{
// Do something if AssignMemberRole is successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// Do something if AssignMemberRole has an error
}));

Remove a member’s role

An admin can remove a role from a member.

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString MemberRoleId = "YourMemberRoleId";

FAccelByteModelsUserIdWrapper RequestContent = {};
RequestContent.UserId = "YourUserId";

ApiClient->Group.DeleteMemberRole(MemberRoleId, RequestContent, FVoidHandler::CreateLambda([]()
{
// Do something if DeleteMemberRole is successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// Do something if DeleteMemberRole has an error
}));

Manage group notifications

Some group activities will trigger notifications that will be sent to individual players, to group admins, or to all group members. The notification payload will be a JSON formatted string that contains data related to the triggered activity. To retrieve these notifications, you need to add a callback to the SetMessageNotifDelegate and the OnNotification functions.

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

ApiClient->Lobby.Connect();

FString NotificationTopic = "group";

ApiClient->Lobby.SetMessageNotifDelegate(AccelByte::Api::Lobby::FMessageNotif::CreateLambda([&](FAccelByteModelsNotificationMessage const& Notif)
{
if (Notif.Topic == NotificationTopic)
{
// Do something if there's a new notification under group topic
}
}));

Notify a player of a group invitation

Here’s an example of the payload for a notification sent to a player when they’ve been invited to join a group:

{
"groupName": "nameOfGroup",
"groupId": "groupId",
"kind": "invitation"
}

Notify a player of an accepted join request

Here’s an example of the payload for a notification sent to a player when their request to join a group has been accepted:

{
"groupName": "nameOfGroup",
"groupId": "groupId",
"kind": "accepted-request"
}

Notify a player of a rejected join request

Here’s an example of the payload for a notification sent to a player when their request to join a group has been rejected:

{
"groupName": "nameOfGroup",
"groupId": "groupId",
"kind": "rejected-request"
}

New Group Member Notifications

Here’s an example of the payload for a notification sent to all group members when a new member has joined their group:

{
"groupName": "nameOfGroup",
"groupId": "groupId",
"newGroupMember": "newGroupMember",
"kind": "new-member"
}

Notify a group admin of a request to join a group

Here’s an example of the payload for a notification sent to group admins when a player has requested to join their group:

{
"groupName": "nameOfGroup",
"groupId": "groupId",
"newGroupMember": "newGroupMember",
"kind": "join-request"
}

Notify a player of a new role assignment

Here’s an example of the payload for a notification sent to a player when a group admin has assigned a role to them:

{
"groupName": "nameofgroup",
"groupId": "groupId",
"roleName": "Chief",
"roleId": "roleId",
"kind": "assigned-role"
}

Notify a member of a role removal

Here’s an example of the payload for a notification sent to a player when a group admin has removed a role from them:

{
"groupName": "nameofgroup",
"groupId": "groupId",
"roleName": "Chief",
"roleId": "roleId",
"kind": "removed-role"
}