Groups

Overview

The Groups service allows players to gather to chat and play together. 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 remove members from their group. The Groups service can be integrated with other services such as 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.

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 first wait for a group admin to approve their request. These groups often have membership requirements, such as only allowing players with an MMR more than 100 to join the group.
  • Private Groups can’t be searched and require permission to join. Players can only join these groups if they’ve been invited by an admin.

Tutorials

Make sure you’ve read about Roles Management to know the basics of creating a role.

Initiate a Group Configuration in the API

Initiating a group configuration will automatically create a default configuration and member roles with default permissions, as follows:

  • Invite players to a group
  • Accept or reject join requests from groups
  • Kick a group member

The default maximum number of members will be 50 and global rules will be empty. Follow the steps below to initiate a group configuration.

  1. Use the Initiate Configuration: POST - /group/v1/admin/namespaces/{namespace}/configuration/initiate endpoint.
  2. Input the Namespace where you want the group to belong.

Create a New Group Role

  1. On the Group Roles page in the Admin Portal, click the Add Role button.

    group

  2. A pop up window appears. Here, input the Role Name for your new role. Click Submit when you’re done.

Add New Permissions to a Group Role

  1. In the Admin Portal, go to the Group Role you created earlier, and in the Group Role Detail click the Add Permission button.

    group

  2. A pop up window appears. Fill in the required fields:

    • Input the Permission with the appropriate format.
    • Choose the Action of the permission.

    group

    Click Add when you’re done.

Create a New Group Configuration

  1. On the Group Configurations page of the Admin Portal, click the Add Configuration button.

    group

  2. Once the form appears, fill in the fields as shown below:

    • Input the configuration Code with the appropriate format. E.g. group-clan.
    • Input the configuration Name.
    • Input athe Description of the configuration.
    • Input the Maximum Group Members.
    • Select the Group Admin Role.
    • Select the Group Member Role.

    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.

    group

  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 attributes to a group.

    group

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

    group

  4. Fill out the custom attributes in JSON format.

    group

    When you’re done, click Save.

Integrate the Group Service with the 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.

CreateGroupRequest createGroupRequest = new CreateGroupRequest
{
configurationCode = "initialConfigurationCode",
groupDescription = "This is My Fabulous Group",
groupName = "MyFabulousGroup",
groupRegion = "US",
groupType = GroupType.OPEN,
customAttributes = new Dictionary<string, object> {
{"numIsland", 2 }, {"waterReserve", 125.10 }, {"countryName", "happyland" }
}
};
AccelBytePlugin.GetGroup().CreateGroup(createGroupRequest, result =>
{
Debug.Log("GroupId: " + result.Value.groupId);
Debug.Log("GroupName: " + result.Value.groupName);
Debug.Log("GroupRegion: " + result.Value.groupRegion);
});
Retrieve a List of Groups

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 = "FabulousGroup";
string groupRegion = "US";
int offset = 0;
int limit = 20;
AccelBytePlugin.GetGroup().SearchGroups(groupName, groupRegion, limit, offset, result =>
{
foreach(var group in result.Value.data)
{
Debug.Log("GroupId: " + group.groupId);
Debug.Log("GroupName: " + group.groupName);
Debug.Log("GroupRegion: " + group.groupRegion);
}
});
Retrieve Group Information

Get information about a group by using the Group ID.

string groupId = "123456789";
AccelBytePlugin.GetGroup().GetGroup(groupId, result =>
{
Debug.Log("GroupId: " + result.Value.groupId);
Debug.Log("GroupName: " + result.Value.groupName);
Debug.Log("GroupRegion: " + result.Value.groupRegion);
});
Retrieve a Player’s Group Information

You can get a player’s group information using this function. 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. Otherwise, the following values could be returned:

StatusRemarks
INVITEThe player is invited to a group.
JOINThe player is ready to join a group
JOINEDThe player is already a member of the group
AccelBytePlugin.GetGroup().GetMyGroupInfo(result=>
{
Debug.Log("GroupId: " + result.Value.groupId);
Debug.Log("Status: " + result.Value.status.ToString());
for(string memberRole in result.Value.memberRoleId)
{
Debug.Log("RoleId: " + memberRole);
}
});
string otherUserId = "123456789";
AccelBytePlugin.GetGroup().GetOtherGroupInfo(otherUserId, result=>
{
Debug.Log("GroupId: " + result.Value.groupId);
Debug.Log("Status: " + result.Value.status.ToString());
for(string memberRole in result.Value.memberRoleId)
{
Debug.Log("RoleId: " + memberRole);
}
});
Retrieve a Group’s Member List

Use this function to get a group’s member list.

string groupId = "123456789";
AccelBytePlugin.GetGroup().GetGroupMemberList(groupId, result =>
{
foreach(var member in result.Value.data)
{
Debug.Log("UserId: " + member.userId);
Debug.Log("GroupId: " + member.groupId);
}
});
Update Group Information

A group’s information such as its name, icon, description, region, and type can be updated with this function. Only members with an admin role can update the group’s information.

