Last Updated: 8/16/2022, 9:10:37 AM

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

# Prerequisites

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

# Permissions

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

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 or Roles assigned to users. For more information, read the Authentication and Authorization documentation.

# Managing Groups in the Admin Portal

# Create a New Group Role

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

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

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

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

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

Click Add when you’re done.

# Create a New Group Configuration

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

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.

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

# Add Custom Attributes

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

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.

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

Fill out the custom attributes in JSON format.

When you’re done, click Save.

# Implementing Groups using 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.

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

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

# Cancel Join Request

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

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

# Connecting Custom Services to Group using the Server SDK

# SDK Initialization

Before using the Groups 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.

Access

Analytics

Distribution

Engagement

Social

Monetization

Storage

Play