Integrate groups into your game

Last updated on October 24, 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 Client SDK or Extend SDK.

This article walks you through how to:

  • Integrate groups into your game with Client SDKs or Extend SDKs.
  • Allow players to manage groups.
  • Retrieve group information.
  • Allow players to interact with groups.
  • Send group-related notifications to the player.

Prerequisites​

You will need access to:

  • The AGS Admin Portal.
  • The AccelByte Unreal SDK, Unity SDK or Extend 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 succeeds
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if CreateGroup fails
}));

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 succeeds
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if UpdateGroup fails
}));

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 succeeds
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if UpdateGroupCustomAttributes fails
}));

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 succeeds
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if GetGroupList fails
}));

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 succeeds
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if GetGroup fails
}));

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 succeeds
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if GetUserGroupInfoByUserId fails
}));

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 succeeds
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if GetUserGroupInfoByUserId fails
}));

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 succeeds
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if GetGroupMembersListByGroupId fails
}));

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 succeeds
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if JoinGroup fails
}));

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 succeeds
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if CancelJoinGroupRequest fails
}));

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 succeeds
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if LeaveGroup fails
}));

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 succeeds
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if InviteUserToGroup fails
}));

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 succeeds
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if KickGroupMember fails
}));

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 succeeds
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if GetGroupInvitationRequests fails
}));

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 succeeds
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if AcceptGroupInvitation fails
}));

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 succeeds
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if RejectGroupInvitation fails
}));

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 succeeds
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if GetGroupJoinRequests fails
}));

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 succeeds
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if AcceptGroupJoinRequest fails
}));

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 succeeds
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if RejectGroupJoinRequest fails
}));

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 succeeds
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if GetMemberRoles fails
}));

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 succeeds
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if AssignMemberRole fails
}));

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 succeeds
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if DeleteMemberRole fails
}));

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"
}

Last updated on

On this page