Skip to main content

Groups

Last updated on

Overview

AccelByte Foundations’ Groups service allows players to gather together to chat and play matches with one another. This service allows players to create, join, and invite other players to groups. Group admins can also manage join requests and add members to or from their groups. AccelByte Foundations’ Groups service can be integrated with other services such as the Lobby, Statistics, and Leaderboards to extend its functionality. For example, you can create groups for players that have achieved a specific level or rank in your game, helping to make groups more evenly balanced and boost player engagement and enjoyment in your games.

How It Works

Group Types

There are three types of groups that can be created:

  • Open Groups are searchable and do not require any approval to join. A player can search for the group using the Group Name or Group Code, and then join the group without waiting for a group admin to approve their request.
  • Public Groups are searchable but require permission to join. When a player tries to join, they must wait for a group admin to approve their request. These groups often have membership requirements, such as only allowing players with an MMR of more than 100 to join the group.
  • Private Groups can’t be searched for and require permission to join. Players can only join these groups if they’ve been invited by an admin.

Managing Groups in the Admin Portal

Create a New Group Role

  1. Open the desired game title and expand the Game Management, select Group Management, and click Roles.

  2. On the Group Roles page, click Add Role.

    group

  3. The Add Role form will appear. Type the name for your new role and click Submit when you’re done.

    group

Add New Permissions to a Group Role

  1. Go to the Group Role you created earlier and click the Add Permission button.

    group

  2. The Add Permission form will appear.

    group

    • Input the type of Permission by using the standard resource format, e.g., GROUP:JOIN, GROUP:KICK. Separate permissions with a comma (,).

    • Choose the Action of the permission.

    Refer to the table below for the types of permissions you can implement.

    UsagePermissionAction
    Delete and update existing groupGROUPRead, Update, Delete
    Invite a player to a groupGROUP:INVITECreate
    Accept and reject group join requestGROUP:JOINCreate
    Kick a player from a groupGROUP:KICKCreate
    Get list of all member rolesGROUP:ROLERead
    Assign a role to a memberGROUP:ROLEUpdate
  3. Click Add when you’re done.

Create a New Group Configuration

  1. Expand the Group Management menu and click the Create Configuration button.

    group

  2. The Create Configuration form will appear. Fill in the required fields:

    • Input the configuration Code with the appropriate format, e.g., group-clan.
    • Input the configuration Name.
    • Input a Description of the configuration.
    • Input the Maximum Group Members as a number.
    • Select the Group Admin Role associated with this group.
    • Select the Group Member Role associated with this group.

    group

  3. Click Add. Your new configuration will be added to the list.

Add Custom Attributes

  1. In the Group Management dropdown of the Admin Portal, click the List menu.

  2. Choose the group you want to add the custom attributes to by clicking the View button. Make sure that you have permission to add the required attributes to a group.

    group

  3. On the Group Details, click the Add Custom Attributes button.

  4. Fill out the custom attributes in JSON format.

    group

  5. Once completed, click Save.

Implementing Groups using the Unity SDK

Managing Groups

Create a New Group

You can create a new group once you have a group configuration in your namespace. The members of your group will be admins by default.

RuleInformation ruleInformation = new RuleInformation
{
ruleAttribute = "MyRuleAttribute",
ruleCriteria = RuleCriteria.MAXIMUM,
ruleValue = 50.0f
};

Rules rules = new Rules
{
allowedAction = AllowedAction.joinGroup,
ruleDetail = [ruleInformation]
};

GroupRules groupRules = new GroupRules
{
groupCustomRule = {},
groupPredefinedRules = [rules]
};

CreateGroupRequest createGroupRequest = new CreateGroupRequest
{
groupName = "MyNewGroupName",
groupType = GroupType.OPEN,
groupMaxMember = 25,
groupDescription = "MyNewGroupDescription",
groupIcon = "https://example.com",
groupRegion = "US",
groupRules = groupRules,
configurationCode = "MyConfiguration Code",
customAttributes = new Dictionary<string, object>
{
{ "sword", 3 },
{ "armor", 7 }
}
};

