brainCloud 4.12 is a targeted release to get Nintendo Switch Authentication support in place before our summer holidays!

Release Highlights

Nintendo Switch Authentication

brainCloud now supports native Nintendo Switch authentication.

There are now Nintendo variants of all the standard Authentication and Identity calls – see the API Changes section for more details.

Note that so far these calls have been added to the Unity Client library only. The Unreal Client libs will be added soon!

Miscellaneous changes

• Bridge-based DEBUG log messages are now free when not debugging!
  Calling the bridge.logDebug() and bridge.logDebugJson() calls have been heavily optimized to do nothing (when not called from the API Explorer or Script Editor) – so we no longer record API counts for these calls. Note that we do still count API counts for debug log calls made from the Logging service itself ← since those calls still go through our full Dispatcher and DispatchHandler systems. So don’t do that – use the bridge methods instead!
• GetUserItemsPage() performance has been improved
  The GetUserItemsPage() / GetUserItemsPageOffset() calls have been refactored to only refresh the items that are being returned by that page call… (instead of unnecessarily refreshing all items during the initial call).
• Improved RTT WebSocket Disconnect Handling in Unreal
  In addition to triggering on websocket disconnects, our Unreal libraries now also use a heartbeat timeout to detect disconnects (useful in platforms like IOS where the disconnect notification can take a while to arrive).
• Improved Country Code, Language Code, and TimeZoneOffset handling
  Both the Unity and Unreal client libraries have been enhanced to detect country code, language code, and timezone offset on more platforms (and we’ll be making more improvements in the future).

---

Portal Changes

We have made the following portal changes:

Design Section

• Core App Info | Platforms
  • Added Nintendo to the platforms list

Monitoring

• Global Monitoring | Custom Entities
  • Added sortable Updated At column to custom entity list screens
• User Monitoring | Select User
  • Added ability to search by Nintendo (Network Services Account) ID
• User Monitoring | User Summary
  • A user’s Nintendo ID will now be shown in the Credentials section of this screen
• User Monitoring | Custom Entities
  • Added sortable Updated At column to custom entity list screens

Reporting

• Analytics
  • Enhanced to show Nintendo platform players
    

---

API Changes

The following changes/additions have affected the brainCloud API:

• BrainCloudWrapper
  • Added AuthenticateNintendo() and SmartSwitchAuthenticateNintendo() calls
• Authentication Service
  • Added AuthenticateNintendo() call
• Identity Service
  • Added AttachNintendoIdentity(), DetachNintendoIdentity() and MergeNintendoIdentity() calls

---

Miscellaneous Changes / Fixes

• Updated libraries
  • 4.12 version of all client libs are available.
  • The Unity and Unreal libs in particular have significant features and improvements in this release – go grab ’em!
• Documentation updates
  • The latest APIs have been added to the API Reference.
• Important Fixes
  • BCLOUD-2298 – Runstate erroneously set to disabled when executing one of the import/export tasks
  • BCLOUD-2191 – Cache ItemDef collection in app cache
• Plus miscellaneous fixes and performance enhancements..

As you are probably aware – brainCloud’s pricing model is designed to be elastic – in that the cost to you (our customer) is proportional to the costs we incur in running your app(s) on our service.

This model is maintained via the formulas that we use to calculate API counts, deep data usage, hosting costs, etc. Keeping the model accurate requires periodic assessments to ensure that the components are balanced — and a review was long overdue!

Reviewing the data, here is what we found:

• Dormant account costs! The storage of dormant accounts (i.e. players who haven’t logged into an app for years) is an ever-increasing concern – affecting storage + backup costs, system performance, and deep data costs for all apps.
  Think about it: As an app enters the long-tail of it’s product lifecycle, the cost of hosting that app should go down – not up!
  
  
• RTT bulk message sends. When we first developed RTT, we expected much higher usage on a per-connection basis – and thus designed the usage formulas accordingly. It turns out that devs are finding that it’s very convenient to have an RTT connection available even in low-usage situations – which is great! – but ensuring proper cost coverage does necessitate an adjustment to the formula.
  
  
• Cloud code API imbalance. Calling brainCloud APIs from within cloud code scripts is more efficient than calling them directly from the client – and our API count formulas reflect that.
  Unfortunately, the existing formula has a design flaw that unintentionally encourages developers to artificially break their code into smaller and smaller scripts. This is both bad design and less efficient for brainCloud – so we are correcting this.
  
  
• Debug logging! Some apps have a surprising amount of debug logging in their scripts — which actually results in more system traffic than you’d think — which is why we charge for the calls — which results in higher costs for our customers.
  In brainCloud 4.12 we’ve optimized the handling of bridge-based DEBUG log message so that we no longer have to charge for them when you aren’t debugging (via the API Explorer / Script Editor).
  
  

The details of these changes (and when they take affect) are described below. How these changes affect your app depend upon the details of how your app is using brainCloud.

---

Impact to apps

Established apps with lots of custom entities will likely see their monthly bills significantly reduced as the Auto-Delete feature removes the abandoned accounts – greatly reducing their deep data usage. That’s provided that the devs enable Auto-delete of course.

Apps that choose to retain all (or a selected portion) of their dormant users will see a proportionate increase in monthly costs as we start to charge for Dormant Users.

Apps that don’t use a lot of scripts (and there are tons of them) won’t see much of a difference at all. Apps with scripts that make lots of API calls will see a modest increase due to the rebalancing – which may be somewhat offset by the DEBUG log savings.

We hope that folks understand that we make these changes with the best intentions of ensuring a better alignment between the costs that we incur and the costs to you – to ensure a healthy service for everyone!

