Groups

Overview

AccelByte Cloud’s Groups service allows players to gather to chat and play together. By implementing this service, you players can create, join, and invite other players to groups. Group admins can also manage join requests and add or remove members from their groups. The Groups service can be integrated with other services such as Lobby (opens new window), Statistics (opens new window), and Leaderboards (opens new window) to extend its functionality, e.g., 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.

Prerequisites

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

Permissions

Permissions (opens new window) are used to grant access to specific resources within our services. Make sure your account has the following permissions before you attempt to manage groups in the Admin Portal. For a full list of permissions that impact groups management, see the Groups tab of the Permissions Reference (opens new window).

Usage	Resource	Action
List Group Configuration	ADMIN:NAMESPACE:{namespace}:GROUP:CONFIGURATION	Read
Create New Configuration	ADMIN:NAMESPACE:{namespace}:GROUP:CONFIGURATION	Create
Initiate Configuration	ADMIN:NAMESPACE:{namespace}:GROUP:CONFIGURATION	Create
Get Existing Configuration	ADMIN:NAMESPACE:{namespace}:GROUP:CONFIGURATION	Read
Delete Group Configuration	ADMIN:NAMESPACE:{namespace}:GROUP:CONFIGURATION	Delete
Update Existing Configuration	ADMIN:NAMESPACE:{namespace}:GROUP:CONFIGURATION	Update
Update Existing Configuration Global Rule	ADMIN:NAMESPACE:{namespace}:GROUP:CONFIGURATION	Update
Delete Existing Configuration Global Rule Based On Allowed Action	ADMIN:NAMESPACE:{namespace}:GROUP:CONFIGURATION	Update
Get List Of Groups	ADMIN:NAMESPACE:{namespace}:GROUP	Read
Get Single Group	ADMIN:NAMESPACE:{namespace}:GROUP	Read
Delete Existing Group	ADMIN:NAMESPACE:{namespace}:GROUP:{groupId}	Delete
Get a List Of Group Members	ADMIN:NAMESPACE:{namespace}:GROUP:MEMBER	Read
Get All List Of Member Roles	ADMIN:NAMESPACE:{namespace}:GROUP:ROLE	Read
Create New Member Role	ADMIN:NAMESPACE:{namespace}:GROUP:ROLE	Create
Get the Member Role	ADMIN:NAMESPACE:{namespace}:GROUP:ROLE	Read
Delete Member Role	ADMIN:NAMESPACE:{namespace}:GROUP:ROLE	Delete
Update Member Role	ADMIN:NAMESPACE:{namespace}:GROUP:ROLE	Update
Update Member Role Permission	ADMIN:NAMESPACE:{namespace}:GROUP:ROLE	Update

Permissions work slightly differently depending on whether they are assigned to IAM Clients (opens new window) or Roles (opens new window) assigned to users. For more information, read the Authentication and Authorization (opens new window) documentation.

Manage Groups in the Admin Portal

Create a New Group Role

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

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.

2. A pop-up window appears. Here, input the Role Name for your new role. Note that Role will appear when you add the Group Configuration later.

Once completed, click Submit.

Create a New Group Configuration

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

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.

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

Add Custom Attributes

You can add custom attributes or custom parameters to customize your group information based on your preferences.

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

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

4. Fill out the custom attributes in JSON format.

When you’re done, click Save.

Implement Groups using the Client SDKs

Manage 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.

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.

Retrieve Group Information

Get information about a group by using the Group ID.

Retrieve a Player’s Group Information

You can get your current player’s group information by 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.

Retrieve Other Player’s Group Information

This function is to call the group information of other users with a specific user ID.

Retrieve a Group’s Member List

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

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.

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.

Group Interactions

Join a 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.

Cancel Join Request

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

Leave a Group

To leave a group, you can use this function.

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.

Kick a Group Member

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

Get a List of Group Invitation Requests

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

Accept Group Invitation Request

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

Reject Group Invitation Request

Players can also reject any invitation request.

Get List of Group Member Join Requests

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

Accept Group Member Join Request

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

Reject Group Member Join Request

Group admin can also reject any member join request.

Get Bulk Users’ Presence

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

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 a List of Group Member Roles

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

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.

Remove a Member’s Role

An admin can also remove a role from a member.

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.

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

Connect Custom Services to Groups using the Server SDKs

SDK Initialization

Before using the Cloud Groups (opens new window) service from the SDK, you will need to initialize your server-side SDK to ensure you are authorized and able to perform create, read, update, and delete actions.

Golang SDK Initialization

Before using the Groups service from the Golang SDK, you will need to initialize the SDK by following the steps below:

• Create your OAuth Client and assign the necessary permissions to access the IAM service.
• Log in as a Client using the SDK.
• Initialize the OAuth 2.0 service using the following function (opens new window):

Once completed, you can use the Golang SDK to create, read, update, and delete Groups (opens new window) from your serverless app.

Python SDK Initialization

Before using the Groups service from the Python SDK, you will need to initialize the SDK by following the steps below:

• Create your OAuth Client and assign the necessary permissions to access the Matchmaking service.
• Log in as a Client using the SDK.

Once completed, you can use the Python SDK to create, read, update, and delete Groups (opens new window) from your serverless app.

To use the Group Service, make sure you have the necessary permissions.

.NET (C#) SDK Initialization

Before using the Group service, you will need to set some permissions. Use the following .NET namespaces:

    using AccelByte.Sdk.Api.Group.Model;
    using AccelByte.Sdk.Api.Group.Operation;
    using AccelByte.Sdk.Api.Group.Wrapper;

Java SDK Initialization

Before using the Group service, you will need to set some permissions. Initialize the Group wrapper from the Group service using the following code:

Group wGroup = new Group(sdk);

Once completed, you can use the SDK to create, read, update, or delete groups.

To use the Group Service, make sure you have the necessary permissions (opens new window).

Create a Group

Use the following function to create a group (opens new window):

Delete a Group

Use the following function to delete a group (opens new window):

Retrieve a Group

Use the following function to retrieve a group (opens new window):

Update a Group

Use the following function to update a group (opens new window):