AccelBytePlugin.GetGroup().CreateGroup(createGroupRequest, result =>
{
if (result.IsError)
{
// Do something if CreateGroup has an error
Debug.Log($"Error CreateGroup, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
}
else
{
// Do something if CreateGroup has been successful
}
});

Retrieve a List of Groups

Use the following function to search for a group by its name or region. The results will be paginated, and you can use offset and limit parameters to limit the list. This function only shows PUBLIC and OPEN groups.


string groupName = "SomeGroupName"; // You can leave it blank if you want to fetch all the groups
string groupRegion = "US"; // You can leave it blank if you want to fetch all the groups
int offset = 0;
int limit = 99;

AccelBytePlugin.GetGroup().SearchGroups(groupName, groupRegion, offset, limit, result =>
{
if (result.IsError)
{
// Do something if SearchGroups has an error
Debug.Log($"Error SearchGroups, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
}
else
{
// Do something if SearchGroups has been successful
}
});

Retrieve Group Information

Use the following function to retrieve information about a group by using the Group ID.

string groupId = "SomeGroupId";

AccelBytePlugin.GetGroup().GetGroup(groupId, result =>
{
if (result.IsError)
{
// Do something if GetGroup has an error
Debug.Log($"Error GetGroup, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
}
else
{
// Do something if GetGroup has been successful
}
});

Retrieve a Player’s Group Information

Use the following function to retrieve a player’s group information. If the player you requested doesn’t belong to any group, the returned status will be ErrorCode.UserNotBelongToAnyGroup.

AccelBytePlugin.GetGroup().GetMyGroupInfo(result =>
{
if (result.IsError)
{
// Do something if GetMyGroupInfo has an error
Debug.Log($"Error GetMyGroupInfo, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
}
else
{
// Do something if GetMyGroupInfo has been successful
}
});

Retrieve Other Players' Group Information

Use the following function to call the group information of other users with a specific user ID.

string userid = "SomeUserId";

AccelBytePlugin.GetGroup().GetOtherGroupInfo(userId, result =>
{
if (result.IsError)
{
// Do something if GetOtherGroupInfo has an error
Debug.Log($"Error GetOtherGroupInfo, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
}
else
{
// Do something if GetOtherGroupInfo has been successful
}
});

Retrieve a Group’s Member List

Use the following function to retrieve a group’s member list.

string groupId = "SomeGroupId";

AccelBytePlugin.GetGroup().GetGroupMemberList(groupId, result =>
{
if (result.IsError)
{
// Do something if GetGroupMemberList has an error
Debug.Log($"Error GetGroupMemberList, Error Code: {result.Error.Code} Error Code: {result.Error.Message}");
}
else
{
// Do something if GetGroupMemberList has been successful
}
});

Update Group Information

Use the following function to update a group’s information, such as its name, icon, description, region, or type. Only members with an admin role can update the group’s information.

string groupId = "SomeGroupId";

AccelBytePlugin.GetGroup().UpdateGroup(groupId, updateGroupRequest, result =>
{
if (result.IsError)
{
// Do something if UpdateGroup has an error
Debug.Log($"Error UpdateGroup, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
}
else
{
// Do something if UpdateGroup has been successful
}
});

Update a Group’s Custom Attributes

Use the following function to update a group’s custom attributes. Only members with an admin role can update the group’s custom attributes.

Dictionary<string, object> customAttributes = new Dictionary<string, object>
{
{ "requirementLevel", 50 },
{ "requirementItem", 25 }
};

string groupId = "SomeGroupId";

AccelBytePlugin.GetGroup().UpdateGroupCustomAttributes(groupId, customAttributes, result =>
{
if (result.IsError)
{
// Do something if UpdateGroupCustomAttributes has an error
Debug.Log($"Error UpdateGroupCustomAttributes, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
}
else
{
// Do something if UpdateGroupCustomAttributes has been successful
}
});

Group Interaction

Join Group

Use the following function to request to join open or public groups. An OPEN group will allow players to automatically join, whereas a PUBLIC group will require a join request to be approved by an admin before the player can join.

string groupId = "SomeGroupId";

AccelBytePlugin.GetGroup().JoinGroup(groupId, result =>
{
if (result.IsError)
{
// Do something if JoinGroup has an error
Debug.Log($"Error JoinGroup, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
}
else
{
// Do something if JoinGroup has been successful
}
});

Cancel Join Request

After a player requests to join a group, that request can be canceled. Use the following function to cancel a join request.

string groupId = "SomeGroupId";

AccelBytePlugin.GetGroup().CancelJoinGroupRequest(groupId, result =>
{
if (result.IsError)
{
// Do something if CancelJoinGroupRequest has an error
Debug.Log($"Error CancelJoinGroupRequest, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
}
else
{
// Do something if CancelJoinGroupRequest has been successful
}
});

Leave a Group

Use the following function to leave a group.

AccelBytePlugin.GetGroup().LeaveGroup(result =>
{
if (result.IsError)
{
// Do something if LeaveGroup has an error
Debug.Log($"Error LeaveGroup, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
}
else
{
// Do something if LeaveGroup has been successful
}
});

Invite a Player o a Group

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

string otherUserId = "SomeOtherUserId";

AccelBytePlugin.GetGroup().InviteOtherUserToGroup(otherUserId, result =>
{
if (result.IsError)
{
// Do something if InviteOtherUserToGroup has an error
Debug.Log($"Error InviteOtherUserToGroup, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
}
else
{
// Do something if InviteOtherUserToGroup has been successful
}
});
string userId = "123456789";
AccelBytePlugin.GetGroup().InviteOtherUserToGroup(userId, result =>
{
Debug.Log("Successfully invite user to the group!");
});

Kick a Group Member

Group admins can kick group members out of a group. Use the following function to kick a group member.

string otherUserId = "SomeOtherUserId";

AccelBytePlugin.GetGroup().KickGroupMember(otherUserId, result =>
{
if (result.IsError)
{
// Do something if KickGroupMember has an error
Debug.Log($"Error KickGroupMember, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
}
else
{
// Do something if KickGroupMember has been successful
}
});

Retrieve a List of Group Invitation Requests

Players can retrieve a list of group invitation requests in order to either accept or reject these invitations. Use the following function to retrieve a list of group requests.

AccelBytePlugin.GetGroup().GetGroupInvitationRequests(result =>
{
if (result.IsError)
{
// Do something if GetGroupInvitationRequests has an error
Debug.Log($"Error GetGroupInvitatioNRequests, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
}
else
{
// Do something if GetGroupInvitationRequests has been successful
}
});

Accept Group Invitation Request

After retrieving an invitation list, players can accept an invitation. Use the following function to accept an invitation.

string groupId = "SomeGroupId";

AccelBytePlugin.GetGroup().AcceptGroupInvitation(groupId, result =>
{
if (result.IsError)
{
// Do something if AcceptGroupInvitation has an error
Debug.Log($"Error AcceptGroupInvitation, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
}
else
{
// Do something if AcceptGroupInvitation hasbeen successful
}
});

Reject Group Invitation Request

Use the following function to reject a group invitation.

string groupId = "SomeGroupId";

AccelBytePlugin.GetGroup().RejectGroupInvitation(groupId, result =>
{
if (result.IsError)
{
// Do something if RejectGroupInvitation has an error
Debug.Log($"Error RejectGroupInvitation, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
}
else
{
// Do something if RejectGroupInvitation has been successful
}
});

Retrieve a List of Group Member Join Requests

Group admins can retrieve a list of group member join requests, to either approve or reject them. Use the following function to retrieve a list of group member join requests.

string groupId = "123456789";  
AccelBytePlugin.GetGroup().GetGroupJoinRequests(groupId, result =>
{
foreach(var request in result.Value.data)
{
Debug.Log("UserId: " + request.userId);
}
});

Accept Group Member Join Request

After getting the list of join requests, a group admin can accept them to the group. Use the following function to accept a group member join request.

string otherUserId = "SomeOtherUserId";

AccelBytePlugin.GetGroup().AcceptOtherJoinRequest(otherUserId, result =>
{
if (result.IsError)
{
// Do something if AcceptOtherJoinRequest has an error
Debug.Log($"Error AcceptOtherJoinRequest, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
}
else
{
// Do something if AcceptOtherJoinRequest has been successful
}
});

Reject Group Member Join Request

Group admin can also reject any member join request. Use the following function to accept a group member join request.

string otherUserId = "SomeOtherUserId";

AccelBytePlugin.GetGroup().RejectOtherJoinRequest(otherUserId, result =>
{
if (result.IsError)
{
// Do something if RejectOtherJoinRequest has an error
Debug.Log($"Error RejectOtherJoinRequest, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
}
else
{
// Do something if RejectOtherJoinRequest has been successful
}
});

Retrieve Bulk Users’ Presence

Use the following function to retrieve user presence information in bulk.

var userIds = new List<string>();
userIds.Add("SomeTargetUserId1");
userIds.Add("SomeTargetUserId2");
userIds.Add("SomeTargetUserId3");

AccelBytePlugin.GetLobby().Connect();
AccelBytePlugin.GetLobby().BulkGetUserPresence(userIds.ToArray(), result =>
{
if (result.IsError)
{
// Do something if BulkGetUserPresence has an error
Debug.Log($"Error BulkGetUserPresence, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
}
else
{
// Do something if BulkGetUserPresence has been successful
}
});

Group Roles

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

Retrieve a List of Group Member Roles

Use the following function to retrieve a list of the member roles that have already been created in the Admin Portal.

AccelBytePlugin.GetGroup().GetMemberRoles(result =>
{
if (result.IsError)
{
// Do something if GetMemberRoles has an error
Debug.Log($"Error GetMemberRoles, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
}
else
{
// Do something if GetMemberRoles has been successful
}
});

Promote a Member to a Role

Use the following function to promote a member to a specific role, so long as that role has been defined for that group.

string memberRoleId = "SomeMemberRoleId";
string userId = "SomeUserId";

AccelBytePlugin.GetGroup().AssignRoleToMember(memberRoleId, userid, result =>
{
if (result.IsError)
{
// Do something if AssignRoleToMember has an error
Debug.Log($"Error AssignRoleToMember, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
}
else
{
// Do something if AssignRoleToMember has been successful
}
});

Remove a Member’s Role

Use the following function to remove a role from a member.

string memberRoleId = "SomeMemberRoleId";
string userId = "SomeUserId";

AccelBytePlugin.GetGroup().RemoveRoleFromMember(memberRoleId, userid, result =>
{
if (result.IsError)
{
// Do something if RemoveRoleFromMember has an error
Debug.Log($"Error RemoveRoleFromMember, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
}
else
{
// Do something if RemoveRoleFromMember has been successful
}
});

Group Notifications

Some group activities will trigger notifications that are sent to individual players, group admins, or all group members. The notification payload is a JSON-formatted string that contains data related to triggering activities. To retrieve these notifications, you need to add a callback to the OnNotification function.

AccelBytePlugin.GetLobby().Connect();
AccelBytePlugin.GetLobby().OnNotification += result =>
{
if (result.IsError)
{
// Do something if OnNotification has an error
Debug.Log($"Error OnNotification, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
}
else
{
// Do something if OnNotification has been successful
}
};

Group Invitation Notifications

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

Group Acceptance Notifications

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

Group Rejection Notifications

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": "newGroupMemberId",
"kind": "new-member"
}

Member Request Notifications

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": "newGroupMemberId",
"kind": "join-request"
}

Member Role Assignment Notifications

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",
"newGroupMember": "newGroupMemberId",
"roleId": "roelId",
"kind": "assigned-role"
}

Here’s an example of the payload for a notification if a group admin removes a role from a player:

{  
"groupName": "nameOfGroup",
"groupId": "groupId",
"newGroupMember": "newGroupMemberId",
"roleId": "roelId",
"kind": "removed-role"
}