---

Pricing changes

As of brainCloud 4.12 (targeted for release on July 20, 2022), we are introducing the following change:

1. We are eliminating the charge for bridge-based DEBUG log messages – when not actually debugging in the API Explorer or Script Editor.
   We have optimized the pipeline for DEBUG log messages called directly from the bridge service – so that these are now essentially no-ops, and thus we no longer need to charge for them. This is a significant cost reduction for some devs who like to leave the debug calls in place (and who wouldn’t?) – and a greater convenience for all devs – who no longer need to comment these calls out to reduce costs.
   

---

As of September 1, 2022, we are introducing the following changes:

1. We are re-balancing the # of free API calls that you get with every Cloud Code script call – from 3 -> 2 calls. Note that every call after the two free calls continues to cost 1/2 an API count.
   This corrects an imbalance from our original formula, that had the unintended side-effect of making some devs think that we were encouraging them to artificially break up their code into multiple smaller scripts. (Hint: We would never intentionally encourage devs to break up their code for reasons that don’t make sense from a design or runtime perspective!)
   
   
2. We are adjusting the ratio used to convert from bulk RTT message sends to API Counts from 1000:1 -> 100:1.
   This looks like a big change, but the message send traffic will still only adds up to a few dollars per month for even the most active apps on the platform. Still – it ensures we are covered should anybody choose to build the next Twitter on brainCloud!
   
   

---

Finally, as of January 1, 2023, we will be introducing billing for Dormant User Accounts.

brainCloud defines a Dormant User Account as any account where the user hasn’t logged in the app in the past 365 days.  These users add no value to your game (e.g. they’re probably anonymous and have already uninstalled your app!) – but they do significantly increase costs (including deep data usage) — and slow down your apps. Currently over 50% of brainCloud storage and backup costs is due to dormant accounts.

Starting January 1, 2023, brainCloud apps will be charged $75 / month per Million dormant users (pro-rated). That is not a lot – though for some apps it would be – but ideally we don’t want to collect any Dormant User revenues at all — we’re looking for the cost savings! That’s why we have our Auto-deletion service!

Auto-Deletion

The Auto-Deletion service (configured via the Design | Core App Info | Auto-Delete Users screen) is designed to keep dormant users from piling up.

We know deleting user accounts is scary – so we have made it very flexible – allowing you customize:

• which accounts get deleted <- you can define exclusions for users who have made purchases, attached an e-mail address, have virtual currencies greater than a certain balancer, etc.
• if (and when) users are notified – notify users in advance by email <- requires an attached Sendgrid account
• whether the accounts are archived for a period of time – you can optionally archive an export of a users data to a Custom Entity collection before deleting the account (just-in-case) <- requires a Plus plan

Note that depending upon the options you choose, there are some billing charges that apply as Auto-delete removes accounts:

• +1 Bulk API Count for each user deleted
• +1 Email Sent API Count for each email notification sent
• Plus deep data charges for temporarily archiving player data…

---

In summary

As always, our goal when designing our pricing models is to ensure that the pricing you are charged reflects the costs that we incur in providing the service.

We feel this approach aligns our interests. The more server resources your apps consume, the higher our costs, and the higher the price to you. But the more efficiently you can build your app, the lower our costs, and the lower the pricing for you. It’s win:win – and we are on the same side!

If you have any questions or feedback, please reach out to us via the Green Chat widget. We are always happy to hear from you!

brainCloud 4.11 has dropped. Here is what it contains.

Release Highlights

Redemption Code Enhancements

brainCloud 4.11 adds significant customization abilities to the Redemption Code service.

Developers can now write and configure scripts to programmatically handle the processing of redemption codes. These scripts can even incorporate asynchronous processing so that redemption processing can work with off-board fulfillment systems (i.e. delivery of virtual or physical goods via a 3rd party system).

brainCloud 4.11 also adds the ability to generate groups of redemption codes – in two code formats*:

• StructuredGuid – which is a standard GUID-format (i.e. “be0cc83f-024b-4dce-b50c-035ca51e99ae”)
• FiveByFive – which is a 5×5 alphanumeric code (i.e. “a1c2b-a82k3-d82h3-48sw7-8a82d”)

Note – Additional code types may be added in the future.

Simply choose the format of codes that you want – and the quantity – and an email will be sent to you with the generated set of codes.

With this – the following API calls have been added:

• GenerateCodes() – generates a set of codes, and emails them to the specified user
• GenerateCodesInline() – generates a set of codes, and returns them directly in the API call… (limited to max of 100 codes generated at a time)
• ProcessAsynchronousResponse() – used in asynchronous custom processing scripts to tell the Redemption Code service the updated status of the specified code.

Division Management API

brainCloud adds a new API for the creation and management of Divisions – accessible via S2S and cloud code.

The following new methods are available:

• SysCreateDivisionSetConfig()
• SysDeleteDivisionSetConfig()
• SysEditDivisionSetConfig()
• SysListDivisionSetConfigs()
• SysReadDivisionSetConfig()

Note that the JoinDivision() and SysGetLeaderboardConfig() calls have also been enhanced to return a new createdAt field (for division leaderboard instances only) that indicates the date+time that that particular division set instance was created. 

Relay Server Fixes / Improvements

We have improved the robustness of the relay server and added support for customizable timeouts.

The following timeout values are now supported:

• MEMBER_TIMEOUT – Number of seconds within which a member needs to initially join the game. They will be automatically dropped if they don’t join within this time. Default is 30 seconds.
• CONNECTION_TIMEOUT – Number of seconds a connection can be idle (i.e. no activity from the client) before the server drops it. Default is 10 seconds.
• RESEND_TIMEOUT – Number of seconds of resending the same packet before the player is dropped for “too many packet drops”. Default is 10 seconds.

