Release 4.1

Note – you can also view the highlights in our new Roadmap!

Release Highlights

Group Leaderboards

Although brainCloud has long supported filtering leaderboards to group members, it has not supported true Group Leaderboards – where each entry in the leaderboard represent’s a Group’s (not a Player’s) score. Until now that is.

Now, when creating a leaderboard, you will first choose whether it is a Player or a Group Leaderboard. 

Important notes regarding Group Leaderboards:

  • Any member of a group can post a score on behalf of their team
  • Post group scores via the new PostScoreToGroupLeaderboard() method. Additional new calls are described in the API section (below).
  • Group Leaderboards cannot be used as the basis for Tournaments or Divisions

Note – we are considering adding Group Tournament and Division support in the future. If it is important to you, vote for it in our Roadmap!

Group Enhancements

We have made a bunch of enhancements to Groups and the Group APIs to go along with the new leaderboard support:

  • Group Summary Data – we have added the concept of summary data to groups. This is an additional bit of custom JSON, associated with your groups, that can be read by non-members. This is useful when searching for groups with specific qualities and also when viewing group leaderboards ← the summary data gets returned in the leaderboard calls
  • Enhanced Searching – when searching for groups, you can now include additional fields (isOpenGroup, updateAt, createdAt, and summaryData) in the filter and sorting clauses.
  • Get Random Groups – we have added a new API call for retrieving a random selection of groups that fit the specified criteria. See GetRandomGroupsMatching().

Voting Leaderboards

Since we were already in the Leaderboard code, we thought we would cover another customer request.

Voting Leaderboards are special leaderboards where the user doesn’t post their own score – rather, a player increments the score of another player. This makes the most sense for a CUMULATIVE leaderboard (where posts from players increment a total). You can imagine using this system to allow players to vote on custom content created by other players – like custom maps layouts, etc.

Important notes:

  • This technically isn’t a new type of leaderboard – it’s merely a new leaderboard call – PostScoreToLeaderboardOnBehalfOf(). Note that this call be made from Cloud Code only.
  • The API does not prevent users from voting (i.e. posting on behalf of another user) multiple times. We leave that enforcement up to the app (if desired, of course).

Multi-Region Support

In V4 we introduced the ability to host Relay and Room Servers. When configuring your servers, you had the ability to choose which region to host them in.

This was a good start, but for global coverage developers would need to create individual server configurations for each of the regions they want to support. And if they’re using our matchmaking and lobby services, they would need to set up separate lobby configurations for each region as well.

Release 4.1 greatly improves things:

  • You can now select multiple regions for a Room or Relay Server configuration in My Servers
  • There are new Client APIs that allow you to retrieve the list of regions associated with lobby type(s), and calculate the latency (i.e. ping times) to them
  • When launching a Room or Relay Server from a lobby, the Lobby Service will now automatically choose the best region for the members of that lobby

Dynamic Chat Channels

And last but not least, this release introduces a new type of chat channel.

Dynamic chat channels are special channels that any user can create and/or join. They exist only for as long as there is activity. Once the channel inactivity timeout expires (typically 30 days), the history (and the channel itself) are automatically deleted and cleaned up.

Note that developers need to manage the “membership” to the channels themselves. If a user of an app connects to a dynamic channel during a session, and you want them to reconnect the next time the app launches as well – you’ll need to save that information somewhere in your app (likely in a user entity).

Portal Changes

