brainCloud BaaS will be upgraded to MongoDB 8.0 on Monday, July 7th, starting at 8 p.m. Eastern. This rolling upgrade may take up to 6 hours to complete. All API and Portal services will be fully available during the upgrade; the portal will NOT be disabled.

[Full disclosure: It will take longer than usual because we are first upgrading to MongoDB 7.0, and then immediately upgrading to MongoDB 8.0.]

Note that all brainCloud Private Instances will be upgraded in the weeks before the end of July 2025.

Compatibility

brainCloud 5.7 has been tested to be fully compatible with MongoDB 8.0.

Important Change (READ THIS!)

MongoDB 8.0 contains an Important Change that brainCloud developers must be aware of.

Starting in MongoDB 8.0, comparisons to null in equality match expressions don't match undefined values.

Consider the following table:

In MongoDB 6, a query for { "name": null } would return all 4 records, as per these conditions:

• The name field is null (_id: 1)
• The name field is undefined or contains an undefined array element (_id: 2 and _id: 3)
• The name field does not exist (_id: 4)

But in MongoDB 8, the query for { "name": null } only returns 2 of the records:

• The name field is null or contains a null array element (_id: 1)
• The name field does not exist (_id: 4)

Note that this change in query behaviour also affects $eq, $in, and $lookup operations.

For full details on MongoDB compatibility changes:

• MongoDB 7 - https://www.mongodb.com/docs/manual/release-notes/7.0-compatibility/
• MongoDB 8 - https://www.mongodb.com/docs/manual/release-notes/8.0-compatibility/

brainCloud Customer Impact

This change only affects brainCloud's list and paging-style calls (which accept custom query JSON) - and ONLY apply if the JSON data itself somehow had undefined values -- which would be pretty unusual.

The affected calls include:

• Custom Entity - GetEntityPage(), SysGetEntityPage()
• Entity - GetList(), GetListCount(), GetPage()
• Global Entity - GetList(), GetListCount(), GetPage(), GetSystemEntityList() GetSystemEntityListCount(), GetSystemEntityPage()
• Group - ListGroupsPage(), GetRandomGroupsMatching(), ReadGroupEntitiesPage(), SysGetRandomGroupsMatching(), SysListGroupsPage(), SysReadGroupEntitiesPage()
• Item Catalog - GetCatalogItemsPage(), SysGetCatalogItemsPage()
• Leaderboard - SysGetLeaderboardConfigsPage()
• Messaging - GetMessagesPage(), SysGetMessagesPage()
• RedemptionCode - SysGetCodeTypePage()
• User - SysGetPage()
• User Items - GetUserItemsPage()

So - this is ONLY an issue if:

• Your app has "undefined" values in its JSON entities
• AND it is querying on those fields with "undefined" values
• AND it is specifically querying those fields for "null" and expects "undefined" values to be included with the query results.

Take action!

If you do feel that this issue may affect your app, reach out to us in support with the following information:

• appId
• category of entity affected (eg, User, Global, Custom, etc).
• entityType field
• field name <- name of the field with undefined values

We may be able to help you prepare the data so that "undefined" fields are replaced with "null" values to ensure that queries continue to work.

This release adds an improved Team Dashboard, Self-Service Delete & Branding, Node Resource Monitoring, Online Matchmaking Improvements, and more. It also readies the platform for MongoDB 8.

Compatibility Notes

All brainCloud releases emphasize preserving stability and backward compatibility for existing apps. That said, developers should be aware of the following changes:

• Lobbies

  • Join In Progress change

    • The system no longer allows additional members to be added to a lobby while it is in the STARTING state. 
    • If Join In Progress is enabled, new members can join once the lobby moves to the ACTIVE state.
    • This change addresses a race condition whereby it was possible for the lobby members to have "readied up" but for a new lobby member to be joined to the lobby in a non-ready state before the associated room instance was completely launched.

Release Highlights

Improved Team Dashboard

We have reworked the Team Dashboard to make it more useful (and prettier!), especially for teams with multiple apps.

Improvements include:

• New Live Apps widget - displays Daily Active Users, New Users, Revenue, and Purchase Count charts for the last 14 days
• New Recently Active Members widget - so you know who has been online in the system recently

Plus improvements to the look-and-feel of the existing widgets. 

Self-Service Branding

As a backend service, brainCloud provides very little UI for end-users. That said, we do provide a few web screens to:

• Verify email addresses
• Enable password resets
• Unsubscribe from tournament emails

The existing screens were functional but plain. brainCloud’s development community has been wishing for the ability to customize the look-and-feel of those screens.

And in 5.7 you get your wish! We have re-designed the screens and tied them to a new Self-Service Branding feature that controls their look and feel.  Using the new system, developers have a lot more control over the screens, including:

• Separate studio and app branding
• Control of header, background, font, and button colors
• Multiple header layout options
• Add custom buttons to screens
• Optional footer section - with links to privacy page, support, etc.
• And more…

The new App > Design > Self-Service > Branding page customizes this look and feel and features a Live Preview so developers can see how their choices will look in Mobile or Desktop browsers.

Self-Service Account Deletion

We built the branding feature (above) so that we could build this feature properly! 😀  

Some app stores (Google) now require that devs provide an URL for web-based account deletion. We have created this new feature to give developers a head start on that requirement. It’s a complete solution for apps using email identity and/or contact emails. Devs using other forms of authentication can use the new APIs and Portal functionality to satisfy the Google requirement.

Scenario 1 - For email-based accounts (fully automated)

The Self-Service Account Deletion feature provides an URL for end-users to delete their accounts.

To delete their accounts, end-users will:

• Navigate to the provided self-service deletion URL
• Provide the email address associated with their account
• The system will then send an email(s) to that address, with a link to click to delete their account. Note that multiple emails will be sent if there is more than one account associated with an email (which can happen with contact emails).
• The user receives the deletion email and clicks the link. Note that the link for account deletion is valid for a limited period of time ← set to 2 hours currently.
• The user follows the prompts to complete the deletion of their account.

Developers can enable and configure this feature from the new App > Design > Self-Service > Delete Account page.

A few important notes:

• The template used to create the email sent to the user is customized with the other Sendgrid email templates, on the App > Design > Authentication > Email Authentication page.  Instructions for creating a template can be found here.
• CSRs can also manually trigger the sending of the deletion email to users directly from the Portal. Choose “Send Deletion Email…” from the Action menu of the user's User Summary page.

Scenario 2 - API-based Automation (For non-Email Identity Types)

Devs can use this feature and associated APIs to build a custom site for deleting accounts. 

The use case would look something like:

• The custom site would prompt the user for their login info, and then, using brainCloud APIs, log in and retrieve the profileId of the associated account.
• The site would then call the new User.SysCreateSelfServiceDeletionUrlForUser() method to create a deletion URL.
• The site would then redirect the end-user to that URL so the user could complete the deletion steps.

Scenario 3 - Manual Via CSR (Customer Support Representative)

CSRs can support the deletion requirements via the new Design Portal features.

The use case looks something like this:

• A form or customer service application prompts the user for the information to identify their account.
• A CSR looks up the user’s account and navigates to the User Summary page of that user.
• The CSR then clicks the Copy Deletion URL… button on the action menu to create and copy the deletion URL for that user.
• The CSR then sends the end-user a response, with the URL to click on for the user to delete their account.

Node Resource Monitoring

The Server Monitor now allows developers to monitor the resource utilization of individual nodes. Including these metrics marks the Server Monitor’s graduation from [Beta] to official release!

Clicking on a node and selecting the Usage tab displays the following charts:

• Containers - the number of containers running on the node
• CPU - the % cpu utilization of the node (across all containers)
• Memory - the % memory utilization of the node (across all containers)
• Storage - the % storage used by the node

The CPU, Memory, and Storage metrics are retrieved from our New Relic monitoring system. There can be an initial lag of up to 5 minutes for newly launched servers in retrieving these metrics. The Container Count metric is received directly from our Room Server Framework via RTT. Still, there is no history, so the data is retrieved and available only while the Server Monitor screen is displayed.

Additional Improvements

brainCloud 5.7 includes a ton of other improvements as well. These include:

• App Alerts

  • We have added a new alert to warn users when their Tournament auto-claim settings are out of sync with the required compatibility flag.

• Builder API

  • The Builder API has been enhanced to support new Dynamic API Keys, which are dynamically created and are good for only 16 hours
  • Dynamic API keys can be created as part of the new SSO functionality that we have built into the platform.  

• Edgegap Hosting

  • The control of the skip_telemetry option is now configurable by devs. Previously, it was hard-coded  true for faster server launches (but at the expense of perfect placement of servers).

• GameLift Hosting

  • There is a new AWS EventBridge option for more scalable reporting of hosted server status. Configuring this is optional, but highly recommended for production deployments.

• Item Catalog Images (via API)

  • New API methods have been added to allow Item Catalog images to be set via Global or User Files. See the API section for more details.

• Online Matchmaking

  • Has improved support for adding groups of players to a lobby
  • Previously, all players would be placed on the same team if a team was specified in the matchmaking call, but if not, the provided players would be dispersed between the available teams.
  • The extension allows developers to ensure players are placed together on a team without having to specify which team.
  • See the API section for more details.

Portal Changes

This release adds some significant quality-of-life improvements to the Portal.

Live Lock

We have made the live lock more convenient. Devs can now drag the app’s name instead of re-typing it into the confirmation field.

Redemption Codes

We have added additional functionality and polish to the design and monitoring Redemption Code screens:

• App > Design > Marketplace > Redemption Codes

  • Now includes a new Search option
  • The list now shows the number of redemptions redeemed - instead of the number available for redemption…. (which is a bit more consistent when showing expired codes)

• App > Global > Marketplace > Redemption Codes

  • If there has been no activity in the past 30 days, the Campaign Activity widget now displays a new [Show the most recent activity] button, which automatically adjusts the chart's date settings when clicked. 

Personalized Pricing

The User > Marketplace > Personalized Pricing screen has been completely reworked to help developers understand which prices a user sees and why. 

This greatly aids in understanding and debugging automated promotions.

Additional Improvements

The following additional portal improvements have been made:

• Login, Registration, and Recovery

  • The screens for user login, new user registration, and account recovery have been improved

• Team > Manage > Apps

  • The [+ New App] dialog has been redesigned to make selecting supported platforms easier.

  • Platforms are now separated into the following categories:

    • Mobile & Web
    • Desktop & Console
    • Legacy

• Team > Manage > Members

  • The Builder API key permission has changed somewhat. It now indicates whether the team member has permission to create and use Static API Keys. The label has been adjusted to reflect this change.

• Team > Setup > Team Info

  • The Builder API access permissions have been slightly refactored. There are now separate permissions for general access to the Builder API and for allowing the use of static keys.

• App > Design > Admin Tools > Deployment

  • This includes a new option for preserving self-service branding during deployment. Useful if the branding for development and production versions of apps is different (for testing purposes)

• App > Design > Notifications > Settings

  • Now supports deleting Apple Push Notification certificates

• App > Global > Leaderboards > Leaderboards

  • The leaderboard entry preview blade shows the user’s profile image, if available.

• App > Design > Self-Service

  • New section for setting Self-Service feature options. See feature description in the Release Highlights section.

• User > User Browser, Search

  • Searching by email now searches for emails in the Contact Email field and Profile Identities, in addition to the Email Identity

• User > Summary > User Summary

  • Screen action buttons have been reorganized under a new Action menu

  • Includes new actions for the new Self-Service Account Deletion feature:

    • Send Deletion Email…
    • Copy Deletion URL…

• User > Gamification > Milestones

  • Refactored and separated from the old Milestones & Quests screen
  • Supports new filtering and searching options

• User > Gamification > Quests

  • Refactored and separated from the old Milestones & Quests screen
  • Supports new filtering and searching options

API Changes

The following calls have been added to the brainCloud API:

• ItemCatalog

  • Added two new methods (cloud code & S2S-only) for copying image files to the item catalog programmatically:

    • SysCopyItemImageFromGlobalFile() - copies (or moves) a file from Global Files to be used as the image for an Item Catalog entry.
    • SysCopyItemImageFromUserFile() - copies (or moves) a file from User Files to be used as the image for an Item Catalog entry.

• Lobby

  • The lobby matchmaking APIs have been extended to support additional options for team selection when dealing with groups of players (as specified using the otherUserCxIds parameter).

  • This new behaviour is controlled by new special “team names” that can be passed into the teamCode parameters of the API calls:

    • “team1” - all players will be assigned to the specified team (existing functionality)
    • ““ or null - players will be individually (and randomly) assigned to teams that have [x] Auto assign players enabled. Players are NOT guaranteed to be kept together on the same team. (existing functionality)
    • “___” (three underscores) - assign all provided players as a group to any team at random.  Note that only teams with [x] Auto assign players enabled are considered. Players are kept together. (New functionality!)
    • “___:team1,team2,…” - attempt to join `team1`, attempt to join `team2`, etc. until the list is exhausted. Players are kept together. (New functionality!)
  • The FindLobby(), FindLobbyWithPingData(), FindOrCreateLobby(), FindOrCreateLobbyWithPingData(), JoinLobby(), JoinLobbyWithPingData(), SysAddMember(), and SysAddMemberWithPingData() have all been extended to accept these new team codes

• User

  • Added a new S2S call for creating the self-service deletion URL for a user:

    • SysCreateSelfServiceDeletionUrlForUser() 

Client Libraries

All Libraries

• Increased the amount of time the client library waits for a CONNECT message from the Relay Server before resending its connection request. Timeout is now 2 seconds (up from 0.5 seconds).

Unity, C#, and Godot

• Fixed bug that caused empty notification tokens to be saved if an end-user denied push notifications

Unreal

• Fixed issue where the WebSocket object is not cleaned up properly on destroy
• Fixed issue with the OnRecv function passing in a reference to the json message, it is now passing a copy of that json message instead of a reference to account for a crash issue happening where the reference points to a null value on rare occasions.
• Fixed bug that caused empty notification tokens to be saved if an end-user denied push notifications (STILL IN PROGRESS)

C++

• Fixed bug that caused empty notification tokens to be saved if an end-user denied push notifications

Java

• Fixed bug that caused empty notification tokens to be saved if an end-user denied push notifications 

JavaScript

• Fixed bug that caused empty notification tokens to be saved if an end-user denied push notifications

Objective-C

• Fixed bug that caused empty notification tokens to be saved if an end-user denied push notifications

Examples

• Invaders Demo greatly improved with Replay Functionality

Documentation and Tutorials

Documentation

• All the latest API additions and changes have been incorporated into our new doc site at docs.braincloudservers.com !

Tutorials

• A new Knowledge Base article discusses how to add a Replay System to your game using brainCloud Playback Streams. Find it here. 
• New Knowledge Base article on creating a custom Room Server Manager (RSM). Find it here.

Marvellous Multiplayer! Release 5.6 brings additional polish and performance to the brainCloud platform, with an emphasis on improved multiplayer services and developer quality-of-life!

Compatibility Notes

There are no API changes in this release. 

There is, however, a change to how often brainCloud retrieves docker images for Hosted Room Servers. brainCloud used to retrieve a fresh image with every container launch - but this is both slow and expensive. Starting in 5.6, if the named image already exists on the node, brainCloud will re-use that image - avoiding the unnecessary "pull" from Docker. For devs who don't set unique tags for each production build, this behavior can be modified so that brainCloud will retrieve a fresh image if the cached image on the node is older than hours. See the Hosted Server Optimizations section for more information.

Release Highlights 

Matchmaking Monitor - Official Release

brainCloud 5.6 marks the official release of our Matchmaking Monitor.

The Matchmaking Monitor is a unique feature of brainCloud that gives developer and designer-friendly insights into an app’s matchmaking performance - and how it impacts the player experience.

This release re-arranges our panels to be more intuitive and mobile-friendly - and adds two new performance metrics: Matches Per Minute and Lobbies Created Per Minute. 

We have also added an Average Steps metric to give developers additional insight when optimizing their matchmaking criteria.

Developers can now click on the Lobby Type panel to trigger a Preview Blade showing its configuration.

The Matchmaking Monitor can be found in the Design Portal under App > Global > Multiplayer > Matchmaking Monitor.

Hosted Server Optimizations

brainCloud has built-in support for hosting Room [i.e., Game] and Relay Servers.

This release brings significant optimizations to hosted server orchestration, including:

• Faster container launches: We have refactored our region and node-locking approaches to speed up the parallel launching of nodes and containers.
• Faster container cleanups: The system will now clean up completed containers faster, making server slots available for new matches sooner. As a bonus, this saves money!
• Optimized image pulls: brainCloud now only retrieves the image for your container once when a new node starts. All subsequent container launches on that node take advantage of the previously retrieved image. This strategy is best for devs who use unique tags [e.g., “1.0.0-1”] for every server build. For devs re-using tags across builds [e.g., “latest”], there is an option to pull a fresh image if the previous image is older than the specified number of hours. This speeds up container launches - and reduces Docker usage - saving money!
• Optimized log retrievals: brainCloud now uses a separate thread to retrieve the logs when cleaning up containers. Also note that by default, brainCloud now only retrieves the logs for containers that complete with a non-zero exit code.

Leaderboard Optimizations

Our Leaderboard system is one of brainCloud’s most popular features. As such, it gets used a lot - by many games in different ways.

A common use case is using our Leaderboards as the basis of Tournaments — both for our built-in Tournament system and for more customized systems that devs have built using Cloud Code. 

Although the system overall performs well, one part of it performs “less well” than the rest: counting all the entries in a leaderboard. Due to MongoDB's limitations, this operation is slower than we’d like. And under some circumstances (e.g., at the end of a tournament, when everyone wants their tournament results), those slowdowns can add up! 

brainCloud 5.6 introduces several improvements to target this very use case:

Leaderboard counts are now being pre-calculated and stored for two high-usage scenarios:

1. Tournament results: When a tournament is completed, and rewards are calculated, we now count and store the total number of players once and use it for batched and real-time processing of tournament rewards.
2. Rotated leaderboards: When a leaderboard rotates, we now count the entries and store them in the leaderboard version history - automatically using that value when the app calls GetGlobalLeaderboardEntryCountByVersion(). 

Both of these improvements are entirely in the background — no changes to Client APIs.

NEVER ROTATION leaderboard cache

The previous two scenarios calculate and store the count for leaderboards that have been completed. Since these leaderboards are no longer live, the number of entries is no longer growing.

The same cannot be said for NEVER rotation leaderboards. These leaderboards are active forever - and can grow to millions of players.  As they do, dynamically counting the entries can take some time.

To improve performance for these leaderboards - we have added a new system that periodically (every 2-5 minutes) counts the number of records and caches the result. This cached count is also dynamically incremented/decremented as new scores are added and deleted. As such - this cached count closely tracks the exact number of entries – though it isn’t guaranteed to be 100% accurate.

When a leaderboard is very large - the difference between 1,500,000 or 1,500,001 isn’t significant…  though apps with this caching enabled should take care to ensure that they can handle the situation where the system says the player’s rank is 1,500,001 – but also says there are only 1,500,000 entries in the leaderboard. [Hint - in that case - artificially inflate the number of entries to 1,500,001 for display purposes.]

Important notes:

• Most apps do not need the NEVER ROTATION cache. Thus, it is turned OFF by default for all apps.
• Our support team must enable the NEVER ROTATION cache on a case-by-case basis.
• After 5.6 is released, our support team will contact teams with apps where we think this should be enabled.
• Contact support if you have questions about whether we should enable it for your app! 

Additional Improvements

brainCloud 5.6 includes a number of smaller improvements as well. These include:

• App Alerts

  • Dangerous Compatibility Flag — We have added a special alert for the "Include shared objects in Owned Custom Entity GetEntityPage queries" compatibility flag, which can significantly slow app performance for apps using Custom Entities. We highly advise that this flag be disabled for all apps. More info here. 
  • Unreachable Web Service — We have added a new alert for when Web Services are not reachable from brainCloud’s servers. This alert may indicate that the target servers are down, the endpoint has changed, or their SSL Cert has expired.

• Database

  • brainCloud now has basic/experimental support for AWS DocumentDB. This is most interesting for our Private Licensees (as an alternative to Atlas) - though we are also considering moving some Public BaaS services to it (e.g., some logs). 

• Logs

  • We have added new Security Log views at the App, User, and Super system levels. These logs mainly capture bad login attempts - at the Client and S2S API levels.

• Relay Server

  • We have added new MD5 and hex dump capabilities to the logging. The two new settings are:

    • PACKET_LOG_ENABLED_WITH_MD5: Set to “true” to enable MD5 hash logging of incoming and outgoing relay packet payloads.
    • PAYLOAD_LOG_AS_HEX: Set to “true” to log the incoming packet payload as a hex dump rather than an ASCII string.
  • The relay server also now exits with a code of 11 if MEMBER_TIMEOUT expires before any players connect. 

Portal Changes

We continue to evolve our Portal. In addition to the Matchmaking Monitor enhancements described above, we have added the following improvements:

Billing Plan Dialog

For users on our Public BaaS, the Billing Plan dialog has been updated to facilitate easier plan comparison and selection. This dialog is accessed from the Team > Manage > Apps page. 

Global Properties

The Global Properties screen (App > Design > Cloud Data > Global Properties), which is used for managing remote config settings for apps, now allows values to be edited inline for convenience. 

Note that JSON-based properties will pop-up a small dialog window for easier editing.

Reference Currency

brainCloud is used by developers across the globe - and thus doesn’t make any assumptions about the base currency that your app uses. The reference price of a Product is simply a number that we sum up when presenting revenues.

Prior releases of brainCloud have displayed a $ next to revenue numbers - which obviously isn’t correct for apps that aren’t using a dollar-based currency.

brainCloud now allows developers to specify the reference currency for apps - so that we can display revenue numbers appropriately.

Navigate to App > Design > Portal > Reference Currency Settings to configure your currency!

Sample Data Mode

Most of our analytics screens now feature Sample Data modes - which are designed to give new devs a feeling for what the screen would display if the related data were available.

Note that when in “Sample Data” mode - the screen contains a prominent brown border with the words “(Sample Data)” after the screen title.

Additional Improvements

In addition, the following additional quality-of-life improvements have been made:

• App > Design > Cloud Code > Web Services 

  • now displays an icon indicating whether the services displayed are reachable by brainCloud

• App > Design > Gamification > XP Levels

  • Changed the default chart display format to Linear (instead of Logarithmic)

• App > Design > Leaderboards > Tournament Templates

  • Greatly improved display and editing of Tournament Prizes!

• App > Design > Multiplayer > Lobbies

  • Re-designed Lobby Preview blade. Now, it shows a summary of the rules.
  • You can also quickly navigate to the associated Server for a Lobby Type from its Preview Blade.

• App > Design > Servers > My Servers

  • Room Servers - Devs can now configure if and how often to refresh Docker images when launching containers. 

• App > Global > Global Data > Custom Entities

  • Added [Apply] button to the editor to allow for easy checkpoint-saving for long editing sessions

• App > Global > Global Data > Global Entities

  • Added [Apply] button to the editor to allow for easy checkpoint-saving for long editing sessions

• App > Global > Leaderboards > Leaderboards

  • The leaderboards page has been updated with improved column order — rank is now placed first, and the score is right after the player’s name.
  • A [Refresh] button was added for convenience.
  • Can now only [Reset] current leaderboards - not prior versions.

• App > Global > Multiplayer > Server Monitor

  • New details were added to the Server Preview Blade. Now shows custom environment settings and Max Nodes.

• User > User Browser

  • A new button on the User Preview Blade will allow you to view the selected user in a new tab.