Note – these improvements are only available for the v2 Relay Protocol servers.

Unity Client Improvements

We have made significant improvements to how the Unity Client processes timeouts and connection errors – especially in times of high server load. These improvements will be applied to the other client libraries in the coming months.

In addition, our latest libs address a WebSocket change in the 2021+ versions of Unity.

As always, for best performance, we encourage all developers to upgrade to the latest client libraries. So be sure to grab the 4.11 libs!

Unity Plug-in Changes

The Unity Plug-in has been enhanced to accept Builder API keys in the password field during login. This is to assist our private licensees who are transitioning to Single-Sign-On usage.

New Unity Authentication Example

We have totally re-written the Unity Authentication example – from OnGUI to Unity UI – to better illustrate how authentication works – including our recently added AuthenticateAdvanced() call.

We even have new docs and a video to go with it. Check it out! 

Additional Features

• Added new Ultra Blockchain Service for our Ultra.io partner
• Auto-Delete Users – we are finally introducing the Auto Deletion service that we teased way back in brainCloud 4.5.5! (Hey – we’ve been busy! 🙂 ) Anyway, this service allows your app to automatically delete users who haven’t logged in for a given period of time (e.g. 1 year) – with useful exceptions, like folks who have monetized, reached a certain level, etc. You can even choose to save a backup of a deleted user for X days. Deleting dormant users saves data and speeds up your app – and saves you $$$ as well!
• Backup Deleted Users for X days. If you enable the Auto-Delete feature (above), you also get the benefit of backing up deleted users for X days when they are deleted via the playerState.Delete() method as well.
• Improved caching of AppStore product items
• Updated Facebook Graph API to version 10 (technically introduced earlier in a 4.10 patch)
• Added missing DELETE (with query parm) APIs to HTTPClient…
• Added the missing SmartSwitch calls to the Java library.
• Added the missing SaveDataHelper calls to the Android C++ library.
• The format of individual User Exports have been updated:
  • new appId, profileId and time fields added to the top-level of the export for easy searching
  • gameId / appId and playerId / ownerId fields removed from sub-data components (redundant)
  • now excluding the following data: playerActivty, groups (we still export the list of groups the player was a member of, just not the data of the groups themselves), sentEvent, matchedOwned, matchHistory, playbackStreams and playbackStreamsTargetUser

Features for Private Licensees

The following features are of particular interest to customers who are licensing private instances of brainCloud:

• SSO status of Team Members now shown in the Super | Manage | Users and Team | Manage | Members pages.
• To better support private licensees moving to SSO, both the Unity Plug-in and our TeamAdmin APIs now support Builder API Keys as passwords. This behaviour is controlled by the new portalSSOTeamAdminAPI brainCloud property.

---

Portal Changes

We have made a few tweaks for 4.11… (though admittedly most of our web efforts are directed at Portal-X, the next-generation portal for brainCloud 5…)

Design

• Cloud Data | Custom Entities
  • Custom index Keys JSON is now properly pretty-printed
• Integrations | Blockchain
  • Added support for the Ultra Blockchain Service (for customers on our Ultra.io licensee’s platform)
• Marketplace | Redemption Codes
  • Redemption Code type screen updated to support linking in a custom Redemption Script for automating the redemption process.
  • Added a Generate Codes function to allow for easy generation of codes in several formats.

Monitoring

• Global Monitoring | Recent Errors
  • Added a Host Name field to error logs – convenient for tracking down certain errors
• Global Monitoring | Redemption Codes
  • Updated the Redemption Code monitoring screen to support the new asynchronous processing states.
• User Monitoring | User Summary
  • Updated the Select User search screen to support Ultra ID lookup

Reporting

• Reporting | API Errors
  • Fixed the error percentage calculations 
• Reporting | API Usage
  • Hosting Hours now only shows two digits after the decimal place

Team

• Manage | Members
  • A Team Members SSO status will be shown in private licensee deployments that support SSO.

Super (private licensees only)

• Manage | Users
  • A Team Member’s SSO status will be shown in private licensee deployments that support SSO.

---

API Changes

The following changes/additions have affected the brainCloud API:

• AppStore
  • VerifyPurchase() – we are now bubbling up more errors from the transactionResultCode up to the overall resultCode. (Basically, everything except for RESULT_FAILED_ALREADY_PROCESSED should bubble up). You still want to check the individual transaction details for receipts with multiple transactions, including ensuring that processedCount > 0. 
• BlockChain
  • Added methods to support minting NFTs (from Redemption Codes) on a Blockchain service. These methods are MintNFTFromRedemptionCode() , which of course starts the minting process, and GetTransaction() – which checks the status of a minting operation.
• CustomEntity
  • Reminder that we added UpdateEntityFieldsSharded() and SysUpdateEntityFieldsSharded() as a patch in 4.10. It is important to use these variants of the UpdateEntityFields() call if you plan to shard your Custom Entity collections <- which is recommended for large collections for best performance. (Ask a support tech to shard the collections for you!)
  • Also a reminder that GetEntityPage() and GetEntityPageOffset() have been enhanced to allow devs to specify whether they want the queries to accommodate entities not owned by the current player. There is a related compatibility flag that all apps should have set to disabled – unless you have a specific reason to enable it. More info here: https://getbraincloud.com/apidocs/custom-entity-getentitypage-improvement/