string groupId = "123456789";
UpdateGroupRequest updateGroupRequest = new UpdateGroupRequest
{
groupRegion = "ID",
groupDescription = "This Group information was changed",
groupName = "StillFabulousGroup",
groupType = GroupType.PRIVATE,
customAttributes = new Dictionary<string, object> {
{"numIsland", 3 }, {"waterReserve", 115.10 }, {"countryName", "happyland" }
}
};
AccelBytePlugin.GetGroup().UpdateGroup(groupId, updateGroupRequest, result =>
{
Debug.Log("GroupId: " + result.Value.groupId);
Debug.Log("GroupName: " + result.Value.groupName);
Debug.Log("GroupRegion: " + result.Value.groupRegion);
});
Update a Group’s Custom Attributes

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

string groupId = "123456789";
var customAttributes = new Dictionary<string, object> {
{"numIsland", 3 }, {"waterReserve", 115.10 }, {"countryName", "happyland" }};
AccelBytePlugin.GetGroup().UpdateGroupCustomAttributes(groupId, customAttributes, result =>
{
Debug.Log("Update Success!");
});

Group Interaction

Join Group

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

string groupId = "123456789";
AccelBytePlugin.GetGroup().JoinGroup(groupId, result =>
{
Debug.Log("JoinStatus: " + result.Value.status.ToString());
});
Cancel Join Request

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

string groupId = "123456789";
AccelBytePlugin.GetGroup().CancelJoinGroupRequest(groupId, result =>
{
if(!result.IsError)
{
Debug.Log("Successfully cancel the join request!");
}
else
{
Debug.Log("Failed to cancel the join request. Error: " + result.Error.Code + " | Message: " + result.Error.Message);
}
});
Invite a Player To 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 the invitation before they can join the group.

string userId = "123456789";
AccelBytePlugin.GetGroup().InviteOtherUserToGroup(userId, result =>
{
Debug.Log("Successfully invite user to the group!");
});
Leave Group

To leave a group, you can use this function.

AccelBytePlugin.GetGroup().LeaveGroup(result =>
{
Debug.Log("Successfully leave the group");
});
Kick a Group Member

Group admins can also kick group members out of the group.

string userId = "123456789";
AccelBytePlugin.GetGroup().KickGroupMember(userId, result =>
{
Debug.Log("UserId: " + result.Value.kickedUserId + ", was kicked from the group.");
});
Get List of Group Invitation Requests

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

AccelBytePlugin.GetGroup().GetGroupInvitationRequests(result =>
{
foreach(var request in result.Value.data)
{
Debug.Log("GroupId: " + request.groupId);
}
});
Get List of Group Member Join Requests

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

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

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

string groupId = "123456789";
AccelBytePlugin.GetGroup().AcceptGroupInvitation(groupId, result =>
{
Debug.Log("Invitation Accepted!");
});
Reject Group Invitation Request

Players can also reject any invitation request.

string groupId = "123456789";
AccelBytePlugin.GetGroup().RejectGroupInvitation(groupId, result =>
{
Debug.Log("Invitation Rejected!");
});
Accept Group Member Join Request

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

string userId = "123456789";
AccelBytePlugin.GetGroup().AcceptOtherJoinRequest(userId, result =>
{
Debug.Log("Join Request Accepted!");
});
Reject Group Member Join Request

Group admin can also reject any member join request.

string userId = "123456789";
AccelBytePlugin.GetGroup().RejectOtherJoinRequest(userId, result =>
{
Debug.Log("Join Request Rejected!");
});
Get Bulk Users’ Presence

You can use this endpoint to get users’ presence information in bulk.

var userIds = new List<string>();
userIds.Add("123456789");
userIds.Add("987654321");
AccelBytePlugin.GetLobby().BulkGetUserPresence(userIds, result =>
{
if(!result.IsError)
{
foreach( var user in result.Value.data)
{
Debug.Log("UserId: " + user.userID + " | Availability: " + user.availability.ToString());
}
}
else
{
Debug.Log("Error: " + result.Error.Code + " | Message: " + result.Error.Message);
}
});

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, kicking a member, etc. Every group member will automatically be assigned to the default member role that is already defined in the group configuration. This can be either an admin group role or a member group role.

Get List of Group Member Roles

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

AccelBytePlugin.GetGroup().GetMemberRoles(result =>
{
foreach(var memberRole in result.Value.data)
{
Debug.Log("MemberRoleId: " + memberRole.memberRoleId);
Debug.Log("MemberRoleName: " + memberRole.memberRoleName);
}
});
Promote a Member to a Role

An admin can promote a member to a specific role, as long as the role has been defined for that group.

string memberRoleId = "123456789";
string userId = "987654321";
AccelBytePlugin.GetGroup().AssignRoleToMember(memberRoleId, userId, result =>
{
if(!result.IsError)
{
Debug.Log("Member promoted successfully.");
}
});
Remove a Member’s Role

An admin can also remove a role from a member.

string memberRoleId = "123456789";
string userId = "987654321";
AccelBytePlugin.GetGroup().RemoveRoleFromMember(memberRoleId, userId, result =>
{
if(!result.IsError)
{
Debug.Log("Member role removed successfully.");
}
});

Group Notifications

Some group activity 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 OnNotification function.

AccelBytePlugin.GetLobby().OnNotification += result =>
{
If(result.Value.topic == "group")
{
Debug.Log("Got Group Notification with Message Payload: " + result.Value.payload);
}
};
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"
}

And here’s the payload if a group admin removes a role from a player:

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