• User > Social > Friends

  • The screen now displays the platform that a friend originates from

Plus, there have been significant improvements to the usability of the Design Portal on mobile devices.

API Changes

brainCloud 5.6 has no changes to APIs.

Libraries and Examples

Client Libraries

Release window - Updated Client and S2S libraries are made available within two weeks of the launch of the updated server software. Updated examples are made available in the two weeks after the client lib updates.

Unity

• The default API endpoint changed to api.braincoudservers.com instead of the legacy sharedprod.braincloudservers.com endpoint.

Unreal

• Compression is now enabled by default.
• The default API endpoint changed to api.braincoudservers.com instead of the legacy sharedprod.braincloudservers.com endpoint.

Java

• Implemented gzip compression to allow for requests and/or responses from the server to be compressed (disabled by default)

  • use compressRequests (boolean compressRequests) to compress requests before they are sent to the server
  • use compressResponses (boolean compressResponses) to tell the server to compress responses
  • use enableCompression (boolean enableCompression) to turn on compressed requests AND responses

JavaScript

• Fixed bug in canReconnect() – Previously, only empty (““ or length == 0) anonymous/profile IDs were being detected

  • Now properly checks for null and empty IDs

• Implemented gzip compression to allow for requests and/or responses from the server to be compressed (disabled by default)

  •  use enableCompressRequests = function(compressedRequestsEnabled) to compress requests before they are sent to the server
  • use compressResponses = function(compressedResponsesEnabled) to tell the server to compress responses
  • use enableCompression = function(boolean enableCompression) to turn on compressed requests AND responses

C++

• Implemented GZip compression to allow for requests and/or responses from the server to be compressed (disabled by default)

  • Currently tested on Windows / Linux / MacOS and Android (Still untested on iOS)

Example/Demo Libraries

Unity Examples

• Invaders

  • Username is now displayed on the main menu upon successful authentication

Documentation and Tutorials

Documentation

• All the latest API additions and changes have been incorporated into our doc site at docs.braincloudservers.com !
• We have started migrating our Knowledge Base at help.braincloudservers.com to French!

We sat down with CEO Mohammad Agha and Lead Developer Tri Truong to gain insights into Magmic’s decision to adopt brainCloud as the primary backend for their games.

About Magmic

Established in 2002, Magmic has developed and published over 100 mobile games, many of which have reached #1 in the Card and Board game categories on the App Stores. Some works include Mattel’s Phase 10, Blokus, and Hasbro’s Scattergories. With 250 million game downloads over 18 years, Magmic has a player base of millions of monthly active users. Across Magmic’s game library, the player base has accumulated billions of hours of play. Currently, Magmic is focused on developing AAA quality Free-to-Play casual games aimed at the mid-core market. Magmic games employ a proprietary event management system, full Live Operations capabilities, and a sophisticated Cross-Promotion SDK.

What were the primary challenges you faced before migrating to brainCloud?

We had a highly fragmented backend infrastructure:

• We had different versions of backends that we had to maintain as we were not necessarily updating older games but we had to keep them active. So we had lots of duplication.
• With all the duplicate backends our AWS bill was pushing $30K+ USD per month and that’s not including salaries of a four person backend team.
• When we were developing Texas Hold’Em King Live for the iPhone, we ran into many sync and latency issues with our legacy tech.
• We had different generations of our legacy backend built on different technologies - which required different developer skillsets to maintain. There was just a lot of inefficiency and lack-of-standardization in our backend code.

What tipped you over to deciding to migrate everything to a new BaaS?

We were spending well north of $400K USD per year on hosting fees, and the system wasn’t 100% reliable.  Add to that the management of servers crashing / going down in the middle of the night and we just always seemed to have an issue to deal with.

During the assessment process, were there any features of brainCloud that stood out as especially valuable for your business?

One of the standout features of brainCloud for our business is the Cloud Code functionality: It gives us the flexibility to develop our products in a way that fully meets our specific requirements. With Cloud Code, we can implement custom logic on the server side, streamline workflows, and optimize performance without needing to manage our own backend infrastructure. This has been invaluable for ensuring scalability, maintaining security, and integrating seamlessly with other cloud services and blockchain solutions. Overall, it allows us to stay agile and focus on delivering the best experience to our users.

What was the key feature or aspect of brainCloud that won the bid?

The real-time multiplayer aspects were what we were looking for initially but then we found a host of other features in there that we also found extremely useful, including Leaderboards, Data Downloads, In-App Purchase configuration and management, and User Login and management.

Is there a ballpark estimate that you would feel comfortable saying is a standard “time savings” that you get from having a standardized backend?

Yes, we no longer need to rebuild backend foundation features like authentication, leaderboards, multiplayer, and cloud storage from scratch, which saves us a significant amount of time—easily 2 to 3 months per project. Instead of allocating resources to backend infrastructure, we can focus more on developing innovative features. For example, in MLB Diamond Inc., our developers were able to shift their focus to building new online functions such as PvP gameplay, Marketplace, and Auction systems.

Can you summarize some of the qualitative outcomes of migrating to brainCloud?

We have seen the following benefits:

• Lower Costs: We estimate we are saving approximately $400K USD/year for AWS bill + $300K USD/year in dev salary for a total of $700K USD/year savings across all our titles.
• Higher Revenues: We started doing a lot more sales and player in-app time went up because our system was more reliable, we estimate 15% increase in IAP revenues.
• Server Reliability → DAU Increase: What we see is DAU [Daily Active Users] increasing more smoothly over time since we are experiencing no downtime. Previously it was common to have servers crash at 2AM – and every time the server goes down, the game loses users due to that. That does not happen anymore.
• Development Time: We estimate over 60%+ decrease in time spent on server development, and no more headaches due to server issues or downtime.

What was your top reservation or concern before the migration, and how did brainCloud meet that concern?

Our top concern was, “Will brainCloud do what we need it to do reliably, cheaply, and consistently? The answer was “yes” on all counts. Moving to brainCloud was clearly the right decision.”

Ready to try brainCloud for yourself?  Create a free account on our Public BaaS - or jump on a call with our Sales Team for more info!

brainCloud 5.5 has something for everyone: Retention Analytics, support for Dart and Flutter, Optimized Group Leaderboards, App Alerts, an Improved Matchmaking Monitor, Improved Security, and more!

Compatibility Notes

We work hard to preserve stability and backward compatibility for existing apps.

Developers should be aware of the following changes:

• Cancelling Find Requests: the LobbyService’s CancelFindRequest() method now requires an entryId be passed into it. This change was technically introduced in 5.4.X, but we note it here for completeness.
• Relay Servers: Significant improvements have been made to how the Relay Servers handle large matches (i.e., matches with more than 30 players). These improvements involve reusing abandoned slot IDs, a behavior change that may impact certain games. Therefore, we made the new software available as the “V3” Relay Server protocol. The protocol APIs themselves have not changed. Most games that work with V2 should work unchanged with V3.
• Group Leaderboards: 5.5 now stores Group Leaderboards in collections separate from regular Player Leaderboards. The older combined storage is still supported and is the default for existing apps. The new compatibility flag controls this behavior: “[x] Store user and group leaderboard scores in the same collection (slower).” This flag is enabled by default for existing apps and disabled for new apps. Changing this value for an existing app will make old group scores (written to the combined collection) inaccessible.

Release Highlights

Retention Analytics

Retention is a metric that indicates how effectively your app engages new users and entices them to return. It is measured over time and represents the percentage of users who return after 1 day, 7 days, etc.  

There are two common variations of retention - Classic Retention and Rolling Retention.

Classic Retention measures the percentage of users who return on a specific day (i.e., D+7 = day 7 - which is 7 days after their account was created). 

Rolling Retention measures the percentage of users who return on that day or any day thereafter.  (i.e., a user who returns on day 7 is also deemed “retained” on all previous days).  

Rolling Retention numbers will always be higher - and will reliably decrease over time – while Classic Retention stats will bump up and down (especially during the first week) - as some users may return on day 3 that didn’t return on day 2, etc.

Classic Retention helps measure the day-to-day engagement for the first week of your app - while Rolling Retention allows for greater generalizations about your app (i.e., 20% of players are still active after 1 week).

brainCloud’s new Retention Analytics screen displays both Rolling Retention and Classic Retention.

As you can see in the image below, the screen is quite dynamic and offers many ways to view this critical metric. 

Note that apps must be LIVE to generate retention analytics. These stats do not make sense for apps under development - so we do not generate them for Dev and Dev+ apps.

Related: Another metric is Churn - which is the percentage of players who stop using your app within a specific timeframe. brainCloud doesn't display it - but it is easy to calculate. Churn is the inverse of Rolling Retention. If your D+7 Rolling Retention is 20%, then the Churn after 1 week is 80%.

App Alerts

brainCloud 5.5 includes our new App Alerts feature. This feature will perform various checks on the health of your app - and display important information regarding its findings in your App Dashboard.

The initial alerts that can be triggered include:

• Apple Push Notifications - Reminders for devs to update their certs
• API Errors - Alerts if error levels are high or rising
• Logging - Alerts if the app is generating excessive logs
• Compatibility flags - Reminder to evaluate and disable unnecessary compatibility flags
• MFA Enforcement - Reminder to enable the new MFA Enforcement feature for live apps

We will continue to evolve and expand upon this feature in coming releases!

Dart and Flutter Support

Dart is a client-optimized language for developing fast apps on any platform. Developed by Google, Dart is similar to JavaScript but is simpler, faster, and more user-friendly.  When paired with the Flutter UI framework - it is a highly productive foundation for building cross-platform applications.

brainCloud 5.5 includes our new Dart client library, which supports all of brainCloud's features and services - including RTT and Relay Comms.  You can find the source for the library on GitHub - and the package itself on pub.dev, the official package repository for Dart and Flutter apps.

Security Improvements

Security has always been a key concern for the brainCloud Platform - and this release makes two key platform improvements in this area.

Brute Force Protection for User Accounts

A brute force attack is a hacking method that uses trial and error (often in a sequential organized fashion) to crack passwords or login credentials.  

brainCloud’s new Brute Force Attack Protection feature thwarts these attacks by blocking the ability to login to an end-user account after an escalating number of bad attempts – similar to how your smartphone makes you wait between login attempts when you get the password wrong.

The feature is enabled and configured on the new App > Design > Security > User screen.

It works like this:

• brainCloud counts the number of bad login attempts in a row for end-user (e.g., player) accounts. Bad logins increment the count. Good logins reset the count to zero.
• If the # of bad attempts exceeds one of the escalating thresholds, the account becomes “blocked,” during which both good and bad login attempts are rejected… ← this is key - if we allow “good” login attempts while blocked, we won’t stop the attack!
• Note that while the account is blocked - the block time does not extend with each new login attempt - if we did, the lock time would quickly escalate to an unworkable value. So login attempts while blocked are essentially ignored - though we do increment the bad login count appropriately. We do NOT extend the “blocked until” time while the account is blocked.
• Eventually, the “block” will timeout - after which - the next login attempt will be considered. If it’s good - the user will log in - and the bad login count will be cleared to 0.  If the login attempt is bad, the count will increment - and become “blocked” again for a duration appropriate to the new threshold level.
• If Sendgrid integration is enabled - the user can enable emails that will be sent to the user each time the account becomes “blocked” due to this feature.

Important - during the period that logins are “blocked” - both bad and good logins are rejected. Note that anonymous reconnects are by default NOT blocked - so users already logged into a device are not inconvenienced by the attacker’s activity.

Unblocking End-user accounts

The User Summary page has been enhanced to show additional information regarding bad login attempts. See the Portal Updates section for more details.

What about Brute Force Protection for Portal Accounts? 
brainCloud already provides this sort of protection for Portal accounts. And the new Team MFA Enforcement feature (below) makes these accounts even more secure! 

Team MFA Enforcement

This feature adds additional protection to a developer’s Team Member (i.e., Portal) Accounts. 