• HTTPClient
  • Added query string support to all relevant HTTP methods that were missing it – including PostMultipartResponseJson(), PostJsonOffboard(), PatchJsonResponseJson(), PatchTextResponseText(), Delete() and DeleteJsonResponseJson()
• Leaderboard
  • SysGetLeaderboardConfig() response now includes, for division set leaderboards only, a new createdAt field, which is the date+time in millis when the instance leaderboard was created.
• PlayerState
  • DeleteUser() call will save a backup copy of the deleted user – if player backups are configured on the Design | Core App Info | Auto-Delete Users screen
• RedemptionCode
  • Added the following new methods: GenerateCodes(), GenerateCodeInline() and ProcessAsynchronousResponse()
• Tournaments
  • Added new Division Management API calls – SysCreateDivisionSetConfig(), SysDeleteDivisionSetConfig(), SysEditDivisionSetConfig(), SysListDivisionSetConfigs(), SysReadDivisionSetConfigs()
  • JoinDivision() response now includes a createdAt field, which is the date+time in millis when the division set instance leaderboard was created
• User
  • The optionsJson parameter for SysGetUserExport() API now supports the ability to exclude specific custom entity collections

---

Miscellaneous Changes / Fixes

• Updated libraries
  • All libraries have been updated with the latest API enhancements. Go get ’em!
• Documentation updates
  • All new APIs have been added to the API Reference.
  • There’s a new document and video for the Unity Authentication Example.
• Important Fixes
  • BCLOUD-2091 – Unity Error re: Runtime of websocket-native.jslib not being defined
  • BCLOUD-1461 – Swart Switch calls are missing for Java
  • BCLOUD-1718 – Reset Univeral ID API sholdn’t throw a no session error
  • BCLOUD-1562 – Treat a blank queue guard setting as “any” rather than “stop”
  • BCLOUD-1631 – Return TLS_VERSION_INVALID for RTT connection attempts that don’t meet TLS version requirements
  • BCLOUD-1876 – Long-lived lobby instances are getting “stuck”
  • BCLOUD-2077 – Gamification – XP Levels: Min Points validation is broken/unenforced when editing and existing XP level
  • BCLOUD-1806 – Swapping between child/parent profiles in the Unlock dialog displays incorrect app name

• Plus miscellaneous fixes and performance enhancements…

Our DevOps team had to update brainCloud set of NAT gateways for brainCloud’s Public BaaS (i.e. portal.braincloudservers.com). This only affects developers who have whitelisted these IPs for security purposes.

The updated list of outgoing IPs is:

• 204.236.224.149
• 34.233.118.83
• 54.152.153.10
• 44.206.200.165

Apologies for the short notice and inconvenience.

The Challenge

Last week we became aware of a potential issue when using GetEntityPage() with owned entities.

The issue is related to how brainCloud handles ACL permissions. As you may or may not know, all entities in brainCloud support ACL permissions – and you can set the global accessibility of an object by setting the acl.other permission to one of the following:

• 0 = no access
• 1 = read-only access
• 2 = read + write access

In loose terms, any object with acl.other != 0 is shared with (or accessible by) all users of the app.

This has large implications when dealing with Owned Custom Entities and the GetEntityPage() call – because by the previous default – the call would look for all entities that meet the search criteria that:

• Are owned by the current user
• Are accessible by the current user

Owned is simple – we simply add “ownerId”: <profileId> to the query provided by the developer.

Accessible is not so simple – the database must look at all of the objects that the player doesn’t own, and specifically examine each objects ACL to see if acl.other != 0 !!! This is incredibly slow, and exponentially so! Especially since 99.9% of the time, a developer is only looking for the entities owned by the current user!

---

The Solution

