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 !