brainCloud has long supported MFA authentication for Portal Accounts - but now Team Administrators can make MFA mandatory for all Team Members. This is done via the Team > Setup > Team Info screen.

Once enabled, only Portal Users using MFA will be allowed to log into the team.  

Team members not using MFA can configure it from the Team Selection screen by clicking the Enable MFA or the [Edit Security] button.

Note that for Private Licensees, SSO-based Portal Users are treated as MFA-enabled - as it is assumed that MFA is provided by their SSO solution.

Additional Improvements

Release 5.5 includes a ton of other improvements as well. These include:

• API Improvements

  • New APIs have been added to the AppStore, Authentication, and Lobby services. See the API Changes section for more details.

• [Refresh] App Metrics

  • App metrics are daily processes that aggregate and calculate various statistics about your app - such as API Usage, sales aggregation, retention data, etc.
  • In some rare circumstances - the calculation of those metrics may be interrupted.
  • To re-trigger the calculation of the metrics - navigate to App > Design > Admin Tools > Cache and click [ Refresh Metrics ]

• Client-Server Protocol

  • We have improved our protocol handling so that client retry attempts are now properly compressed (when applicable)

• [Optimized] Group Leaderboards

  • Before 5.5 brainCloud, player- and group-based leaderboards were stored in the same collections. This is not optimal - especially when dealing with large [sharded] leaderboards. brainCloud now stores player-based leaderboards and group-based leaderboards separately.  
  • A new compatibility flag controls this behavior. When enabled, the flag preserves the old behavior. The flag is enabled by default for existing apps and disabled for new apps.

• Hosted Servers

  • A new "Retrieve Logs" option was added, which determines whether the logs from successful room/relay server sessions will be retrieved. By default logs will only be retrieved if the container exited with a non-zero result.

• Matchmaking Monitor

  • The Matchmaking Monitor has been enhanced to show stats for how fast players are launched into actual matches.  ← Before the stats stopped at being added to a Lobby

• Portal SSO and Builder API

  • The Builder API has been enhanced to support dynamic authentication as an OAuth SSO Provider
  • This allows Private and Platform Licensees to build custom applications that use brainCloud’s Portal Accounts for authentication - and access brainCloud’s Builder API via new dynamic [and temporary] API keys
  • Note that this SSO Provider is for portal accounts only - not the end-user accounts of brainCloud apps [that is a future feature under consideration]

• S2S IP Security for Room and Relay Servers

  • brainCloud can now dynamically restrict the S2S interfaces associated with Room and Relay servers to the IP addresses of the currently running servers.
  • To enable this feature - go to App > Design > Servers > My Servers, choose the appropriate server type, and enable IP Security.  

• Relay Server Improvements

  • Improvements for when dealing with larger player counts
  • Ability to restrict relay comms to less than 40 players (now defaults to max of 32 for webgl compatibility)
  • Improved disconnect handling
  • Note that the above improvements are all made available via the “V3” version of the Relay Server. The behavioural changes are very subtle and shouldn’t impact the great majority of apps. We highly recommend that devs using “V2” upgrade to “V3” in their test apps (no API changes) and upgrade production when convenient.

Portal Updates

We continue to rapidly evolve the Design Portal.

Team Menu

The flag to enable Team MFA Enforcement has been added to the Team > Setup > Team Info screen.

App Menu

App Dashboard

The new App Alerts section is front and center on the App Dashboard.

We have also added your Client Library version to the App Profile section.

Cloud Code (rendered view)

We’ve added an option to view the rendered version of a cloud code script.  If the [x] Show Rendered option is enabled, the editor shows a read-only view of the script with all included scripts shown inline. This view matches the version of the script that brainCloud keeps cached for runtime execution.

Security

This release consolidates App-related Security sections under App > Design > Security.  

You will find the old settings from App > Design > Core App Info > Security here, as well as the new Brute-Force Protection settings. 

Matchmaking Monitor

The Matchmaking Monitor has been enhanced with a new screen that shows a summary of matchmaking activity across all lobby types.

Click on any row to navigate to the detailed monitoring charts for that Lobby Type.

The details screen has been enhanced to show how long it takes for matches to launch on servers.

The time displayed includes the time it takes to spin up a container (on-demand) - as well as the time to cold-launch a node (server) for the container to run upon (if applicable).

Blocked Users

The User Browser (preview blade) and User Summary screens now show information about Bad Login Attempts and whether a user has been blocked. There are also controls that allow a Team Member to [UNBLOCK] the user and/or [Reset] the bad login attempt count.

Retention Analytics

The new Retention Analytics screen can be found at App > Reports > Analytics > Retention.

Previous day usage

In addition to Today and Yesterday - the API Usage and API Errors screens now include a tab labeled “Previous,” - which displays the stats for the day before yesterday.

API Changes

The following changes and additions have been made to the brainCloud API:

• AppStore Service

  • New API for rewarding products (without a corresponding purchase)
  • New API for recording a purchase (for cases where purchase is handled by custom client code).

• Authentication Service

  • Password reset calls are now accessible from cloud code
  • New GetServerVersion() call available to retrieve the brainCloud server version before authenticating.  This is useful for our example apps.

• Bridge (cloud-code only)

  • New DeleteSessionCacheObject() method - useful if you only need a session cache object temporarily - like when passing information from a pre- to post-hook script.

• Event Service

  • New SendEventToProfiles() method allows for sending the same event to multiple users

• Friend Service

  • New GetProfileInfoForCredentialIfExists() method is the same as GetProfileInfoForCredential() - but skips writing the log entry if the credential doesn’t exist

• Group Service

  • The UpdateGroupAcl() and UpdateGroupEntityAcl() methods are now available from the client libs; previously, they were cloud-code only.

• Identity Service

  • The GetIdentityStatus() method is now available from the client libs

• Leaderboard Service

  • The PostScoreToDynamicGroupLeaderboardUsingConfig() method is now available from the client libs. This method should be used instead of PostScoreToDynamicGroupLeaderboardUTC() and PostScoreToDynamicGroupLeaderboardDaysUTC().

• Lobby Service

  • The CancelFindRequest() method now requires an entryId as a parameter. The entryId is included in the response from the various Find Lobby API calls.
  • New SYS APIs: SysCreateLobby(), SysCreateLobbyWithPingData(), SysGetLobbyData(), SysAddMember(), SysAddMemberWithPingData(), SysRemoveMember(), SysUpdateSettings()

• Mail Service

  • New SendAdvancedEmailByAddresses() method for sending a single email with multiple addresses in the “to:” list.

• PlaybackStream Service

  • The ProtectStreamUntil() method has been added to the client libs. This allows a developer to keep a playback stream around for longer than the default – which is currently 150 days in our Public BaaS.  Extending specific streams is helpful for games that use the streams for ghost replays - and want to keep “featured replays” around longer.

• [New!] Report Service

  • SysGetLatestReport() - returns the data from the latest generated report (of the specified type).
  • SysGetReportForStartDate() - returns the data from the specified report.

Libraries and Examples

Release window - Updated Client and S2S libraries are made available within two weeks of the launch of the updated server software. Updated examples are made available in the two weeks after the client lib updates.

Client Libraries

All Libraries

• All new and missing methods were added as described in the API Changes section.

