Design

Groups are used to associate collections of users together – useful for representing Organizations in apps, and Clans and Guilds in games.

  • When considering if your game will benefit from groups, Design should consider if it is possible to create Group-based goal and Group-based reward systems to support it. 
  • Challenges & rewards for Group-based activities will create social pressure for players in the group to engage with the game longer and more frequently. 
  • For example, to actively drive playtime, track the aggregate wins of all players in a group, placing those scores in a monthly or bi-weekly Tournament that pays rewards to top Groups. 
  • Players should have the means to Find, Join, and Leave Groups at will. 
  • Supporting Clan communication with an in-game Group Chat panel is highly recommended
  • Group sizes for social apps typically range from 25 - 50. In general, a higher Max Size is better. 

Implementation

To create a group type, go to the Group page on the dashboard.

Creating a Group Type

  • Click the [Add Item] button with the plus icon.
  • Enter a the Group Type Name. When creating a group with CreateGroup API call, your app with specify a group name, along with this group type name. 
  • Enter the Max Size of users. This number must be between 2 and 50.
  • On Owner Delete - Choose how the Group handles the owning user being deleted. 
  1. Assign New Owner - An admin currently in the group will randomly be assigned to be the group owner. If there are no admins, a member level user is selected.
  2. Delete Group - If an owner's account is deleted, the group itself is deleted.

When would I use Assign New Owner vs Delete Group? If your app is a game that offers a guild feature, and the guild owner decides to delete their account. Your game would most likely prefer a new owner to be assign, rather than the group be deleted. However, if you created a paid app, where the owner was paying for the group as a service, your app may wish the group to be removed when the paying user no longer exists.

Writing the code

Now that you created group types, you will want your players to join and create groups.

In your client code

  • Add the brainCloud client to your app.
  • Pair the client with the dashboard.
  • Authenticate your user into brainCloud.
  • Request a list of groups for the player to join, and have the player join those groups.
  • Have your player create their own group. 
  • Review other group related calls for your app in the API Reference.
private BrainCloudWrapper _bc;
private string _wrapperName = "default";

void Start() {
    // Unity
    GameObject go = new GameObject();
    _bc = go.AddComponent<BrainCloudWrapper>();
    _bc.WrapperName = _wrapperName; // optionally set a wrapper-name
    _bc.Init(); // extra data, such as: _appId, _secret and _appVersion, is taken from the brainCloud Unity Plugin.
    DontDestroyOnLoad(go); // keep the brainCloud game object through scene changes
 
    _bc.AuthenticateAnonymous((response, cbObject) => { LookForGroups(); });
}
List<string> groupList = new List<string>();
// Look for groups that exist in your app
void LookForGroups()
{
    var contentJson = BrainCloud.JsonFx.Json.JsonWriter.Serialize(new Dictionary<string, object>
    {
        {"pagination", new Dictionary<string, object> {
                {"rowsPerPage", 50},
                {"pageNumber", 1}
            }
        },
        {"searchCriteria", new Dictionary<string, object> {
                {"groupType", "clan"}
            }
        },
        {"sortCriteria", new Dictionary<string, object> {
                {"createdAt", 1},
                {"updatedAt", -1}
            }
        }
    });
    _bc.GroupService.ListGroupsPage(contentJson, (response, cbObject) =>
    {
        var jsonMessage =
            (Dictionary<string, object>) BrainCloud.JsonFx.Json.JsonReader.Deserialize(response);
        var jsonData = (Dictionary<string, object>) jsonMessage["data"];
        var results = (Dictionary<string, object>) jsonData["results"];
        var items = (Dictionary<string, object>[]) results["items"];
        foreach (var group in items)
        {
            var groupId = group["groupId"];
            groupList.Add((string)groupId);
        }
        JoinFoundGroups();
    });
}

// Have the end-user join those groups
void JoinFoundGroups()
{
    foreach (var group in groupList)
    {
        _bc.GroupService.JoinGroup(group);            
    }
    CreateYourGroup();
}
// Have them create their own group
void CreateYourGroup()
{
    var groupName = "Coffee on Monday";
    var groupType = "clan";
    var isOpenGroup = true;    // If using closed groups, implement GetMyGroups to get the request list.
    var groupAcl = new GroupACL(GroupACL.Access.None, GroupACL.Access.ReadWrite);
   
    var jsonData = BrainCloud.JsonFx.Json.JsonWriter.Serialize(new Dictionary<string, object>
    {
        {"description", "Beginner Friendly"}
    });
   
    var jsonOwnerAttributes = BrainCloud.JsonFx.Json.JsonWriter.Serialize(new Dictionary<string, object>
    {
        {"clanType", "PREMIUM"}
    });
   
    var jsonGroupAttributes = BrainCloud.JsonFx.Json.JsonWriter.Serialize(new Dictionary<string, object>
    {
        {"clanPoints", 1500}
    });
   
    _bc.GroupService.CreateGroup(
        groupName,
        groupType,
        isOpenGroup,
        groupAcl,
        jsonData,
        jsonOwnerAttributes,
        jsonGroupAttributes,
        (response, cbObject) => { Debug.Log("Successfully made the group."); });
   
}


Further learning

  • Try creating a closed group, and use GetMyGroups to grab and handle requests.
  • Create Group Entities shared between Group Members.
  • Create a Group Leaderboard, and have a member of the group post a score to it.
  • Try adjusting shared group data with IncrementGroupEntityData and UpdateGroupSummaryData. 

Did this answer your question?