We have made the following portal changes:


  • Core App Info | Application IDs
    • Renamed “Facebook Secret” to “Facebook App Secret” to better clarify what it is
  • Core App Info | Admin Tools
    • Added new options to the Deployment section to prevent overwriting the Lobbies and MyServers page settings. This is important because you very likely want to configure different performance + availability settings for dev vs. prod environments
  • Cloud Code | My Servers
    • Enhanced the Room Server and Relay Server configuration screens to support multiple regions
    • Note that each region can use the default configuration settings (server size, # containers, etc); or you can override those settings on a region-by-region basis
  • Leaderboards | Leaderboard Configs
    • When creating a new Leaderboard config, you can now choose between Player and Group entry types (default is Player).
    • Once the entry type has been set, it cannot be changed
    • Tournaments and Division Templates cannot be enabled for Group leaderboards
    • The entry type has been added to the Leaderboard Config list screen as well


  • Global Monitoring | Leaderboards
    • Have been enhanced to show the results of Group Leaderboards
    • The column displayed now automatically change depending upon the leaderboard type being displayed
    • Clicking on a group id will bring you to the group.


  • DOCS menu
    • Added a link to the new Roadmap site

API Changes

The following changes/additions have affected the brainCloud API:

  • Chat Service
  • Group Service
    • [New!] CreateGroupWithSummaryData() allows the creation of a group with summary data.
    • [New!] GetRandomGroupsMatching() returns a list of random groups that match the supplied criteria
    • [New!] SysChangeGroupType() changes the group type of a group. Useful for leveling up the maximum number of players in a group. Cloud code only.
    • [New!] UpdateGroupSummaryData() allows a member to update the summary data of the app. Note that the user must be the owner of the group; or the group’s data ACL must be set to “member”: 2 to perform the update.
    • [Update] ReadGroup(), GetMyGroups(), ListGroupsPage(), and ListGroupsPageByOffset() will now return the summaryData associated with groups
    • [Update] Additional fields (updatedAtcreatedAt, isOpenGroup, and summaryData) can now be used as filter and sort criteria in group calls.
  • Leaderboard Service
  • Lobby Service
    • [New!] GetRegionsForLobbies() retrieves a list of super-set of regions for the specified list of lobbies. Is used by the client app to determine with regions to ping test.
    • [New!] PingRegions() tells the client to ping the retrieved set of regions. Should be called after GetRegionsForLobbies() has completed.
    • [New!] CreateLobbyWithPingData(), FindLobbyWithPingData(), FindOrCreateLobbyWithPingData() and JoinLobbyWithPingData() are enhanced versions of the regular calls, with the obvious addition of ping data that the server will use to select the best region when launching a Room or Relay Server. Note that the library will automatically provide the ping data for those calls (there are no additional parameters)
    • [New!] SysSendSignal() allows cloud code scripts to send signals to members of a lobby.
    • [New!] SysDisbandLobby() allows cloud code scripts to disband a lobby.
  • Tournament Service

Note that we have also made a small change to GetGlobalLeaderboardViewByVersion() and GetGlobalLeaderboardPageByVersion() to allow you to once again pass in -1 as the version id. That behaviour had regressed in 4.0. Apologies for the inconvenience!

Miscellaneous Changes / Fixes

  • Updated libraries
    • All libraries have been updated for the 4.1 release! Go get ’em!
    • The Unreal Library now includes beta-level support for our Relay Communications protocol!
    • Warning – there is a known issue with Unity 2019 on IOS devices that affects brainCloud (and really any app making web requests). More info here!
  • Documentation updates
  • Important Fixes
    • BCLD-4714 Mismatch of Service and Operation on API Explorer after quick authenticate
    • BCLD-4833 Importing an invalid script zip file and choosing “Full Sync” deletes all existing scripts
    • BCLD-4832 Facebook transactions – some transactions are being displayed as “null”
    • BCLD-4812 Need ability to preserve My Servers and Lobby configurations on Deploy and Import
    • BCLD-3193 SendEvent operations gives a positive response without entering profileID
    • BCLD-4751 Descriptive text on “Edit Lobby Type” popup is out-of-date
    • BCLD-4737 Can’t delete a group after using “Delete Users”
  • Plus miscellaneous fixes and performance enhancements…

Warning: Unity 2019.X (iOS) issues


Update – this issue was addressed in Unity 2019.3. All good now!

Hi folks,

We are currently tracking some oddities in the reliability of the brainCloud libraries running in Unity 2019.X on iOS devices.


  1. We have confirmed that this issue is limited to iOS only (edit: also probably tvOS). It does not occur on Android, Mac, Windows or WebGL.
  2. A Unity Rep has confirmed the defect, and that they are working on a fix. See this Unity Forum thread.
  3. The defect now appears in Unity’s Issue Tracker – click and add your +1 –
  4. Further updates in this brainCloud Forum Post.

Executive Summary: We highly advise developers to stick with Unity 2018.X until further notice.


The symptom is that requests are being sent to brainCloud, and occasionally rejected with what brainCloud calls a signature error.

Signature errors are flagged if the content of the message that brainCloud receives doesn’t match the MD5 that has been calculated for the message. They generally mean that either the client had the wrong secret (likely a hacking attempt) or the message content has been tampered with (also likely a man-in-the-middle hacking attempt).

In this case, neither of these has occurred – rather, the message content has been corrupted somehow by Unity’s libraries (we suspect a combination of the UnityWebRequest and/or UploadHandler classes).

This doesn’t happen all-the-time… (in fact, it very rarely occurs if requests are less than 2K). But we’re seeing it happening quite often with requests that are 7K or greater in size.

After enough of these errors occur, the UnityWebRequest class is locking up – causing the brainCloud client library to stop functioning properly – requiring the app to be terminated.

Note – the good news is that brainCloud’s servers catch this issue and prevent the bad message from corrupting your data. The bad news is that a client experiencing this issue might have to retry several times to send a request – impairing client performance.

Reproducing the error

We have only been able to reproduce this error in Unity 2019.1.X (as well as 2019.2.0b5 (alpha) and 2019.3.0a5 (beta)) and only when running on iOS devices.

We do have reason to suspect that Android devices may also be impacted (but we haven’t had time to test + prove that yet). Update: We have since tested on Android and cannot reproduce the problem. So this appears to be an iOS-only issue.

Certainly, the same code running from the editor on Mac and Windows workstations seems to run just fine.

And certainly, the same brainCloud libraries (with test code) running under Unity 2018.X runs fine as well. Also, our C++/Objective-C libraries are still running fine under iOS – this issue is limited to Unity.

We have noted, as per their 2019 release notes, that Unity seems to be making significant changes to their iOS communications.

  • 2019.1 Release notes
    • iOS: UnityWebRequest will use new backend based on NSURLSession. Old NSUrlConnection backed is still available (commented out in trampoline)
  • 2019.1.4 Release notes:
    • iOS: Fixed larger than 2k payloads not sent by UnityWebRequest when HTTP/2 (1146305, 1152777)


For now, we recommend that developers limit their production iOS builds to Unity 2018.X or earlier.

We are constructing a limited function test app that we will submit to Unity when we report this defect. We will keep the community posted as to how that progresses.

Update – you can see the brainCloud forum post, with repro code and details, here.

In the meantime, we thought it best that our community have a heads up regarding this potential problem.

We apologize for the inconvenience and hope that through working with Unity, we can get a solution to you ASAP!