braincloud-csharp (C#/Unity/Godot)

• Created overloaded FindLobby functions that do not require timeoutSecs parameter. Original functions have been deprecated.
• Improved country/region code retrieval for UWP with Windows.Globalization
• Improved error-handling for Relay Comms ordered packet IDs management
• Fixed issue with WebSocket in WebGL on iOS where the browser resets due to running out of memory

braincloud-unreal-plugin (Unreal)

• Implemented request/response compression

• RTT bug fixes/improvements

  • Fixed issue where the disconnect callback wasn't being triggered in a situation where RTT connection is lost from internet connection becoming unavailable (tested by not sending heartbeat messages)
  • Fixed issue where calling EnableRTT twice before a connection is established causes connection issues, the function is now safeguarded from double calls
  • Fixed issue where received RTT messages were incorrectly processing special characters / non-ASCII characters

braincloud-js (JavaScript)

• Fixed bug in attachAdvancedIdentity function

  • The conditional statement for optional externalAuthName was not checking for authenticationSubType correctly

braincloud-dart

• A brand new library with full support for all brainCloud APIs - including RTT and RelayComms

• The source can be found in the following github repos:

  • braincloud-dart - the core dart library. No flutter dependencies.
  • braincloud-dart-persistence - An add-in library that utilizes Flutter to implement the persistence required by the brainCloud wrapper. It is highly recommended that devs use this with the core library.

• The packages can be found on pub.dev at the following locations:

  • braincloud - the core library package
  • braincloud_data_persistence - (see description above)

S2S Libraries

No changes in this release.

Examples

All examples will be updated to use brainCloud 5.5 in the coming weeks (generally 2-4 weeks after release).

Documentation and Tutorials

BootCamp

• No changes

Documentation

• All the latest API additions and changes have been incorporated into our docs.

brainCloud 5.4.1 isn't a full release - but there have been enough tweaks and improvements to warrant a page describing them.

Features and Improvements

PlaybackStream Protect API

brainCloud 5.4 added Sys APIs for PlaybackStreams - to make them more convenient for use as ghost players, community members in hub worlds, etc.

A challenge, however, is that PlaybackStreams are automatically deleted 90 days after creation. This may not be desirable in all use cases.

To address this, we have added new APIs to "protect" a stream from automatic deletion for a number of days. This API can be called periodically to keep specific playback streams around in perpetuity...  (For example - a cloud code script could be written to run daily to protect the "featured" replays of the system for days into the future).

The new calls are ProtectStreamUntil() and SysProtectStreamUntil().

Apple Receipt Validation Improvements (and a new warning)

We have addressed a scenario where brainCloud was not validating the bundle id for old legacy-style receipts -- even if the bundle Id has been correctly entered on the App > Design > Core App Info > Application IDs page. This has been fixed.

That said - we remind devs that the Bundle ID field, although optional, does allow brainCloud to further validate that the receipt provided is from proper app. It is highly recommended that developers using Apple's AppStore for In-App Purchases fill in this value!

To encourage the use of the field, we have added a new warning for Apple purchases made without validating the bundle ID. The warning includes the bundle ID present in the used receipt.

The message looks like this:

Purchase security warning - iTunes bundle id should be set for greater security. Purchase with bundle id '' still processed.

You can search for these warnings using the following log filter:

• service: appStore
• operation: VERIFY_PURCHASE

We have added a new warning message to the system as a reminder to fill it in and as a confirmation of what bundle ID was currently used. Developers can use the warning to confirm what value should be entered on the page and look for fraudulent entries.

View Leaderboard and Group users in a separate tab

We have expanded our UI paradigm to allow viewing users in a separate browser tab - without otherwise losing the context of where the team member is in the Portal. 

For now we have added this feature to just the Leaderboard and Group screens - but we'll be adding more support in coming releases.

Miscellaneous fixes and improvements

Server fixes and improvements

• BCLOUD-7437 - Fixes to user rate limiting
• BCLOUD-8468 - Server request-response log - add incoming IP to ERROR MESSAGE instead of RESPONSE
• BCLOUD-8869 - Add support for existing filters to the export functionality
• BCLOUD-9262 - Performance improvement: now reading shard count at beginning of matchmaking run
• BCLOUD-9285 - Change to the "never" Global Entity expiry value to prevent issues in javascript
• BCLOUD-9315 - Added new PlaybackStream APIs: ProtectStreamUntil, SysProtectStreamUntil
• BCLOUD-9356 - Modified support for CANCEL_FIND_REQUEST to require an entryId to work; without it the call is a no-op
• BCLOUD-9357 - Increment user's failedRedemptionsTotal for each RedeemCode attempt after being locked out
• BCLOUD-9358 - Removing support for lobby entry queue v2 (everyone is on v3 now)
• BCLOUD-9378 - PortalX is loading uppercase email address and the Server is not automatically lowercasing it
• BCLOUD-9379 - Spelling mistake in Amazon IAP error message
• BCLOUD-9386 - Global Entities count on list screen including expired entities
• BCLOUD-9390 - Bug fix for treating a full team as a full lobby during lobby join
• BCLOUD-9393 - Builder API Create a cloud code script returned error
• BCLOUD-9398 - Builder API Team Level - Fix for out-of-date updatedAt value
• BCLOUD-9400 - Request/Response entry pairs not matching on sequenceId
• BCLOUD-9411 - Log all APP packetId-related errors as APP WARNING (not APP ERROR)
• BCLOUD-9425 - Added missing ENV variables for Edgegap servers
• BCLOUD-9447 - Compress cached last response if size is greater than maxLastResponseSizeBytes
• BCLOUD-9483 - Add pre-truncated request size to log when truncating it
• BCLOUD-9508 - Updated billing logging
• BCLOUD-9513 - Billing fixes… (had mistakenly treated some values at bytes instead of straight counts)
• BCLOUD-9528 - less strict on Lobby RemoveMember and UpdateSettings
• BCLOUD-9532 - optional (via brainCloud Property) logging of downloads
• BCLOUD-9542 - Validate range parameter in file servlet rather than passing on to CDN
• BCLOUD-9568 - Added ‘skip_telemetry’ parameter to Edgegap session creation
• BCLOUD-9581 - Added legacy sandbox receipt bundle id validation

Portal-X fixes and improvements

• BCLOUD-9336 - Fix issue in displaying brainCloud properties that have been overridden 
• BCLOUD-9361 - Hide RTT session chart on App Dashboard if RTT is not enabled
• BCLOUD-9365 - When creating global entities, the entity type should be selected by default
• BCLOUD-9370 - Fixed sort order in Server Monitor screen
• BCLOUD-9371 - Fixed percentage errors display in Script Usage panel
• BCLOUD-9377 - Added toast message failures during Export Configuration
• BCLOUD-9385 - Fixed Global Entities Export
• BCLOUD-9405 - Improvements to Universal Search SCREEN results presentation
• BCLOUD-9406 - Global Files - fixed issues around recovery folder
• BCLOUD-9407 - Updates and fixes to user request+response logs
• BCLOUD-9408 - Add the ability to view player/group in a new window/tab
• BCLOUD-9414 - Fix to display job results for all run states except Scheduled
• BCLOUD-9426 - Show “Loading…” for screen title text when loading screen data
• BCLOUD-9438 - Fixed issue with modal popup when no folders are present.
• BCLOUD-9439 - Fix issues in Global Files File Path & File Tree
• BCLOUD-9512 - Fixed Number (decimal) field issue in brainCloud Properties Dialogs
• BCLOUD-9582 - Addressed vulnerability CVE-2022-25927
• Plus - fixed formatting of available funds value in Team Billing info

brainCloud BaaS will be upgraded to MongoDB 6.0 on Wednesday, September 25th, starting at 8pm Eastern.  It is a rolling upgrade that may take up to 3 hours to complete.  All API and Portal services will be fully available during the upgrade. The Portal will NOT be disabled.

Note that all brainCloud Private Instances will be upgraded in the following weeks - before October 31st, 2024.

brainCloud 5.4 has been tested to be fully compatible with MongoDB 6.0.

That said, MongoDB 6.0 contains an Important Change that brainCloud developers must be aware of:

In MongoDB 6.0, $regex Find Queries No Longer Ignore Invalid Regex.  This means that while invalid $regex expressions were ignored in MongoDB 5.0 -- in MongoDB 6.0, the same query will return an error.

For example, in MongoDB 5.0, the following query, which includes an invalid regex option (i.e., "bad"), returns a successful database response with a document.

In MongoDB 6.0, that same query returns an error from the database - thus, brainCloud also returns an error.

This change only affects brainCloud's list and paging-style calls (which accept custom query JSON) - and ONLY apply if the developer-provided queries have invalid $regex or $options.  These calls include:

• Custom Entity - GetEntityPage(), SysGetEntityPage()
• Entity - GetList(), GetListCount(), GetPage()
• Global Entity - GetList(), GetListCount(), GetPage(), GetSystemEntityList() GetSystemEntityListCount(), GetSystemEntityPage()
• Group - ListGroupsPage(), GetRandomGroupsMatching(), ReadGroupEntitiesPage(), SysGetRandomGroupsMatching(), SysListGroupsPage(), SysReadGroupEntitiesPage()
• Item Catalog - GetCatalogItemsPage(), SysGetCatalogItemsPage()
• Leaderboard - SysGetLeaderboardConfigsPage()
• Messaging - GetMessagesPage(), SysGetMessagesPage()
• RedemptionCode - SysGetCodeTypePage()
• User - SysGetPage()
• User Items - GetUserItemsPage()

So - in summary:

• If your app isn't using $regex expressions in your query - you have nothing to worry about
• If your app is using VALID $regex expressions and valid $options - you have nothing to worry about
• If your app is using INVALID $regex expressions or $options - then brainCloud may now flag that error

A description of MongoDB 6.0 $regex and $options can be found here.

Feel free to reach out to brainCloud Support if you have questions.

brainCloud 5.4 is a massive update - and furthers our goals of advancing brainCloud’s support for Product Management, Customer Support, and Multiplayer Developers.

This release includes:

• New EdgeGap Multiplayer integration!
• New Matchmaking Monitor screen for visualizing the performance of Online Matchmaking.  Plus we’ve significantly improved the performance of matchmaking to boot!
• New Server Monitor screen for viewing hosted Room and Relay servers. We’ve added new launch progress events. And we have also added hosting capabilities for private deployments on Azure and Google Cloud!
• New Region, Language, and App Store analytics
• A bunch of API enhancements
• and much, much more! 

Plus - we bid farewell to our legacy portal! Long live Portal-X! 😀  

Notice - the new Region, Language, and App Store analytics screens will not be available until the nightly jobs can generate the required data. 

Compatibility Notes

Ensuring stability and backward compatibility for existing apps is a key priority. 

brainCloud 5.4 adds one new compatibility flag (enabled by default for existing apps) which allows devs to suppress the new server launch progress events.  This is a safety measure in case the client apps don’t automatically ignore them.

 Disable Room Server Launch Progress Messages

---

Release Highlights

EdgeGap Multiplayer

As you know, brainCloud provides everything you need right out of the box for easy-to-implement multiplayer. We’ve got flexible Online Matchmaking, Lobbies, Peer-to-peer and Dedicated-Server Examples, and built-in support for Room and Relay Servers that can be launched in regions all around the world.

But what if I told you that with hardly any changes to your multiplayer container - you can level up your multiplayer even further?  We’re talking lower latencies for players; faster cold starts; lower idle costs - and overall cost efficiency!

Too good to be true? Well - that’s what you get with our new EdgeGap Integration!

Just (1) set up an EdgeGap Account, (2) configure a server in brainCloud via the My Servers page (App > Design > Servers > My Servers), (3) link your lobbies to the new EdgeGap server type, and (4) modify your server code to tell EdgeGap when a session completes. That’s it - no client changes at all!

Pricing - requires a paid EdgeGap account. brainCloud does not add hosting fees on top of the EdgeGap charges. To compensate for matchmaking server usage, brainCloud adds 5 api counts per player matched to EdgeGap servers.

Matchmaking Monitor [Beta] & Sharded Matchmaking

brainCloud’s Online Matchmaking can be a tough process to visualize - until now!  

Our new Matchmaking Monitor screen (App > Global > Multiplayer > Matchmaking Monitor) provides real-time insights on matchmaking load and performance. Just select a lobby type and voila - the stats start streaming in.

And brainCloud’s matchmaking is now dynamically sharded - so extra CPU resources are brought online when you need them.

Note that this is a beta version of our Matchmaking Monitor - additional stats, better memory handling, and some more UI polish will be added in future releases.

Server Monitor [Beta*]

For those using brainCloud’s native Room and Relay Server Hosting - we’ve added a new Server Monitor screen (App > Global > Multiplayer > Server Monitor) to help visualize the running nodes and containers. Just select a server type and the screen will start updating.

Note that this is a beta version of our Server Monitor - there are plans to add CPU and Memory utilization metrics in the future.

Additional Improvements

brainCloud 5.4 includes a ton of other improvements as well:

• AppStore Transactions

  • We’ve added new cloud code-only methods for retrieving purchases recorded in brainCloud. Note that this API does not return data from the legacy transaction collections.

• Azure and GCloud Hosting

  • Private and Platform Licensees on Microsoft Azure and Google Cloud can now natively host Room and Relay Servers in those environments. Customers should contact brainCloud support to deploy the feature.

• Completed Divisions

  • Divisions no longer immediately disappear from getMyDivisions() once they have been claimed. They will now remain available in a COMPLETED state for as long as the division results are available.

• Dart & Flutter!

  • Our client team is hard at work creating a Dart version of the brainCloud library - suitable for use in Flutter and other apps.
  • It’s still early going - but feel free to check out the develop branch for an early look at things!

• IfExists Methods

  • Sometimes an error is okay - and there is no need to log it!
  • We have added new IfExists versions of several key methods (in the Leaderboard and Event services) to help keep your logs clean.

• Invisible Presence

  • Devs can now configure Presence so that users are initially invisible.  This is configured from the App > Design > Messaging > Presence screen.

• Remote DevTool

  • The Remote DevTool (remote to the brainCloud platform) allows developers to host Room Servers locally on their workstations for debugging purposes
  • Added a new and improved Debug Mode to better debug dedicated servers and hit breakpoints

• Replay System

  • brainCloud Playback Stream service is normally used for one-way multiplayer match replays - as demonstrated in the brainCloud Clashers demo.
  • This release adds new “Sys” and S2S-compatible APIs so that Playback Streams can be used by Custom Room Servers to directly enhance the gameplay experience. Think ghosts in racing games, crowds in hub worlds, etc.
  • In addition to the APIs - we’ve got a new example game, Invaders, that demonstrates the feature - and a great knowledge base article that describes how to make it work for your game!

• Server Launch Progress Messages

  • New events will be sent to all lobby members when starting hosted Room or Relay Servers
  • These events can be safely ignored – or can be used to communicate more information to clients as servers launch

• /servertime endpoint

  • A /servertime endpoint has been added to brainCloud, which returns the current server time in simple JSON format. 

• Status Effect Behaviour

  • Devs can now control, from the item catalog definition, whether status effects extend or replace the duration of the effect.   ← Initially introduced as a patch in 5.3

• WebHook Log Security

  • As a security feature, devs can now configure webhooks so that key parameters received are not recorded in the server logs

---

Portal Changes

We continue to rapidly evolve the new Portal. 

In addition to the new Matchmaking and Server Monitor screens (see above), 5.4 adds new Analytics, Usage, and Usability features!

Analytics

New & Returning Users

The new Daily Active Users chart added to the App Dashboard and App Analytics pages gives you immediate feedback on how your app community is evolving daily.

 

Region and Language Analytics

We have refactored our Region and Language analytics processing - and added new pages to better communicate who is using your app!

 Notice - these screens will not be available until the nightly jobs can generate the required data. 

Store Analytics

The new Store Analytics page shows your app’s financial performance by platform.

 Notice - this screen will not be available until the nightly jobs can generate the required data. 

Usage

API Usage

The API Usage screen now displays trend icons depicting how this month’s extrapolated usage compares with the previous month.

Monthly History

Speaking of previous months - you can now travel back in time to see what your app’s usage looked like in previous months!

Script Usage

We have added a new chart to the Script Usage screen to help you zero in on the cloud code scripts that could benefit most from optimization. 

Just bring up the page - and work your way down the list from top to bottom!

Remember - fewer API calls → fewer server resources → faster responses → lower costs. It’s win:win:win!

Usability

API Explorer & Portal Authentication

We have replaced the default Authenticate and [Quick Auth] features in the API Explorer and Script Editor with a new Portal authentication type.  This new identity type is only useable from within the Portal - and can be attached to any end-user account.

This change fixes an issue where [Quick Auth] would not work properly for apps that had Password Enforcement standards enabled. 

Note that “Portal” auth is the new default authentication type for the API Explorer.  The first time you use it it will by default create a new user account with that identity type.  It uses the email address associated with your Portal account as the id.

If you would like to attach that Portal identity to an existing end-user account:

• Log into the API Explorer as that end-user account.  This would normally be accomplished by finding the user via the User Browser, and then clicking the [Login as User] button.
• Attach your Portal identity to the account. In the API Explorer, navigate to the Identity service and Attach operation. Your portal email address will automatically be filled into the externalId. Leave all other fields as is. Click [Execute].

And voila - from now on, clicking [Quick Auth] will log into the account that you selected!

 

User Activity

We have added an informative preview pane to the User Activity screen.  Now if you click on a login entry - you’ll see a summary of what changed during that play session!  Increased/decreases in XP, purchases, virtual currencies - etc. Super helpful!

 

Advanced Settings > Compatibility Flags

This screen has been enhanced to make it easier for developers:

• Compatibility flags are now listed from newest to oldest - and we even display the brainCloud release in which a particular flag was added.
• By default - only the enabled flags are shown. [No reason to show old flags that do not apply for your app!].  Remember - when we add new compatibility flags to the system - they are automatically enabled for your app. We encourage devs to review whether they need a flag enabled though - and disabled it if they do not. brainCloud apps will perform best with all compatibility flags disabled!
• Flags are now searchable! ← note - be sure to uncheck the [x] Only show enabled option to search across all flags.

Filtered Global Entity Exports

The App > Global > Global Data > Global Entities screen now allows you to export a sub-set of a type of Global Entities.

Simply use the [Refine] button to find a subset of the entities - and then export as normal from the Bulk Actions menu. You’ll notice “filtered” in the export options - confirming that it is a subset of the objects that will be exported.

 

---

API Changes

The following enhancements have affected the brainCloud API:

• AppStore Service

  • [New!] SysGetTransactionsPage(), SysGetTransactionsPageOffset() - new methods for returning a summary list of a users' purchases.  Note - does not include all fields. 
  • [New!] SysGetTransactionDetails() - returns additional information about the specified transaction.

• Event Service

  • [New!] UpdateIncomingEventDataIfExists() - a variant of UpdateIncomingEventData() - but doesn’t write an error log entry if the evId specified no longer exists.  Useful for keeping the error logs clean when that’s a normal use case.

• Leaderboard Service

  • [New!] IfExists variants of calls won’t log an error if the leaderboard does not exist. Helps to keep your logs clean!

    • GetGlobalLeaderboardPageByVersionIfExists()
    • GetGlobalLeaderboardPageIfExists()
    • GetGlobalLeaderboardViewByVersionIfExists()
    • GetGlobalLeaderboardViewIfExists()
    • GetPlayersSocialLeaderboardByVersionIfExists()
    • GetPlayersSocialLeaderboardIfExists()
    • GetSocialLeaderboardByVersionIfExists()
    • GetSocialLeaderboardIfExists()
  • [New!] PostScoreToDynamicLeaderboardUsingConfig() method has been added to all client libraries. This is a much more flexible version of PostScoreToDynamicLeaderboard() which is now deprecated.  In particular,  PostScoreToDynamicLeaderboardUsingConfig() allows dynamically created leaderboards to have an expiry TTL - which is highly recommended for timed leaderboards!

• Lobby Service

  • [Improved!] FindOrCreateLobby() and its variations now send additional RTT events if/when hosted Room or Relay Servers are being launched. These events are entirely informational and can be ignored - though developers may want to use them to trigger on-screen updates for the end user.

• Tournament Service

  • [Improved!] GetMyDivisions() - now returns divisions that have been claimed in a new COMPLETE status…  Completed divisions will be returned as long as the associated leaderboard data is still available.

We have also deprecated the following methods:

• Leaderboard Service

  • PostScoreToDynamicLeaderboard() - will be removed from the client libraries after September 2025. Use PostScoreToDynamicLeaderboardUsingConfig() instead. The legacy method will continue to work for apps using old client libraries.

---

Libraries and Examples

Client Libraries

All Libraries

• Removed cxId parameter from cancelFindRequest function
• Added “IfExists” versions of various leaderboard functions that do not return an error if a leaderboard does not exist or is expired)
• Added PostScoreToDynamicLeaderboardUsingConfig() function
• Added “IfExists” version of UpdateIncomingEventData() function for Event Service