To address this issue, we are changing to the default behaviour of `GetEntityPage() so that it no longer considers shared entities (by default) for Owned Custom Entities.

Thus, a query with the following criteria will now only return objects that are owned by the current user:

{
  "pagination": {
    "rowsPerPage": 50,
    "pageNumber": 1
  },
  "searchCriteria": {
    "data.position": "defense"
  },
  "sortCriteria": {
  }
}

Going forward, if an app wants to modify this default behaviour to include accessible (i.e. shared) objects that are owned by other users – they can add the new ownedOnly: false option. For example:

{
  "pagination": {
    "rowsPerPage": 50,
    "pageNumber": 1
  },
  "searchCriteria": {
    "data.position": "defense"
  },
  "sortCriteria": {
  },
  {
  "options": {
    "ownedOnly": false
  }
}

---

Compatibility Flag

Because this is a change to the previous brainCloud behaviour, we have introduced a new compatibility flag. When enabled, the following flag preserves the old functionality – where both objects owned and accessible by the user will be returned.

The new compatibility flag can be found in the Design | Core App Info | Advanced Settings page:

[ x ] Include shared objects in Owned Custom Entity GetEntityPage queries (warning: can be slow). Can be overwritten by specifying ‘ownedOnly’ in query context ‘options’.

When enabled, the default for ownedOnly is false – and when disabled, the default for ownedOnly is true.

---

We believe strongly that this new-and-improved GetEntityPage behaviour is the better + safer default – and thus highly recommend that all developers whose owned queries are only expecting objects owned by the current user go to this compatibility flag and immediately “uncheck” it to enable the new behaviour!

Remember – this option does not affect queries for Un-owned Custom Entities. It also does not affect Sys calls. So both of those scenarios will continue to return objects not owned by the current user – regardless of the compatibility setting.

If you have any questions – please reach out to the support team.

Cheers!

A quick reminder that usage of the following features have always required activation of a Plus Plan for live apps:

• RTT – used for Chat, Lobbies, Presence, etc
• Hosting – spinning up custom Room and Relay Servers
• Deep Data – used for Custom Entities and Messaging

In 4.9.5 (and earlier) there were scenarios where these restrictions were not being enforced.

We have addressed those scenarios in 4.10 – and as noted in the 4.10 release notes – we will enable the feature flag to begin properly enforcing these restrictions tomorrow – April 5th, 2022 – at approximately 9am Eastern.

Starting tomorrow, developers can expect that attempting to access these features (like enabling RTT, creating a custom entity, connecting to a chat channel, sending a message, etc.) without an active Plus Plan, will result in a run-time licensing error.

To quickly update your app to a plus plan, simply:

• Navigate to Team | Manage | Apps
• Select Change Plan from the action menu associated with the app
• Click on the Plus Plans tab
• Choose the plan to switch to
• And click [Choose Plan]

brainCloud will then swap your app to the new plan.

Note that your charges will be adjusted automatically, with the first few days of April charged to the old plan, and the rest of the month charged to the new plan – with the live fees pro-rated accordingly.

If you have questions or issues, feel free to reach out via the support widget.

brainCloud 4.10 adds new Security Options, an upgraded Cloud Code Engine, new Advanced Authentication calls, and more.

Release Highlights

TLS Security Enforcement

We are hardening the security of our Public BaaS environment to enforce TLS 1.2 for all APIs.

To facilitate a manageable transition – we have added an additional API endpoint to our public BaaS. So our public BaaS now supports:

• api.braincloudservers.com – our new API endpoint that supports TLS 1.2 only… (we will further upgrade it to support TLS 1.3 as well when AWS supports it)
• sharedprod.braincloudservers.com – this is our legacy endpoint that currently supports TLS 1.0, 1.1 and 1.2. This URL will be re-targeted to the same endpoint as api.braincloudservers.com starting June 7, 2022 ← approximately 90 days from now.

Note that other than the version of TLS enforced, these two endpoints function exactly the same. Your apps and players will not see any difference!

Our 4.10 client libraries have all been updated to use api.braincloudservers.com as the new default serverUrl for API calls. If you are using an older library, you can simply specify "https://api.braincloudservers.com/dispatcherv2" for the serverUrl parameter of the wrapper Initialize() call – see API Reference.

Once your app is calling the new endpoint, you can then go to the new Design | Core App Info | Security page, and set the minimum API TLS to 1.2. Careful though – this will mean that any calls to the older API endpoint (sharedprod.braincloudservers.com) will be rejected! ← because brainCloud cannot otherwise ensure that they were at least TLS 1.2.

Note that our RTT websocket endpoint is already enforcing a minimum TLS of 1.2. The raw TCP version of RTT however, which is used only for clients that cannot support WebSockets, is not encrypted. Setting Minimum RTT TLS Version to 1.2 thus disables the raw TCP connection option for your app. Note that both Unity and Unreal clients use the encrypted websocket implementation by default – so removing this option does not affect 99% of apps.

Migration options

In summary, brainCloud 4.10 allows developers to bump up the minimum level of TLS for client APIs. Developers have two options on how they would like to migrate:

1. Do nothing – If you do nothing, your app will automatically be upgraded to TLS 1.2 starting on June 7, 2022 when sharedprod.braincloudservers.com merges with api.braincloudservers.com and begins enforcing a minimum TLS of 1.2.
2. Migrate early – For developers wanting to improve their app security now, the new API and security settings provide the means to de-risk and accelerate the migration – which is definitely convenient for devs maybe going through Facebook’s Privacy Checklists for example. The recommended approach is:
   1. Reconfigure your app to talk to api.braincloudservers.com – either by updating to the 4.10 libs – or overriding the serverUrl parameter in wrapper Initialize().
   2. Confirm that your app works just fine
   3. Release the updated build of your app – so that you can get the majority of your player base migrated over
   4. Set the minimum client version of your app to force upgrades for any stragglers.
   5. Adjust the TLS settings of your app to require TLS 1.2. You are done!

Cloud Code Engine Upgrade

We have upgraded the Mozilla Rhino Engine from 1.7.13 → 1.7.14.

This brings with it support for the following Javascript features:

• Template Literals!
• Promise Support (Requires app to be set to ES6)
• Error stack traces!

And more!

For the full details, see the Rhino 1.7.14 Release Notes.

Advanced Authentication

Developers of certain categories of apps have long asked for the ability to register a new user, and set default attributes, etc. for that user during the initial Authentication call. This is not possible with the existing Authentication calls – so we have added a new set of calls to satisfy this use case. 

The new AuthenticateAdvanced() call allows the developer to include an extraJson payload with the authentication call, which can then be picked up by pre- or post- API hooks for additional processing as the account is created.

Note that for simplicity, all authentication types are handled by the single AuthenticateAdvanced() call – similar to how the API Explorer works… Corresponding Merge() and Detach() calls have been added to the Identity service as well.

Group and Group Entity Enhancements

We have done a full review of our Group and Group Entity code, and found some areas that warranted improvements. The following changes/fixes have been made:

• Improved handling of ACL permissions – In particular, some GroupEntity operations were being gated via the Group ACL instead of the Group Entity ACL! Note that there is a compatibility flag to preserve the old behaviour.
• Improved concurrency handling – we have improved the locking of several key methods – including managing group membership.
• Added missing Group “Sys” API call – Added Sys implementation for SysRemoveGroupMember()
• New SysGetRandomGroupsMatching() call – this is a more useful implementation of the GetRandomGroupsMatching() call – which is hampered by ACL permissions not allowing the API to return full details of groups that the user is not a member of. We would recommend that in most use cases, it is more correct to use SysGetRandomGroupsMatching() than GetRandomGroupsMatching() – though like all Sys calls, SysGetRandomGroupsMatching() is not available directly via the client API – so you’ll need to call it via a cloud code script.
• Updated ReadGroupMembers() and SysReadGroupMembers() calls to return a user’s summaryFriendData

Additional Features

• Unreal Relay communications – we have completely re-written Unreal relay communications for this release. In addition, we have created an Unreal-based Relay Tester app to demonstrate the usage of the relay server APIs.
• Improved credential checks – we have added improved versions of getProfileInfoForCredential() and getProfileInfoForExternalAuth() that don’t unnecessarily log an error if the credential isn’t found. This is handy for use cases where a credential not being found is normal – and isn’t worth flagging as an error in the logs. The new methods are:  getProfileInfoForCredentialIfExists() and getProfileInfoForExternalAuthIfExists()
• Faster file deployments – brainCloud will now copy multiple files in parallel during app deployments. This should have a noticeable reduction in deployment times for some apps.
• Ultra authentication – brainCloud APIs now support user authentication for apps on the Ultra.io platform. 
• Unity Chat – a new Unity Chat example app has been created. You can find the source for it here:
  https://github.com/getbraincloud/examples-unity/tree/develop/BC-Chat
• Unreal Relay Test – a new Unreal Relay Test example app has been created. You can find the source for it here:
  https://github.com/getbraincloud/examples-unreal/tree/master/RelayTestApp

Plus 4.9.5 Patch items

The following additions were technically included in 4.9.5 patches – but are described here for completeness:

• Illegal file types – Developers are no longer allowed to upload certain file types. Currently disallowed extensions are: html,htm,jsp,php,bat,cmd,exe,js,pif,ps1,scr,vb,vbe,vbs
• SysUpdateEntityFieldSharded() call – added new SysUpdateEntityFieldSharded() call for use with sharded Custom Entity Collections. This is because the existing SysUpdateEntityField() will not work for owned custom entities once sharded.
• Improved Room and Relay Servers – improved handling for long-lived lobbies with join-in-progress servers.
• Improved RTT connection handling – improved handling of RTT connection disconnects. 

---

Portal Changes

We have made the following portal changes:

Design 

• Core App Info | Advanced Settings
  • Added a new compatibility flag to preserve the old (and incorrect) GroupEntity / Group ACL behaviour. By default this flag is enabled for existing apps – but it is recommended that devs review their apps and clear this flag when possible.
• Core App Info | Security
  • This new screen allows devs to customize the security settings of their apps. For more information, see the TLS Security Enhancements section above.

Monitoring

• Global Monitoring | Custom Entities
  • Improved performance when showing all entities for a custom entity collection with tons of entities.
• Global Monitoring | Recent Errors
  • Fixed an issue that would cause logs to show the wrong relative date in certain timezone situations.

Reports

• Reporting | Analytics
  • The Dormant Users statistics table has been updated.
• Reporting | API Usage
  • Fixed an issue displaying usage stats for games with > 2.1 Billion game sessions.

General

• Unlocking apps – Unlocking a live app (via the Live Lock Banner) now requires the developer to type the name of the app, not the developer’s password. This is more in tune with the original design intent for the banner (which was to ensure the developer is aware of which particular version of their app (production, development, etc.) is being changed) – and interacts better with the PortalSSO integrations of private licensee’s brainCloud instances.

---

API Changes

The following changes/additions have affected the brainCloud API:

• Authentication
  • New AuthenticateAdvanced() call that allows extraJson payload to be included with player authentication / registration
  • New AuthenticateUltra() call allows apps to authenticate with the Ultra.io platform
• Custom Entity
  • New methods UpdateEntityFieldsSharded() and SysUpdateEntityFieldsSharded() are sharding-safe implementations of the older UpdateEntityFields() and SysUpdateEntityFields() methods. The non-sharded versions of these methods are now recommended only for custom entity collections that you know you will never want to shard in the future (i.e. small, probably static collections).
• Friend
  • The new getProfileInfoForCredentialIfExists() and getProfileInfoForExternalAuthIfExists() methods behave just like getProfileInfoForCredential() and getProfileInfoForExternalAuth() respectively – except that they don’t log errors if the credentials don’t exist. Handy and cleaner for many use cases.
• Group
  • New SysGetRandomGroupsMatching() call is a more convenient version of GetRandomGroupsMatching() – which eliminates the need to give read-only access to “other” users.
  • Added new S2S + cloud code only method: SysRemoveGroupMember()
  • Updated ReadGroupMembers() and SysReadGroupMembers() to return a user’s summaryFriendData
  • Improved concurrency handling
  • Improved handling of ACL permissions; behaviour changes are gated by a new compatibility flag.
• Group Entity
  • Improved concurrency handling
  • Improved handling of ACL permissions; behaviour changes are gated by a new compatibility flag..
• Identity
  • New cloud code only GetIdentityData() call allows apps to retrieve additional information regarding a specific player identity. Currently only supported for the new Ultra authentication.
  • New Advanced identity methods: AttachAdvancedIdentity(), DetachAdvancedIdentity(), MergeAdvancedIdentity()
  • New Ultra identity methods: AttachUltraIdentity(), DetachUltraIdentity(), MergeUltraIdentity()
• RTT
  • EnableRTT() now fails if the app’s plan does not support RTT. Note that this is a server-side check, and is not limited to the 4.10 client library.

We have attached warnings in the API docs to the following methods:

• Custom Entity
  • UpdateEntityFields() and SysUpdateEntityFields() – These methods are not sharding safe – and thus are not recommended for custom entities that you may want to shard for greater performance and scalability in the future. Consider using UpdateEntityFieldsSharded() and SysUpdateEntityFieldsSharded() instead.

---

Miscellaneous Changes / Fixes

• Updated libraries
  • All libraries have been updated with the new serverUrl and the latest APIs. Go get ’em!
• Documentation updates
  • API reference has been updated with the latest API changes.
• Important Fixes
  • [BCLOUD-1508] Fix for broken RTT disconnects
  • [BCLOUD-1508] Fix for broken RTT disconnects
  • [BCLOUD-1565] Dormant User Analytics changes: Users now only considered dormant if inactive > 365 days
  • [BCLOUD-1534] [Fixed] Can’t turn off Facebook Limited Login Friends once turned on
  • [BCLOUD-1530] [Fixed] Design Portal Error log entry displayed date is not accurate
  • [BCLOUD-1378] Add missing API Hooks for RedemptionCode service
  • [BCLOUD-266] [Fixed] RTT DISCONNECT message not passed to the user
  • [BCLOUD-35] [Fixed] Relay C++ UDP ping sent before CONNECT
  • [BCLOUD-1535] Add missing Sys Group API (SysRemoveGroupMember)
  • [BCLOUD-1525] ItemCatalog service missing some cloud code SYS calls
  • [BCLOUD-1298] [BuilderAPI] Fixed NPE when request does not contain a content-type
  • [BCLOUD-1531] Improved error message (and logic) for launching hosted servers when a region is not supported
  • [BCLOUD-1515] [Fixed] Apps with billing plans with RTT disabled should not be able to send chat messages or make rtt connections
  • [BCLOUD-1587] [Fixed] Group has two members having role of OWNER
  • [BCLOUD-1387] [Fixed] User Monitoring – Login as User should set user’s languageCode and countryCode on created PlayerSession
  • [BCLOUD-1394] Return Catalog Item Definition name and/or description in app’s default language if none for user’s language for User Item with metadata flagged true
  • [BCLOUD-1393] Added missing support for getRunningOrQueuedCloudScripts Sys API on ScriptS2SServiceProxy
  • [BCLOUD-1331] Group APIs for Group Entity should enforce Group Entity ACL, not Group ACL
  • [BCLOUD-1331] Speed up SysIncrementGroupEntityData and SysUpdateGroupEntityData calls by avoiding Group lookup (only required for the equivalent non-Sys calls)
  • [BCLOUD-1402] [Fixed] Messaging Sys APIs not allowing version -1 for any version

• Plus miscellaneous fixes and performance enhancements…

Background

On February 22nd and 23rd, we will be migrating brainCloud’s core database cluster from VM-hosted MongoDB instances to MongoDB’s Atlas service.

This is a live migration – intended to accomplish the migration of all app and player data – with minimal service interruption.

Player-visible Service Impacts

Depending upon the features your app uses, the following service impacts may be noticeable by your players:

• Lobbies and Hosted Servers delays – lobby processing and launching of hosted servers will experience some performance delays during the cut-over period. We hope to keep this period of reduced performance to ~10-20 minutes — between the hours of 05:00 and 07:00 Eastern on Feb 23, 2022.
• Delayed Push notifications – new push notification jobs started during the cut-over period may experience delays
• Scheduled Jobs – scheduled cloud code jobs may experience small delays during the initial cut-over period.
• Stale Segments – The nightly Segment Refresh job will not run the night of Feb 22, 2022. This could mean that a player that newly qualifies for a segment wouldn’t be considered part of it – for a segment targeted Push Notification run, for example. Note that an individual player’s segments will still refresh when they log in — so any Store pricing shown to players will still accurately reflect any applicable promotions.

Temporary Restrictions

For data integrity reasons, we cannot allow any changes to the database schema (i.e. new/removed collections or indexes) during the migration period – so certain brainCloud features will be disabled. We also need to disable (i.e. temporarily remove) all TTL (Time To Live) indexes — so certain objects will stick around past their normal expiry periods.

These restrictions translate to the following brainCloud limitations:

• For safety, we will also be disabling the ability to Deploy or Import/Export apps during the entire migration period.
• If creating a new app in brainCloud, the leaderboard collection for that app will not be created (until after the migration period)
• If introducing support for leaderboards in your app for the first time, posting scores will not be supported until after the migration
• TTL indexes for all core and custom collections (i.e. Custom Entities, Messages, etc.) will be removed. This means that some objects may stick around for up to one day later than they otherwise would
• Developers will not be able to create new Custom Entity collections.
• Developers will also not be able to create new Indexes on Custom Entity collections
• If Messaging is newly enabled for an app, messages cannot be sent until after the migration

Thus, the following screens in the Design Portal will be disabled during the migration period:

• Design | Core App Info | Admin
• Design | Cloud Data | Custom Entities

Also – to ease the amount of data changes to migrate, we will be disabling Segment Processing for the night of Feb 22nd only.

Detailed Schedule

The planned schedule for the migration is as follows. Interim times are intentionally conservative. If the migration is proceeding well, some steps will happen earlier than stated here.

• Feb 22 11:00 Eastern – Start migration prep
  • Notify developers (via banner) that migration is starting
  • Disable collection creation
  • Disable the Admin Tools and Custom Entities design screens
  • Disable Segment Processing
  • Prep the source database cluster (i.e. disable balancer and remove TTL indexes)
• Feb 22 13:00 Eastern – Start bulk migration
  • The background bulk copy processes will begin
• Feb 22 22:00 Eastern – Start sync
  • The bulk migration should be complete
  • The system now goes into sync mode – syncing oplog changes in realtime between the old and new clusters. Note that it will take several hours for the new clusters to catch up to the latest changes being applied to the old clusters
• Feb 23 04:00 Eastern – Validate data + indexes
  • Validate the results of the migration. May involve rebuilding key indexes
• Feb 23 06:00 Eastern – Start cut-over
  • Cut-over the brainCloud servers from the old database to the new database.
  • Certain background processes will be scaled down during the cut-over. This will delay the processing of certain background tasks, like scheduled jobs, push notifications, etc. Those jobs will be processed once the servers spin back up on the new cluster.
• Feb 23 09:00 – Finalize migration
  • Validate health of all processes
  • Disable sync process
  • Re-enable balancer and re-add TTL Indexes
• Feb 23 11:00 – Migration complete
  • Re-enable collection creation
  • Re-enable brainCloud screens
  • Re-enable Segment processing
  • Remove banner

---

FAQ (Frequenty Asked Questions)

Why is brainCloud moving to MongoDB Atlas?

Moving to Atlas will offload the low-level server and software maintenance responsibilities from brainCloud DevOps personnel. It means less work keeping the servers secure, up-to-date and running properly – but also means that performing common operations like software upgrades, vertical and horizontal scaleouts, etc. are all handled automatically.

There are also benefits to monitoring the performance of the database — and a recommendations engine that brainCloud is considering leveraging for future Custom Entity enhancements.

Will my players or developers notice any changes once the system is running on Atlas?

No.

Will my players or developers notice any changes during the migration to Atlas?

Potentially. See the Player Visible Service Impacts section above.

What if something goes massively wrong during migration?

If the migration appears compromised in any way, we will abort. The database will remain on the existing servers – and we will reschedule the migration for a future date.

As you are likely aware, a serious vulnerability has been discovered in Apache Log4J 2, a very popular logging library for Java services. This attack is informally referred to as log4shell, presumably due to the way it allows an attacker to make privileged JNDI calls via the logging of simple input data from an API or web form.

We are pleased to report that brainCloud’s Production Services are unaffected by this vulnerability – and that we have further patched our services to completely eliminate any future risk of attack.

More specifically:

• brainCloud’s API and Portal services do not use Log4J 2 – and are thus not affected by log4shell.
• Some secondary Datastream and RTT services do use Log4J 2 – but these services do not log raw input data in our Production configuration – and thus, once again – are not affected by log4shell.
• To completely eliminate any future risk of exposure, we have now patched all services that use Log4J 2 to version 2.16.0, which disables the compromisable functionality.

The security of your apps and user data is of utmost importance to us. Thank you for trusting your business to brainCloud!

brainCloud 4.9.5 is the last release of 2021, and targets a few key customer requests and performance and reliability improvements.

Release Highlights

Profanity Check Improvements

We have improved the built-in filtering of our WebPurify integration – so that devs can now choose to filter a user’s chat messages, and updates to their name, by their own language only (instead of against all configured languages).

You will find the new options:

• on the Design | Integration | Manage Integrations screen for the player name settings

• on the Design | Messaging | Chat screen for the chat message settings

Additional improvements

• Async Match improvements – Deleting a player will now automatically abandon any asynchronous matches that they have in progress
• Entity call improvements – added a new _serverTime field to the JSON responses of most get entity calls – as a convenience to client devs
• Friend service improvements – more reliable retrieval of friend data across multiple social platforms ← a failure to retrieve friends from one service will no longer abort retrieving from the remaining services.
• Leaderboard rotation improvements – Improvements to concurrency handling during Leaderboard rotations and Tournament processing
• Lobby matchmaking – improved matchmaking performance under heavy loads
• User batch processing – improved handling of larger data bundles during batch processing

---

Portal Changes

We’ve made the following portal improvements:

Design Section

• Integrations | Manage Integrations
  • WebPurify – Added new options for improved targeting of languages for name profanity checks
• Multiplayer | Chat
  • Added new options for improved targeting of languages during chat profanity checks
• General
  • Adjusted the line-height of several components used in some log screens to address issue with low-hanging font characters being cut off

---

API Changes

The following changes/additions have affected the brainCloud API:

• CustomEntity service
  • Added a _serverTime field to the ReadEntity(), ReadSingleton(), SysReadEntity(), GetEntityPage(), GetEntityPageOffset(), and GetRandomEntitiesMatching() responses
• [User] Entity service
  • Added a _serverTime field to the GetEntitiesByType(), GetEntity(), GetList(), GetPage(), GetPageOffset(), GetSharedEntitiesForProfileId(), GetSharedEntitiesListForProfileId(), GetSharedEntityForProfileId(), GetSingleton() responses
• GlobalEntity service
  • Added a _serverTime field to the GetList(), GetListByIndexedId(), GetPage(), GetPageOffset(), GetRandomEntitiesMatching(), GetSystemEntityList(), GetSystemEntityPage(), GetSystemEntityPageOffset(), ReadEntity(), ReadSystemEntity() responses
• Group service
  • Added a _serverTime field to the ReadGroupEntitiesPage(), ReadGroupEntitiesPageByOffset(), ReadGroupEntity(), SysReadGroupEntitiesPage(), SysReadGroupEntitiesPageByOffset(), SysReadGroupEntity() responses

---

Miscellaneous Changes / Fixes

• Updated libraries
  • There are no new client APIs in this release.
  • There have been several client lib patches over the past month though – so be sure that you are using the latest!
• Plus miscellaneous fixes and performance enhancements…