braincloud-csharp (C#/Unity/Godot)

• Added conditions to correct country code to ensure consistent formatting

  • “419” would become “_LA_”
  • “Hans” and “Hant” would become “CN”

braincloud-unreal-plugin (Unreal)

• Fixed compatibility issues with Unreal Engine 5.4

braincloud-cpp (C++)

• Added conditions to correct country code to ensure consistent formatting

  • “419” would become “_LA_”
  • “Hans” and “Hant” would become “CN”

braincloud-js (JavaScript)

• Fixed bug with usage of Node Buffer module

braincloud-dart (Dart)

• Pre-alpha version of our new Dart-based client library

 

S2S Libraries

brainclouds2s-cpp (C++)

• Added vcpkg.io to the S2S CPP library, allowing it to build for both Windows and Linux (MacOS still a WIP). With vcpkg dependencies are managed dynamically, so static libraries were removed from the repo and replaced with libraries that are downloaded through vcpkg.

Examples

Note: brainCloud example apps are dependent upon the brainCloud published client libraries - and are thus released in the two weeks that follow a new brainCloud release. 

Stay tuned for updates!

---

Documentation and Tutorials

BootCamp

• Additional Godot tutorials are now available!
• Updated the Portal images in many of the Unity tutorials ← PortalX is moving too fast!
• Be sure to check out bootcamp.braincloudservers.com if you haven't already!

Documentation

• All the latest API additions and changes have been incorporated into our new doc site at docs.braincloudservers.com !

• New knowledgebase articles available:

  • Implementing a Replay System in brainCloud
  • Implementing a Jackpot System in brainCloud

 

 

brainCloud 5.3 is a significant release that reflects our goals of advancing brainCloud’s support for Product Management, Customer Support, and Multiplayer Developers in 2024.

Most urgently - this release includes support for Google’s Firebase Cloud Messaging (FCM) V1 API – just in time because the old FCM APIs will cease functioning in June 2024. Devs will want to upgrade their app configurations in short-order before the deadline.

This release includes improved handling of In-App Purchases, new Product Analytics, performance improvements for Lobby Matchmaking and Room/Relay Servers, new API calls and more! 

Finally, we have packed in a bunch more Portal polish - including our redesigned Context Banner, new User Menu, and new User Unlock feature! 

Compatibility Notes

As always - we have done all of this with an emphasis on preserving stability and backward compatibility for existing apps. Developers should be aware of the following changes:

• Google FCM HTTP v1 API - To use the new FCM API, developers must update their Google push settings to include a Service Account JSON.
• Country Codes - We have improved the country code lookup functionality in our client libraries and are now validating the codes sent to the server to enforce a standardized set. A new capability flag controls this behavior: “[x] Do not enforce valid Country code” which defaults to checked for existing apps to maintain the previous (legacy) behavior.
• Posting Scores with null extra data -  Now - if the app updates a score (via PostScoreToLeaderboard() or similar calls) while specifying null for the data parameter, the system will preserve the existing data associated with the score. (Previously, it would clear it).  There is a new capability flag to control this behavior: “[x] Do not preserve Post score with data null” - which defaults to checking for existing apps to maintain the previous (legacy) behavior.
• For apps with Tournaments and RTT - brainCloud will now send RTT-enabled events when a tournament has completed. This will allow the app to notify the user in real-time.
  Note that we did not implement a compatibility flag for this - as it should “just work” for apps that are already using Tournaments and RTT - but contact support if there are issues. We can disable it on a per-app basis!

Release Highlights

Google FCM V1 API

Google’s legacy Google Firebase Cloud Messaging APIs, which brainCloud up to 5.2 still uses, are being removed in June 2024.

brainCloud 5.3 has been updated to use the new APIs - but to do so, developers must update their Google push settings to include a Service Account JSON.  This is done via the portal's App > Design > Notifications > Settings page.

Technically devs do not need to update their client code to use the new notifications. But devs using the raw push notification methods may want to update the raw JSON they send to take advantage of new FCM V1 features.

Product transactions

We have made big improvements to the recording and reporting of Product Transactions (i.e. In-App Purchases) in brainCloud, namely:

1. We are now more accurately distinguishing between sandbox and production purchases.
2. Sandbox and Mock store purchases are no longer included in daily and monthly metrics
3. Pending purchases now expire (and are deleted) after X days
4. Mock AppStore purchases can now be performed via the Client API - but only by users flagged as “Testers” in the system

Refreshing previously calculated all-time revenue

We have added a feature to allow an app’s total revenue metric to be re-calculated… (to remove the impact of previously recorded sandbox, mock, and/or pending transactions).

This process will scan through all transactions - properly skipping over sandbox, pending, and mock transactions. 

Limitations:

• The scan does not include revenue from legacy transactions (those that occurred before November 2018)
• It also will not pick up the revenue from deleted users (as their transactions are deleted with them).
  • By default, Dormant User Deletion skips users with purchases - so the totals are unlikely to be affected by the dormant user deletion process - it would just be users with purchases that chose to delete their accounts.

Note that this process does not update previous daily or monthly totals - just the all-time revenue and purchase counts.

The function can be accessed from the Team > Manage > Apps page - by selecting “Refresh Revenue…” from the app’s action menu.

Country Codes

We have significantly improved both the:

• Retrieval of country codes [by our client libraries]
• Validation of country codes [by our servers]

Previous versions of the client libraries were simply retrieving an "assumed" country code from the locale APIs of the client device. This means that if you choose "US English" the system would assume that you are in the US - even though that just may be a language preference... (eg. lots of folks in Canada would choose "US English" simply because they prefer US spellings - like "color" instead of "colour" - "favorite" instead of "favourite", etc.). But that doesn't mean those folks are in the US!

Also - this mechanism can lead to further ambiguities - as Spanish is spoken in so many South American countries that the country code comes back as the number "419" (which indicates "Latin America Spanish").

So... here is how the new processing works (in priority order)

1. The client libs on supported platforms (iOS, Android, Playstation, etc) will now first attempt to fetch the country code from a more appropriate region selection (instead of from the language locale)
2. If that is not available, the client will use the language locale (as before)
3. If the language locale comes back as "419" (which indicates "Latin America Spanish") - our libs will convert that to a special country code of "_LA_" <- for latin america

And finally, our servers now validate the country code being sent to them - rejecting bad values (and preserving the existing country code stored against the account if there is one).  And note that we have the special Latin America ("_LA_") country code that we use in place of 419 if that's the only information that we have.

Important notes:

• This new country code lookup functionality is only available in the 5.3 client libraries and above - so be sure to upgrade!
• A new capability flag controls the server-side valication: “[x] Do not enforce valid Country code”.  This compatibility flag is automatically enabled for existing apps, and disabled for new apps.

Additional Improvements

But wait - there is more! Other improvements include:

• Cloud Code Scripts

  • Improved importing of scripts from zips (with folders) when the scripts do not have metadata

• Lobbies

  • Multiple improvements to Lobby matchmaking performance

• Purchases

  • Improvements to purchase data captured - now included item title and originalPrice - but drops the unused description field.

• Room Servers

  • Improved scalability of launching multiple Room / Relay Servers in parallel

Portal Changes

There are significant changes to the Design Portal in 5.3.

Context Banner

The Team / App / User Context Banner has been re-implemented to be more informative and yet take up less space on the screen. It even has a new mini version that tucks up into the corner of the screen when you collapse it! 

[New!] User Menu

The most obvious change in brainCloud 5.3 is the introduction of the new User menu. Your users are the heart of your application - and it’s about time that brainCloud treated them that way!

The User menu elevates player searches to a top-level feature and is much more accessible for non-development personnel (i.e. Customer Support Reps, etc.).

User Unlocking

To further streamline support, live user data can now be edited without fully unlocking the app. 

The new User Lock is a single-click mechanism that unlocks a specific user for editing (by the local Portal user). This mechanism is quicker, safer, and less scary than fully unlocking an app to make changes.

User Summary Data

User Summary Data is now displayed more prominently throughout the portal. You’ll see it in User Previews and on the revamped User Summary page itself - where you can even edit it directly!

User Virtual Currency

The User Virtual Currency screen has been enhanced with a chart of the user’s currency balances for the past 30 days.

In-App Purchase Transactions

Two new screens have been added to the portal:

Global Transactions

The new Global Transactions screen (available at App > Global > Marketplace > Transactions) provides a view of recent IAP purchases by app store.  Note that users without the All or Reporting Role permissions can only see item counts - they do not see revenue totals.

Product Analytics

The new Product Analytics screen (available at App > Reports > Analytics > Product) for all users with All or Reporting Role permissions, provides an overview of purchases by product for the selected timeframe.

My Servers

We have improved the configuration dialog for Room and Relay Server hosting to better communicate the performance and/or cost impact of certain settings.

The most common confusion is how Min Ready Containers combines with Containers per Server to affect the number of servers that are running 24x7 - even if they are idle. 

Explanation:

• Setting Min Ready Containers to > 0 reduces the average launch times for Room and Relay Servers, because brainCloud will attempt to keep enough server VMs running with free spots for the specified number of containers. We call this feature Quick Launch.
• For example - If Min Ready Containers is set to 8, and Containers per Server is set to 4, a minimum of 2 servers will run at all times to satisfy the Min Ready Containers requirement.
• Furthermore, in the above example, if Containers Per Server were changed to 1, it would mean that 8 servers would run at all times!

This can lead to surprising bills for customers - which obviously is not what we want. 

The My Servers list page now displays:

• Quick Launch - an icon to indicate that Min Ready Containers is > 0 - which allows matches to start faster since there should generally be a warm server around to host them
• Idle Servers - a calculation of the minimum number of servers that will be running at all times - so that the developer has a heads up! 

In addition - we have added additional help text and costing indicators ($ - $$$$$) to help developers better understand the cost impact of the configuration settings.

API Changes

The following changes/additions have affected the brainCloud API:

• AsyncMatch

  • The new UpdateMatchStateCurrentTurn() function - which allows the current player in the game to overwrite the matchState and statistics without completing their turn or adding to matchHistory

• Group

  • The new DeleteGroupJoinRequest() method allows an end-user to delete their request to join a group.

• Leaderboard

  • The new SysDeleteLeaderboardConfig() method allows devs to delete leaderboards even if tournaments are configured against them. This method is available in Cloud Code only.

• PlayerState

  • New UpdateCountryCode() method that allows a user’s country code to be updated. This method is available in Cloud Code only.

• Tournaments

  • New behavior - for apps with Tournaments enabled - brainCloud will now send RTT-enabled events for when a tournament has completed. This can allow the app to notify the user in real-time.
    Note that we did not implement a compatibility flag for this - as it should “just work” for apps that are already using Tournaments and RTT - but contact support if there are issues. We can disable it on a per-app basis!

Client Libraries

All Libraries

• Created canReconnect() helper method that returns true if there are stored Anonymous and Profile IDs on the device that can be used for reconnect authentication
• Added logout functions to Wrapper for application close events
• Changed how country code is retrieved on devices, instead of getting the country code from the language selection locale, there is now specific code per platform to fetch the country code from a more appropriate region selection on the supported OS platforms. (PC, Mac, Android, iOS, PlayStation, Nintendo)
• Added updateMatchStateCurrentTurn() function: Allows the current player in the game to overwrite the matchState and statistics without completing their turn or adding to matchHistory

braincloud-csharp (C#/Unity/Godot)

• as above

braincloud-unreal-plugin (Unreal)

• Added new module to plugin that provides access to native Android functions to get device information, including a function that gets the country code of the device. It first attempts to get it from the SIM card, if the device doesn’t have a SIM card, it tries to get it from the connected wi-fi network and if the device is not connected to any network, it will default to getting the country code from the selected Language (country) locale.

braincloud-cpp (C++)

• as above

braincloud-java (Java)

• as above

braincloud-js (JavaScript)

• Added logout functions to Wrapper for application close events

  • logoutOnApplicationClose() uses the Fetch API to send a logout request. When triggered by a "beforeunload" event, this attempts to send the request when the page/tab is closed/refreshed
  • runScriptAndLogoutOnApplicationClose() is similar to logoutOnApplicationClose(), but it sends a request to run a Cloud Code script before logging out

S2S Libraries

• no updates

Examples

All Examples

• Added logout on windowClosing for all demos
• Added logout buttons to applicable demos

• Implemented reconnect authentication in applicable demos

  • attempts reconnect automatically on app start and displays login fields if not successful

examples-unity (C# Examples)

• Bombers, BCChat, TicTacToe all got updates and bug fixes
• BC Clashers UI overhaul, gameplay features added
• Invaders: Added features for when a user is connecting to a room

examples-godot (Godot Examples)

• Improved RelayTestApp demo

example-csharp (Xamarin Examples)

• Xamarin examples updated

examples-java (Java Examples)

• Added logout on windowClosing for RelayTestApp
• Added logout buttons to Android demos

• Implemented reconnect authentication

  • attempts reconnect automatically on app start and displays login fields if not successful

examples-javascript (JavaScript Examples)

• Implemented new logout functions as described in the brainCloud-JS changes above so that the examples will automatically logout when closed
• Added logout buttons to RelayTestApp and Warstone as there was previously no way to logout of these examples manually

• RelayTestApp now uses getLobbyData()

  • populate lobby types options list
  • read rules to determine if users can join in-progress matches or return to lobby with same members (END_MATCH)
  • read teams to determine game mode (Free-For-All or Team)

examples-unreal (Unreal Examples)

• Improved test app for deployment to consoles and devices
• reconnect and logout features as above, plus Remember Me feature
• BCChat, Relay Basters and Tappy Chicken various improvements, features, bug fixes

braincloud-roomserver-unreal (Dedicated Demo)

• reconnect and logout features as above

examples-swift

• reconnect and logout features as above

examples-cpp

• reconnect and logout features as above

Documentation and Tutorials

BootCamp

• More Godot BootCamp video lessons

Documentation

• All the latest API additions and changes have been incorporated into our new doc site at docs.braincloudservers.com !

brainCloud 5.2 is a hefty release and includes:

• a new and improved Redemption Code system
• new user metrics and visualizations
• a more refined Design Portal - with improvements for the whole team!

In addition, there are a bunch of significant technology upgrades under the covers (Java 11 → 17, Spring 5->6, etc.) – all to ensure that the platform remains performant and secure!

Compatibility Notes

As always - we have done all of this with an emphasis on preserving stability and backward compatibility for existing apps. Developers should be aware of the following changes:

• Redemption Codes

  • When calling RedeemCode() without specifying the optional codeType, the API now assumes that scan codes <= 20 characters are Shared Codes, and codes >= 25  are Personal Codes.
  • All redemption codes are now stored in UPPERCASE format. All lookups first convert the incoming code to UPPERCASE for case-insensitive lookups. Before 5.2, codes were generated in lowercase and stored “as is”. 
  • Lookups of older codes will still work as long as the “[x] Support legacy case-sensitive redemption codes ('personal' scan codes)” compatibility flag is on. It defaults to ENABLED for existing apps. Note that this involves an extra look-up if the compatibility flag is enabled (which is way slower of course!).  It is strongly recommended that apps have this flag DISABLED if they don't need it!

• Email validation

  • brainCloud 5.2 can validate the format of emails passed during Authentication, Identity, and other Mail-related calls - rejecting invalidly constructed email addresses. This enforcement will be enabled shortly after the launch of 5.2.

Release Highlights

Redemption Codes

The brainCloud Redemption Code system has been completely re-designed and overhauled.

• Personal codes - these are the sort of individualized codes that you might find in a Happy Meal or as a gift card. Each code is unique - and can only be redeemed by a single user. 
• Shared codes [NEW!] - these are sort of a shared coupon code system. The same shared code can be redeemed by multiple people (once each).

While brainCloud has always supported personal codes - support for shared codes is new! The advantage of shared codes is that they are much easier to manage and distribute - and therefore much more convenient for regular promotional campaigns.

Note - a full overview of the new Redemption Code system will be provided in a subsequent update post.

Devs using the older Redemption Code system should keep the following in mind:

• Existing Redemption Code APIs work for both older (Personal) and newer (Shared) redemption codes.
• We have, however, changed how codes are stored. The actual scan codes are now stored in UPPERCASE format (to better support case-insensitive lookups). To ensure previously generated codes still work, a compatibility flag has been added (and it defaults to enabled for existing apps). The new flag is “[x] Support legacy case-sensitive redemption codes ('personal' scan codes)”
• When attempting to Redeem codes without specifying the optional code type (now known as campaign name), the system will assume that codes <= 20 characters are Shared Codes, while codes 25 characters or greater are Personal Codes.

Session Duration (and other metrics)

brainCloud 5 aims to improve the metrics and analytics available to app developers.

brainCloud will never be a full-on analytics platform (that’s a whole product category of its own) - but increasing the scope of what we are providing (from 7-day analytics to 30-day analytics) will greatly help our community in understanding the health of their apps and their users.

To start, brainCloud has added support for Session Duration. This is an important metric for assessing the engagement of the users of an app. But we need your help to collect it!

brainCloud will now record the duration of a session in the loginLog entry of the player… IF the app calls Logout() to inform the servers when the session is over.  Many apps are already calling this (it is an existing method on the playerState service) and thus they don’t need to change anything.

To make it more convenient, we have also added a new Logout() method to the wrapper itself. 

You can check to see if session durations are being recorded for your app by examining the Duration column in the new App > Users > Summary > User Activity screen.  If it has values - you are good! If not - add that Logout() call!

Important - to record the duration of a session brainCloud needs to be told when the session ends. This is done by calling Logout() on the wrapper or playerState service.

brainCloud 5.2 is now collecting additional metrics that will be leveraged in upcoming releases.

These metrics include:

• session activity - we have refactored and expanded our loginLog. brainCloud now tracks the last 30 days' worth of logins for a player.
• session duration - as mentioned above, we now record the duration (in seconds) of a session - IF the logout() method is called. 
• hourly counts - we have increased the number of metrics that we record hourly (as opposed to daily). This will improve our ability to report on user engagement throughout a day - and relative to the previous day at this time
• session balances - we are recording the balances of certain metrics (like XP, currencies, etc) at the start of a session - so that we can compare sessions and report when changes have occurred. This will help brainCloud to better communicate the behavior of a user during the last 30 days in your app 
• last purchase date - a new field to help devs assess the current value of a user to their app. 

Devs will see the benefits of these metrics in future releases of brainCloud.

Portal Customization

In addition to improving the usability of the base screens themselves - we have added a new App > Design > Portal section that allows devs to customize the configuration of the Design Portal for their app. We plan to build upon this feature heavily in future releases.

To start - we have added the ability to customize elements of the User Browser and User Summary. These sections allow devs to simplify the portal by hiding options that don’t make sense for their app (i.e. there is no need to be able to search by PSN ID if your app does not support Playstation!).

On a somewhat related note - devs can now set colors to be associated with Virtual Currencies. These colors are specified on the App > Design > Marketplace > Virtual Currencies screen.

Additional Improvements

brainCloud 5.2 includes a ton of other improvements as well. These include:

• Archived Users - Post-archive scripts

  • Devs can now choose to run a script after a user has been archived. This is convenient if deleting a user may leave a bit of secondary data that needs clean-up. Configure via the App > Design > Core App Info > Archive Settings screen.

• Builder API / CLI

  • Now supports improved exporting and importing of cloud code scripts - so that meta-data can be preserved properly.

• Checkpoints

  • Every time brainCloud does an import or a deployment into your app - it creates a checkpoint - which is a backup of your app.
  • Checkpoints back up your app’s meta-data, scripts, migrate-able custom entities, and migrate-able global entities. They do not include a backup of files - or any user data.
  • This release adds the ability for a dev to manually create a new backup checkpoint
  • Checkpoints are accessed via the App > Design > Admin Tools > Checkpoints screen.

• Email validation

  • Up until now, brainCloud has been fairly lax in verifying the format of email addresses used in the system (requiring our customer’s apps to take on that burden themselves).
  • brainCloud 5.2 now enforces that emails added to the system are validly formatted. ← note - this feature will be enabled a few days after the deployment of the 5.2 software.

• Hosting

  • Launching servers - the system has additional retry logic to help deal with errors that occasionally happen (normally associated with just-in-time patch updates) when launching cold Room & Relay Servers.

• Relay Servers

  • Reconnects - Relay Servers now better handling reconnect scenarios. There is also an option to allow reconnects even if the user’s session has changed ("ALLOW_REJOIN_BY_PROFILE_ID": "true").

• Push Notification Tokens

  • There have been some odd occurrences where users end up accumulating hundreds of push notification device tokens - which can result in rate limiting from Apple & Google when we attempt to send notifications.

  • We have made two changes to help address this:

    • The maximum expiry for push notification device tokens has changed from NEVER to 365 days.
    • User accounts are now limited to a maximum of 10 device tokens. Adding an 11th token will result in the oldest token being deleted.  [Note - this limit is customizable on a per-app basis. Contact support if your app needs an exception.]

• Virtual Currencies

  • By default - our currency system prevents currency balances from going below zero.
  • That said - there are certain situations where the developer (or a CSR) may need to revoke a player's currency - and in those cases the balance _should_ go less than zero (otherwise it would open up a window for fraud).
  • The Design Portal and the APIs have been extended to incorporate the concept of "revoked" currencies.

• Web Services

  • We have added a new [x] Preserve during deploy setting for Web Services
  • This allows your app to have different web service endpoints configured for different stage versions of your app (i.e. Dev vs. Test vs. Production) – and keep deployments from overriding those settings!

Portal Changes

We continue to rapidly evolve our next-generation design portal, Portal-X. This release brings significant improvements and new features - and we’re still just getting started!

Important - we will be removing support for our Legacy Portal soon! If you have feedback on how Portal-X isn’t meeting your needs - now is the time to tell us! Let us know via the Chat Widget or Forums!

Banners and General UI

We are working to make our Portal more useful and user-friendly - especially for non-development personnel like Product Managers and Customer Support Representatives (CSRs).

Our new Live Lock banner reflects this direction - providing a bit more information on what is going on and how to interact with it. 

We have also adjusted the controls for our Context and Screen Info banners - making it easier to understand how to toggle them on and off. 

The placement of the Screen Help hyperlink and the Sharing URL links have been updated as well.

Full-screen Script Editor

Laptop users - we have heard your cries! 

The new Script Editor layout is designed to be easier on screen real estate. We have even added a new Full-screen Mode to take things to the max! 

We have also made the API description sections of the API Explorer and S2S Explorer screens collapsible.

User Screens

One of our big goals for brainCloud 5 is to improve the experience for CSRs (Customer Support Representatives) using brainCloud.

As initial steps toward this goal - we have made several improvements to the Users section of the portal.

To start with, we have improved the experience of searching for users:

• Search

  • Email Search - the system can now do a partial search for a user’s email identity
  • Customization - you can customize the list of search methods via the new App > Design > Portal > User Browser Settings screen.

• User Browser

  • More info faster! - the user browser has been redesigned to surface more information (like which users are spenders on your platform).  The User Browser is also faster and more responsive now.
  • Segments - The Browse tab of the User Browser has been enhanced to support filtering the user list by segment! 
  • User Preview - more useful context regarding the currently selected user.
    Note that you can turn off the Revenue section via the App > Design > Portal > User Summary Configuration screen if your app doesn’t use brainCloud for in-app purchases.

Once you have located the user account - we have put more information at your fingertips!

• User Summary

  • User Activity - a list of the last 30 days of user sessions
  • Recent Errors - a subset of Global Monitoring’s Recent Errors screen - but for the selected user
  • Unreadable Requests - any invalid client API requests that were received (and not processed) from this user

• Marketplace

  • Transactions - An improved view of this user’s purchases - complete with a new chart of the past 30 days of activity.
  • Redemption Codes - an updated view of any Personal or Shared redemption code activity for this user

Lastly, we have improved the Virtual Currency screens to make it easier to understand and adjust a customer’s currency balances (via the App > Users > Marketplace > Virtual Currency screen).

Custom Entity Monitoring Enhancements

We have significantly enhanced the Custom Entities Monitoring screen (App > Global > Global Data > Custom Entities), to make it more responsive - and to offer more custom query capabilities.

The screen now requests the “document count” in the background - so that the initial page of results can be displayed more quickly. When available, it will present the currently “cached” value of the count (which it updates once the full count result is available).

In addition, there are new [Sort] and [Hint] tabs available - so that requests can be fully tailored before sending them to the server.

Portal Scalability

Sometimes our customers surprise us with how heavily they use portions of our system. >10K leaderboards? Really?!! 

We have made significant improvements to the performance of the following screens:

• App > Design > Leaderboards > Leaderboard Configs
• App > Global > Leaderboards > Leaderboards
• App > Global > Global Data > Custom Entities
• App > Global > Global Data > Global Entities ← it’s faster, but more improvements are coming
• App > Users > User Browser

API Changes

The following changes/additions have affected the brainCloud API:

• Authenticate

  • AuthenticateEmailPassword() will now validate the email format before attempting to create a new account. If the provided email is not in the proper format, it will return an error with a reasonCode of 40221 - with the message "Email address fails validation"

• Identity

  • attachEmailIdentity() will now validate the email format before attempting to create a new account. If the provided email is not in the proper format, it will return an error with a reasonCode of 40221 - with the message "Email address fails validation"

• Leaderboard

  • SysGetLeaderboardConfigsPage() / SysGetLeaderboardConfigsPageOffset() - new paged Leaderboard retrieval APIs -- useful for apps with a crazy number of leaderboards! 

• Redemption Code 

  • AddCode() - the method for adding a new code to a Personal Code campaign will now return a warning if the scanCode provided is < 25 characters. Personal Codes should be 25 characters or greater.
  • RedeemCode() - if the optional codeType is not provided, the system assumes that codes <= 20 characters are shared ('multi-use') codes - while codes >= 25 characters are personal ('single-use') codes. 
  • SysAddMultiUseCodeType() - new cloud code-only method for creating Shared campaign redemption codes. (Also known as multi-use redemption codes).
  • SysGetCodeTypePage() / SysGetCodeTypePageOffset() - a new set of cloud code-only methods for retrieving the list of redemption code campaigns. 

• VirtualCurrency

  • RevokeCurrency(), RevokeParentCurrency() and RevokePeerCurrency() methods have been added

• Wrapper

  • AuthenticateEmailPassword() will now validate the email format before attempting to create a new account. If the provided email is not in the proper format, it will return an error with a reasonCode of 40221 - with the message "Email address fails validation"
  • Logout() - new convenience method used for ending a user's API session. Functionally equivalent to the playerState method of the same name, though the wrapper version includes a forgetUser option to clear the profileId saved to the device as well. ← useful for apps that force a full login each time

Libraries and Examples

Client Libraries

All Libraries

• A new Logout() call has been added to the brainCloud wrapper. Includes a forgetUser parameter to clear the stored user's profileId.

braincloud-csharp (C#/Unity/Godot)

• Wrapper Initialize() method has improved validation of the serverUrl parameter:

  • Prepends "https://" if not included in the URL.
  • Automatically appends "/dispatcherv2" if absent (and if there's no other slash with content included in the URL).
• Fixed a bug with the Event service where certain calls used int instead of long for tick values.
• Improvements and bug fixes for Godot Engine.

braincloud-unreal-plugin (Unreal)

• Improvements and bug fixes in WebSockets
• Updated CI to ensure stable builds and compatibility across engines and platforms
• More tools exposed for blueprints

braincloud-cpp (C++)

• Improved error logging for relay disconnect

braincloud-java (Java)

• Fixed SmartSwitch bug in BrainCloudWrapper.java

  • A callback containing authentication request was not being called
• Added Logout method to BrainCloudWrapper.java

braincloud-js (JavaScript)

• Added Logout function to brainCloudWrapper.js

S2S Libraries

All S2S libraries

• Added RTT / WebSocket support

brainclouds2s-unreal (Unreal)

• S2S Library repository is now usable as an Unreal plugin and can be added as a submodule to a project
• The S2S Unreal plugin depends on the BrainCloud Unreal plugin for utility functions
• Created a new repository for the S2S Unreal Unit Test project that demonstrates the use of the S2S library

brainclouds2s-cpp (C++)

• Added brainCloud namespace

Examples

All Examples

• All examples have been updated to showcase the use of the BrainCloudWrapper Logout() call.
• RelayTestApp Cursor and Shockwaves normalized to send percentage position that ranges from 0,0(for top left corner) to 1,1 (for bottom right corner) for reliability across devices and screen sizes.

examples-unity (C# Examples)

• The marketplace example now has support for iOS Push Notifications and App Store in-app purchases and subscriptions.
• BCChat example has been updated with a new UI and showcases a more automated process for handling channel connects, disconnects, and other Chat server calls.

• Relay Test App has additional features including:

  • 2 sets of Disconnect/Reconnect buttons have been added to demonstrate how to handle Relay disconnection (IE: From a network connection loss). But only for lobbies that have the right room configuration. Info on setting this up can be found in the README.md.
  • Lobby types are now filled in using Global Properties to display in the drop-down menu from the main menu. Info on setting this up can be found in the README.md.

examples-godot (Godot Examples)

• Added Script, Global Statistics, Player Statistics, XP, and Virtual Currency services to the demo

  • Run Cloud Code scripts
  • Increment statistics and experience points
  • Award/spend virtual currency

examples-javascript (JavaScript Examples)

• Added Team Mode to Relay Test App

  • Users can send shockwaves to everyone (both teams), opposing team members, or the same team members based on click type (left, middle, right)

• Added EndMatch and JoinMatch features to the Relay Test App

  • Users can “End Match” to return to a lobby with the same players rather than exiting the game completely
  • Users can “Join Match” from a lobby if other users have already started a match

examples-unreal (Unreal Examples)

• Updated to Unreal Engine 5.3 (tested in Unreal Engine 5.4)
• Retired 4.27 branch. A demo 4.27 app is available in the main branch.
• New minimal test app to quickly test developer blueprints or source code on devices and consoles.
• Improved Leaderboard project

• FPS Example includes features such as:

  • Friend System (Includes inviting people as friends, Joining friends that are in a lobby, and remove friend)   
  • Lobby System + Lobby Invite through Friends List
  • Relay Service Rooms with Ping data (Using First Person Shooter Template)
  • Chat System, one in Main Menu as the Global Message board and second in Lobby as Lobby Message board.
  • Create Custom Game (Includes changing lobby room name, time duration, region, and map selection)
  • RTT (Real Time Tech) callbacks to demonstrate how to utilize Presence (in friends list it shows who is online), Event system(handles friend request system), Chat system for global and lobby messages, and Lobby system.
• New BCChat project

Documentation and Tutorials

BootCamp Tutorials

• Additional Godot tutorials are now available!

Documentation

• All the latest API additions and changes have been incorporated into our new doc site at docs.braincloudservers.com !