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…
brainCloud 4.9 is a massive update with a hat-trick of new Multiplayer / Hosting Features – plus Unity Compression and some highly requested Marketplace and Management APIs. We hope you like it!
Warning
This release features an update to path handling for the bridge.callScript() method to ensure that called script paths are treated as relative to the calling scripts paths. This aligns with the path handling of the bridge.include() import mechanism – and makes for more maintainable and portal script modules. See Updated Script Path Handling for more information.
Release Highlights
Amazon GameLift Support!
We are pleased to announce that brainCloud now supports Amazon GameLift.
This means that you can enjoy all the benefits of brainCloud multiplayer – with our online matchmaking and lobby services – but with the flexibility of running and hosting your own server fleets in GameLift.
This is especially helpful in scenarios where:
You already have game servers running in GameLift
Your game needs the performance boost provided by GameLift’s non-containerized architecture
You want to lower costs with GameLift’s ability to utilize AWS Spot Instances
The best part is that once you configure it – there are almost no changes to your client code. The only difference is that the connectData information returned to the client will specify a protocol type of gamelift.
JSON
Information
Note that GameLift hosting is priced differently than standard brainCloud hosting. brainCloud will charge the equivalent of 5 API Calls per player added to your GameLift servers.
This is independent of the costs that Amazon will charge you directly, of course.
Join in progress!
Speaking of brainCloud lobbies and matchmaking – brainCloud 4.9 adds support for backfilling of matches – which means that new/replacement players can finally be added to matches in progress!
Note that the room server should use the SysGetLobbyMember() call to validate the legitimacy of any players attempting to join the Room Server after the match starts.
Retrieve List of Lobbies
To complete our multiplayer hat-trick, developers can now query the list of active lobbies in a game. This is useful for games providing a more classic multiplayer experience.
Simply pair the new GetLobbyInstances() and GetLobbyInstancesWithPingData() calls with the existing GetLobbyData() and JoinLobby() calls to implement your own old-school lobby system!
AppStore Item Purchases
At long last, Marketplace Products can now include Inventory Items. This means users will be able to acquire your game’s “Magic Wand of Silly Walks” directly through an in-app purchase!
Unity Client Compression
The Unity Client now officially supports compressing of client ↔︎ server messages.
Sending large API requests/responses takes time – especially under mobile conditions. With a pair of flags, you can enable compression for faster processing of brainCloud requests. This can also reduce the occurrence of network timeouts that can happen when sending/receiving larger requests.
brainCloud’s compression support is intelligent – and only kicks in if the message bundle to be transmitted is greater than a size threshold – which defaults to 50Kb. Any messages sent/received above that threshold will be compressed (and uncompressed) automatically and transparently to your app.
Note that compression is disabled in the 4.9 Unity Client by default.
To enable compression of both requests and responses, call:
C#
Updated Script Path Handling
We have updated brainCloud’s handling of paths for the bridge.callScript() method to make it more consistent with industry standards (and our own bridge.include() method).
Before this change, if brainCloud were running script /subFolder/myScript.ccjs – the following two calls would look for their files in different directories:
bridge.include("myImportFile.ccjs") ← would look for myImportFile.ccsj in the current directory of the calling script – i.e. “/subFolder” ✅
bridge.callScript("myUtilityScript.ccjs", {}) <- would look for myUtilityScript.ccjs in the root! ❌
With this change, the two calls use the same algorithm to determine the referenced script.
As you would expect, we have introduced a new compatibility flag that controls this improved behavior. The new [x]Use legacy script path handling flag, if enabled, preserves the old functionality. This flag is enabled by default for all existing apps, and disabled by default for newly created apps.
Information
Important – this change does not affect the functioning of ScriptServiceProxy.runScript(). As that method mimics the Client API call – it always assumes that it is running from the root. We highly recommend that devs use bridge.callScript() instead of ScriptServiceProxy.runScript() from within scripts.
Tournament Management APIs
We have expanded our Sys APIs to support Tournament Management.
This includes new cloud-code only APIs for:
Managing Tournament Templates
Enabling Tournaments for a Leaderboard Config
Editing Tournament details for current and future periods
In addition, we have added new methods for more efficiently retrieving the list of leaderboards, and retrieving leaderboard details. See the API Changes section for more details.
Additional Improvements
This release also includes the following:
$text query support
the query syntax for Custom Entities has been extended to support MongoDB $text queries.
Improved RTT connection id handling
The Relay Server Protocol protocol (and the Relay Server and Client Libraries that implement it) have been enhanced for more consistent usage of RTT connection IDs – basically, the protocol now uses profileIdCx ids instead of just profileId
There is a new compatibility flag, [x] Include legacy lobby owner field in API output, that when enabled ensures that this new behavior still works with old clients. This flag is enabled by default for all existing apps, and disabled for newly created apps.
Additions / Improvements to the Builder API
Support for API Hook management
Support for basic Team Member management
Improvements to Async Match APIs
We are now returning handy summaryFriendData for players in more of the AsyncMatch calls – including FindMatches(), FindCompleteMatches() and ReadMatch()
Additional HTTP Client methods
Support for HTTP PATCH, DELETE, and HEAD commands
External Authentication enhancements
Ability to return additional information with authentication results
For more info – see the new authPayload and extraErrorJson fields documents in the API Docs.
Portal Changes
Design
Core App Info | Advanced Settings
Added new compatibility flag: [x] Include legacy lobby owner field in API output. Enabled for existing apps by default. See Improved RTT Connection ID handling for more information.
Added new compatibility flag: [x] Use legacy script path handling. Enabled for existing apps by default. See Updated Script Path Handling for more information.
Cloud Code | My Servers
The new GameLift Room Server option has been added.
Cloud Code | Scripts
When dealing with live apps, the Script Editor will no longer allow portal users to start editing a script before unlocking the app — instead of just refusing to save the changes! A small but useful improvement!
Custom Config | Legacy Files
The old Files page has been fittingly renamed to Legacy Files.
Integrations | Manage Integrations
A new AWS GameLift Integration section has been added.
Leaderboards | Leaderboard Configs
We have added a search box for filtering the list of leaderboards. Super useful for those apps with tons of leaderboards!
Marketplace | Products
Added the ability to add Items as reward items for in-app purchase products.
Multiplayer | Lobbies
Added new options to the Rules page for lobbies:
Disband on start (default) – lobbies will be terminated when the game starts. This flag is enabled by default for existing apps.
Allow join in progress – allows players to join games that are already in progress (i.e. backfilling)
Team
Manage | Apps
We’ve added an app’s appId (in parenthesis) to the list for easy reference
We’ve also added a new Last Updated field – so it is easier to see which apps have been edited recently. Note that we have also updated how some of our nightly processes work with the updatedAt field of the game record – so that going forward, apps are not considered to be “updated” when our back-end billing processes run.
API Changes
The following changes/additions have affected the brainCloud API:
AsyncMatch Service
We have added user summary data to the results returned by CreateMatch(), SubmitTurn(), FindMatches(), FindCompleteMatches(), ReadMatch() and UpdateMatchSummaryData().
Client Service (Unity Only)
Call the new EnableCompressedRequests()and EnableCompressedResponses() methods to enable compression.
Global App Service
New ReadSelectedProperties() and ReadPropertiesInCategories() methods allow the app to retrieve a subset of the app’s global properties instead of all of them.
We have also added new S2S and cloud-code only methods for creating properties: SysCreatePropertyString() and SysCreatePropertyJson()
Group Service
New cloud-code only SysIsGroupMember() call for testing group membership.
HTTPClient
Added support for HTTP PATCH: PatchJsonResponseJson() and PatchTextResponseText()
Added support for HTTP DELETE: DeleteJsonResponseJson() and Delete()
Added support for HTTP HEAD: HeadRequest()
Leaderboard Service
New PostScoreToDynamicGroupLeaderboardDaysUTC() call allows for the dynamic creation of group leaderboards with a DAYS rotation.
New SysCreateLeaderboardConfig() and SysEditLeaderboardConfig() methods are updated versions of the older SysCreateLeaderboard() and SysEditLeaderboard() methods – with the ability to edit tournament settings. The old methods continue to be available (they are not deprecated).
New SysListLeaderboardConfigs() and SysGetLeaderboardConfig() methods for more efficient retrieval of summary information vs. leaderboard details, respectively.
New APIs for editing tournament period settings on leaderboards: SysEditTournamentSettingsForFuturePeriodsOnly() and SysEditTournamentSettingsIncludingCurrentPeriod(). Note that you would usually only edit future periods – because you don’t want to change the rules of a tournament that is already underway – that seems unfair!
New APIs for editing adhoc tournament periods – SysCreateAdhocTournamentPeriod(), SysEditAdhocTournamentPeriod(), and SysDeleteAdhocTournamentPeriod()
Lobby Service
Added new GetLobbyInstances() and GetLobbyInstancesWithPingData() calls to return the list of available lobbies. Pair with the existing GetLobbyData() and JoinLobby() calls to implement your own old-school lobby system!
Tournament Service
New management calls – SysListTournamentTemplates(), SysCreateTournamentTemplate(), SysEditTournamentTemplate(), SysReadTournamentTemplate() and SysDeleteTournamentTemplate().
User Service
A number of Sys methods that were missing from the S2S proxy have been added
Miscellaneous Changes / Fixes
Updated libraries
All libraries have been updated with the latest API changes. Go get ’em!
Documentation updates
All of the new API calls have been added to the API Reference
Important Fixes
BCLOUD-792 – JS S2S Heartbeat doesn’t work – fixed.
BCLOUD-799 – User Batch Script processing issue with PlayerSession API version causing Leaderboard API errors
BCLOUD-945 – REDIS lag causes issues when scripts are moved between folders
BCLOUD-980 – Scripts in the root folder are not being cleared when restored to checkpoint
BCLOUD-981 – Add protection for PlayerStatistics experience points from going negative
BCLOUD-982 – Add more input validation for Tournament rewards input for GlobalGameStatistics and/or PlayerStatistics stat names
BCLOUD-998 – Add support for $text operator text query document fields
BCLOUD-1057 – Locks with no player session context not unlocking properly
Plus miscellaneous fixes and performance enhancements…
GameSparks developers will find that the brainCloud feature set and technology platform align well with what they are already used to.
Major advantages of migrating to brainCloud include:
Cloud code – brainCloud’s cloud code system utilized JavaScript, is based on Mozilla Rhino, uses JSON parameters, and allows synchronous access to the full brainCloud API.
Cloud data – brainCloud uses NoSQL MongoDB for persistent data storage.
Chat & Messaging – brainCloud’s RTT (Real-time Tech) service provides support for Chat (both Global and Group channels) and player-to-player Messaging
Downloadables – brainCloud supports Downloadables and Uploadables, with built-in CloudFront CDN support
Email – brainCloud provides a SendGrid integration for email
Leaderboards – brainCloud rich leaderboard system directly supports everything but leaderboards partitions – and partitions can be emulated via separate, dynamically created leaderboards.
Multiplayer – brainCloud provides support for hosted Room and Relay Servers, and beginning in 4.9 supports Amazon GameLift as well!
Teams – brainCloud’s Group service provides support for teams – including team chat and leaderboards
Virtual Currencies and Virtual Goods – brainCloud supports them both, along with purchasing both from the AppStores.
And much, much more!
This document provides instructions and tips for migrating your app from GameSparks to brainCloud.
Click on the collapsable table-of-contents to jump to a section.
brainCloud supports standard achievement functionality: short name (id), title, description, and platform-specific achievement IDs. Devs can also attach a collection of key+value pairs for additional metadata.
In brainCloud, Achievements are cosmetic – they do not deliver additional rewards (such as Virtual Currencies, Player XP, User Statistics, Virtual Goods, etc.).
brainCloud does provide a Milestone system, however, that can be used to trigger such awards – including Achievements themselves. Milestones are configured to watch User Statistics and trigger automatically when specified thresholds are exceeded. Milestones can award Achievements, Virtual Currencies, Player XP, User Statistics, and Global Statistics.
Milestones do not currently award Product Items; that feature is coming in an upcoming release. This functionality can however be easily achievedwith custom code by attaching the product item id to the Achievement’s metadata.
brainCloud does not have Leaderboard Triggers – but you can attach a custom Cloud Code script to any API Call via the API Hooks feature. So for example, a PostSuccess API Hook on the PostScoreToLeaderboard() call can achieve a similar result.
Authentication Basics
brainCloud supports a rich set of authentication types (also called Identity Types).
The equivalent of GameSpark’s Device Authentication is brainCloud’s Anonymous ID. This is a generated GUID that is stored on the player’s device.
Authenticating anonymously is as simple as calling the brainCloud Wrapper’s AuthenticateAnonymous() call.
bool forceCreate = true; // Creates the account if it doesn't already exist
SuccessCallback successCallback = (response, cbObject) =>
{
// Continue with launching the app
// ...
};
FailureCallback failureCallback = (status, code, error, cbObject) =>
{
// An error occurred
// Pop up a dialog for the user to retry?
};
_bc.AuthenticationService.AuthenticateAnonymous(forceCreate, successCallback, failureCallback);
Registration
brainCloud also supports both Univeral Identity (username + password) and Email Identity (email address + password) authentication.
To register their account, the app simply attaches the desired identity type to the player’s account. For example, the following code attaches a Universal Identity to the account.
Once a higher form of identity has been attached to the account, the app can login using that identity via the appropriate authentication calls. For example, to login via the Universal Identity:
brainCloud supports Sign in With Apple, Facebook Login, Google Play, Google OpenId, Oculus, and more.
From a code perspective, all work basically the same:
The app uses the appropriate Platform / 3rd Party SDK to authentication the user
The app then passes the authentication information returned from the SDK to brainCloud (via the appropriate authentication mechanism
brainCloud validates the authentication is legit – and then looks up the user’s account and/or creates a new account as directed (according to the “forceCreateoption)
brainCloud supports both Chat and Messaging as part of its RTT (Real-time Tech) offering. RTT enhances brainCloud’s standard request+response API with an additional WebSocket connection to the server for bi-directional real-time communications.
Chat
In brainCloud, Chat messages are directed to channels, not users. Channels have an ID and a rolling history. Active listeners of a channel are notified in real-time when new messages are posted.
brainCloud supports Global, Group (i.e. Clans or Teams) and Dynamic Channels. brainCloud also supports Lobby Chat – though technically that is achieved through a separate, lobby event API.
To participate in Chat or Messaging, the client app must first enable RTT:
Note that brainCloud chat supports both simple text and rich JSON payloads – and integrates with WebPurify for profanity filtering.
Messaging
In brainCloud, Messaging messages differ from Chat messages in that they are directed at players, not channels. Messaging can be thought of as a simple local email system for your app.
Each player has an inbox and an outbox.
Note – because Messaging is RTT-enabled, online players will be alerted in real-time (via a callback) when a new Message arrives.
brainCloud Messaging supports both simple text messages and complex JSON payloads. The following method delivers a simple text message to the players at the specified profileIds.
brainCloud’s Cloud Code system is very similar to the model employed by GameSparks:
In brainCloud:
Cloud code Scripts are written in JavaScript, and run upon an embedded Rhino engine
Scripts can include other scripts and call other scripts.
Scripts are passed JSON parameters when they are called
Scripts have access to the full brainCloud API – including the ability to Get/Set Player Data (like player statistics, attributes, User Entities, Owned Custom Entities, etc.) and Get Static Game Data – MetaCollections (like Global Properties, Global Entities, Un-owned Custom Entities, etc.)
API calls made from Cloud Code Scripts run synchronously for simplicity!
Scripts have access to the brainCloud HttpClient service – which can be used to Send HTTP requests to external services
Scripts can be registered to be called from webhooks – which are useful for Receiving HTTP Requests from external services. (Note – brainCloud also supports a custom S2S API for more flexibility)
brainCloud supports User Batch Jobs – so you can trigger a script to be run on a select batch of users (or all users).
brainCloud supports Scheduling scripts to be run in the future. Although there isn’t the concept of “run every hour” or “run every day” – it is very simple to have a script reschedule itself to achieve the same result.
brainCloud scripts can be attached to API calls via API Hooks. API Hooks can be configured to run custom scripts before and/or after the API call. This can be useful for modifying a game’s behavior without the need to redeploy a new client.
brainCloud Data
brainCloud offers a rich set of data APIs for storing player and game data. An overview of the different data APIs can be found here – as well as a discussion of the benefits of Custom Entities vs. the older User and Global Entity mechanisms here.
MetaCollections
Developers should use brainCloud’s Unowned Custom Entities in place of MetaCollections. Custom Entities are JSON objects with a rich API for storage and retrieval. For more information, see the Custom Entity API reference.
System-Scripts
brainCloud provides a mechanism called API Hooks that allows you to attach custom scripts to API Calls and other events in brainCloud.
API Hooks can be configured as either Pre- or Post- hooks – meaning that they will run either before or after the API calls they are enhancing.
Post-hooks are useful for cases where you want to enhance the results of an API call with additional data – for example, attaching the user’s campaign state to the Authenticate call results.
Pre-hooks can be used to add additional checks to allow/disallow API calls – and alternatively re-route the calls themselves. They are an easy way to re-route cheaters to alternate leaderboards, for example.
Bulk-Jobs
brainCloud offers a Batch User Script feature for scheduling a script to be run all or a subset of users.
Like GameSparks, the workload is spread across all players and executed as background jobs to not impact server performance. brainCloud also offers the ability to trigger a completion script when all users have been processed.
brainCloud offers APIs for scheduling a script to run at a specified time in the future. Although not the same as the every-hour, every-day scripts supported by GameSparks – the same sort of functionality can be achieved by having the script re-schedule itself to run again. An example of such a script can be found in brainCloud’s Cloud Code Central repository.
Transitioning MetaCollections
The brainCloud Portal offers the ability to import data from JSON files – this is supported for both Custom Entities and Global Entities. This is suitable when important static reference data – like level data, tuning files, etc.
Information
The allowed size of import files is limited – if you receive an error during the import, message our support and we may be able to adjust the limit for you.
Note that brainCloud also supports an S2S API, which may be helpful if you need a more custom approach for migrating your app’s reference data.
GameSparks API Wrappers
If you decide to create wrappers for GameSparks key APIs, you can easily include them in your scripts using the bridge.include() operation.
Using this approach may allow you to better take advantage of the similarities between the brainCloud and GameSparks cloud code systems.
Asynchronous APIs
Happily, brainCloud cloud code scripts use synchronous calls, just like GameSparks.
Performance Bottlenecks
The brainCloud Cloud Code Editor and API Usage pages can help you to find performance bottlenecks:
The Cloud Code Editor returns the execution time for each test run of your script. It also returns information on what API calls we made by the script – to help better understand where time may have been spent
The Reports | API Usage page displays the average execution times of each of your API calls, including cloud code scripts. Any commonly called scripts taking longer than 200ms should be examined for possible optimizations.
Data Transition Guide
Reference data
The brainCloud Portal offers the ability to import data from JSON files – this is supported for both Custom Entities and Global Entities.
This is suitable when importing static reference data – like level data, tuning files, etc.
Information
The allowed size of import files is limited – if you receive an error during the import, message our support and we may be able to adjust the limit for you.
Note that brainCloud also supports an S2S API, which may be helpful if you need a more custom approach for migrating your app’s reference data.
User accounts
For dynamic user data, it is highly recommended that new users be migrated over during initial login to brainCloud.
This has a number of benefits:
Simpler – Importing a single user is simpler than importing all of them
Scalable – It spreads the work of importing out, creating less load on both brainCloud and GameSparks
Efficient – it ensures that only active player data is migrated over to brainCloud. If your game is more than two years old, it’s likely that less than 25% of your stored player accounts are still active.
The recommended approach is to leverage the following brainCloud features:
External Authentication – which allows brainCloud users to be authenticated via an external source – like your Gamesparks app
API Post-Hook – which can be used after successful authentication, to trigger a script to retrieve the user’s GameSparks data
HTTPClient service – used to make HTTP calls to external services (i.e. GameSparks)
More information on this sort of approach can be found in this article.
Downloadables
brainCloud supports a Global Files service that allows developers to upload files to be downloaded by client apps. These files are automatically distributed to AWS CloudFront CDN for fast downloads.
Uploading of files to brainCloud is normally done via the Design Portal. It is also possible to upload a file as a User File via a Client Library, and then convert it to a Global File via an API Call.
(We will be adding the ability to upload Global Files directly in a future version of our APIs.)
Emails (SendGrid)
brainCloud provides a SendGrid integration for sending emails.
To utilize brainCloud’s SendGrid functionality, simply:
Configure the SendGrid settings on the Design | Integrations | Manage Integrations page, SendGrid section of the design portal
Modify your scripts and/or client to use brainCloud’s Mail service APIs
Optionally customize the system templates to be used for password resets and such on the Design | Authentication | Email Authentication page.
Leaderboard Basics
brainCloud provides a rich leaderboard system – with support for both player and group leaderboards, scoring types, rotation types, supplemental data, history, etc.
Leaderboards are normally pre-defined in the Portal on the Design | Leaderboards | Leaderboard Configs page. Leaderboards can also be dynamically created using the PostScoreToDynamicLeaderboardUTC() call.
Leaderboard scores can be viewed on the Monitoring | Global Monitoring | Leaderboards page of the Portal.
brainCloud of provides a rich API for returning leaderboard results, including social and global leaderboard results – as well as an advanced API for retrieving high scores across multiple leaderboards for social maps.
A player’s own score can be retrieved via the GetPlayerScore() api.
Advice
Pro-tip: To retrieve a player’s rank as well as score, use the GetGlobalLeaderboardView() call, specifying 0 for the beforeCount and afterCount.
Leaderboard Partitions
brainCloud does not support Partitioned Leaderboards – but something similar can be achieved using multiple leaderboards.
To keep setup as simple as possible, we would recommend that the additional partitions (for example, country-specific versions of the leaderboard) be created programmatically with a descriptive suffix (i.e. “_<countrycode>”. This can be done via a simple cloud code script and/or cloud code hook.
Leaderboard Resetting
brainCloud directly supports the following automatic rotation types:
NEVER – the leaderboard never resets
DAILY – the leaderboard resets daily
DAYS – the leaderboard resets after <x> days
WEEKLY – the leaderboard resets weekly
MONTHLY – the leaderboard resets monthly
YEARLY – the leaderboard resets yearly
brainCloud leaderboards also have a “retained count” – that determines how many old copies of the leaderboard are retained before deletion. This can be useful for rewarding players for their performance in the previous rotation.
Note that developers can also directly control rotation by configuring a NEVER leaderboard and resetting it manually via the SysResetNeverLeaderboard() call.
Manage Screens
brainCloud has a feature-rich Design Portal that provides access to game, group, and player data – including entities, statistics, leaderboards, etc. All of this data is viewable and editable by development and support personnel (given appropriate permissions).
The data is all accessible via the Monitoring portion of the portal. Monitoring is broken into the following sub-sections:
Global Monitoring – for viewing/editing global data – like global/custom entities, leaderboards, global statistics, job queues, and more
Group Monitoring – for viewing/editing of groups and group data
User Monitoring – for viewing/editing of users and their data
brainCloud also provides an S2S API that can be used to implement a custom management tool that manages your brainCloud-based apps.
More information on the S2S API can be found here.
Matchmaking
brainCloud provides two different matchmaking systems.
The MatchMaking service is primarily for use by games that are using brainCloud’s Async Match and One-way Match APIs. Games of these types are often played offline – and thus this matchmaking service only selects offline players.
Online games should use the brainCloud Lobby service for matchmaking. Lobby Matchmaking identifies groups of suitable players for online play.
Lobby Matchmaking is highly configurable, with support for:
skill level matching
min / max players (by team)
geo matching <- prioritizing players that are close together
filter scripts
For more information, see the brainCloud Lobby service.
Player Manager
Player Management is accomplished via the Monitoring | User Monitoring section of the portal. Subsections for viewing and editing player data include:
User Summary – a summary of the user’s info, including name, xp, identities, currency balances, etc.
Achievements – displays the user’s achievement status
Attributes – displays any attributes attached to the user. Supported creating and editing of attributes
Custom Entities – allows for view/edit of a user’s owned Custom Entities
Friends – view the player’s friends (both 3rd party and locally managed)
Groups – view the Groups the user is a member of
Inventory – view the items owned by the player
Milestones & Quests – view the user’s completion status for milestones and quests
One-way MP – view the status of recent one-way multiplayer matches
Pricing – view the store prices for this player – including any promotions that may be being applied
Statistics – view/edit the user’s statistics
Transactions – view any purchases the player may have made
Turn-by-Turn MP – view any async match games currently in progress
User Entities – view/edit the player’s User Entities
User Files – view the files that this user has uploaded
Virtual Currency – view/edit the user’s current balances
Logs – logs of the user’s recent interactions with the brainCloud API <- super useful for debugging!
brainCloud also offers an S2S API that can be useful for building custom management tools.
Scheduled Events
brainCloud offers a Scheduled Promotions feature that can be used to configure sale prices for all users and/or specific segments of users.
The list of active promotions can also be queried via the RefreshPromotions() call – and could be used by the client to configure additional custom functionality.
Teams
brainCloud’s term for Team is Group.
Groups are designed as follows:
Groups consist of a collection of members (users)
Groups have a name, a type, an id, and custom data
Members are each assigned a role-based permission level: “OWNER”, “ADMIN”, or “MEMBER”
Groups have one (and only one) “OWNER”. The OWNER of a group can add/remove members, and delete the group
Groups can have multiple “ADMIN”s. ADMINs are like OWNERs, except that they cannot delete the group.
Any “MEMBER” can edit group data
MEMBERs of a group can have custom attributes associated with them (can be used for custom application roles, etc.)
Users can be members of more than one group
Users can be the owner of more than one group
Groups can also have associated Entities (i.e. GroupEntity)
Team Chat & Notifications
brainCloud supports text-based Team Chat via RTT’s Chat Service. The Chat service supports special “group channels” for communications between the members of a group.
brainCloud also supports sending push notifications to the members of a group via the SendRawPushNotificationToGroup() call.
Team Leaderboards
brainCloud supports group leaderboards – which are leaderboards where the group entries, instead of player entries.
brainCloud also supports group social leaderboard calls – where the results of the player leaderboard call are filtered to just the members of the specified group.
Team Data
brainCloud supports two forms of team data:
Group Data – which is custom JSON attached to a group
Group Entities – which are JSON entity objects owned by a group
brainCloud provides a VirtualCurrency service for managing a player’s currency balances. Developers can define as many currencies as they like – and these currencies can be automatically awarded from XP level-ups, Milestones, Quests, and Tournaments — and of course, be purchased via in-app purchase Products.
To configure a sign-up bonus for players, simply add the desired currency amount as a reward for the initial XP level. Note that this technique works even if your game doesn’t otherwise use the brainCloud XP system.
Virtual Goods Basics
brainCloud provides support for virtual goods via:
ItemCatalog service – which defines the set of items (i.e. virtual goods) that are available for purchase by the user
UserItems service – which manages the player’s inventory of said items, including purchases and trading
Standard item properties include: id, name (localizable), category (user-defined), description (localizable), resource ids, pricing (in virtual currency), tags, and custom JSON data.
Additional properties enable behaviors like stackable, consumable, activatable, and tradable.
User items also have a publishing state (DRAFT, PUBLISHED, RETIRED, REVOKED) to help control their life cycle.
Note that brainCloud does not currently support bundles – though this can be worked around using the custom JSON data and a bit of cloud code.
Virtual Goods (3rd Party)
brainCloud directly supports in-app purchases on iOS, Google, Facebook, Steam, and more.
Purchases are enabled by defining Products in the Design | Marketplace | Products screen of the Design Portal. Products are generally used to purchase Virtual Currency bundles, but in brainCloud 4.9 we add support for purchasing User Items (i.e. Virtual Goods) as well.
Products in brainCloud can be defined with multiple price points – which are convenient for scheduling sales using the Promotions service.
To configure Products in brainCloud for purchase, developers must first:
Configures the necessary platform integration settings. See tutorial examples for iOS and Google to start.
Configure the products to be purchased in the Design | Marketplace | Products page of the portal. The products should be configured to award Virtual Currencies, items from the Item Catalog, and/or custom rewards via attached JSON (and custom cloud code scripts)
Configure the pricing of the products – matching up the appStore IDs with the definitions in the platform stores
At purchase time, the app will:
Retrieve a list of the products available for sale (and their corresponding platform store ids) via brainCloud’s AppStore service’s GetSalesInventory() call.
Call the Platform SDK to retrieve the localized prices for the items to display
Display the list of products to the user in your custom storefront
When a user selects purchase, the app will initiate a purchase transaction using the Platform SDK
The SDK will return receipt data, which the app will forward to brainCloud using the AppStoreVerifyPurchase() call
brainCloud makes a server-to-server call to the Platform to verify the receipt data (as well as performs a few additional checks of our own)
If the purchase is valid, the player is awarded the contents of the Product – and the results are returned to the client app
For more information, see the brainCloud AppStore APIs.
Facebook only allows apps to retrieve the user’s friends during the initial authentication operation. Since brainCloud Friend and Social Leaderboard APIs can be called anytime (during the current or subsequent play sessions) – we need to store a copy of the Facebook friends in the internal brainCloud friend list. If this feature is enabled, when a user logs in via the AuthenticateFacebookLimited() call, brainCloud will retrieve the user’s Facebook friends and add them to the internal friend list for that user. Note – all friends in brainCloud are bi-directional – so their friend’s friend lists get updated as well.
To enable this feature, go to the Design | Core App Info | Application IDs page, choose the Facebook tab, and set the Facebook Limited Login (Retrieve friends) drop-down to “Retrieve and add to internal friends (add only).”
Advice
For our customers that are using 3rd party authentication services: If you are getting a list of Facebook friends from another service, you can use the new AddFriendsFromPlatform() call to add those friends to the internal list all at once.
Account Migration Support
The brainCloud community has long been interested in being able to migrate player accounts on-demand from one instance to another.
This is useful when:
migrating to brainCloud from another service
beta-testing a new release in a separate brainCloud app (or server) instance
brainCloud’s security and privacy frameworks can make this very challenging (as they should!). In brainCloud 4.8 we’ve added some new features + APIs, that when used together, can make this use case achievable.
The new features / APIs are:
Authentication postFail – you can now attach a custom script to an Authentication failure. This allows your custom script to perform some work (like account retrieval and creation) when an authenticate operation fails. The script then returns a special status (199) to tell the dispatcher to re-try the authentication from the beginning.
GetSessionForValidatedCredential() – a new S2S method that allows a client authentication to be performed via an S2S script. Once authenticated, the script can then retrieve and return select data from the user account.
SysGetUserExport() – a new cloud-code only method that allows a script to retrieve an export of the data associated with a user.
By putting these features together, a developer can:
Write an authentication postFail script for the target app, that will catch authentication failures and attempt to retrieve the missing user account
Write an account retrieval script for the source app, that can be called via S2S to retrieve the data from a user account if the supplied credentials are valid
Information
For full instructions on these use cases, see the brainCloud Knowledgebase.
Edit User Email Identities
The brainCloud Design Portal has been updated to provide a simple way for Support personnel to update the Email Identity + Contact Emails of users.
Simply navigate to the Credentials section of the User Summary page in User Monitoring, and click the pen icon next to the user’s email identity.
Note that if you only want to edit a user’s Contact Email – we have added an edit feature (via another pen icon) near that field as well.
Miscellaneous
In addition, the following new changes have been added to the platform:
Division improvements – we have adjusted the Division Set algorithms to allow players to post scores for rounds that started before the Division instance was created. This is important because some apps have their user’s join divisions just-in-time as they are posting their first score – and thus if the user is the first player in the division, their play round would have begun before the division tournament itself had been created! (And thus it was rejected by brainCloud). The new algorithm will dynamically adjust the start time of the division if a player attempts to record a score from before the Division was created. Note that the start time of the round must be within 2 X the Buffer time defined for the tournament.
Authentication Pre- and PostFail- hooks – we have added both pre- and postFail- hook support for the Authentication services. This work was done in association with the Account Migration feature (above) – but they will undoubtedly will be useful in their own right!
Lobby + Relay Server protocol improvements– we have tightened up the data structures and IDs commonly used between Lobby Services and Relay Services to be more consistent. This is in preparation for new Multiplayer features coming in the near future. The biggest impact of this is the replacement of the owner field in the Lobby data with the proper ownerCxId field. To help migrate to the new structure, a new compatibility flag has been introduced, which when enabled, causes both the owner and ownerCxId fields to be present in Lobby data messages. (This flag is currently forced to enabled for both new and existing apps.)
New Client Library calls– we have added a few calls that were introduced in recent releases as cloud-code only, to the 4.8 client libs:
AppStore – the RefreshPromotions() call has been added
Events – the DeleteIncomingEvents(), DeleteIncomingEventsOlderThan() and DeleteIncomingEventsByTypeOlderThan() calls have been added
User Files – we have added the UploadFileFromMemory() call to the JavaScript library, and likewise improved the Unity implementation of the call.
Audit Logging
Added additional tracking for changes to Team information
Cloud-code Script Performance
Updated Rhino engine from 1.7.12 to 1.7.13
We have enhanced the API Server bootup strategy to pre-load and cache both scripts and leaderboard configurations for active apps – resulting in faster launch performance for cold servers
Added big message support to user batch script operations
Group & GroupEntity Performance Improvements
We have adjusted the indexes and sharding strategies for Groups and Group Entities to improve performance.
Scheduled / S2S Scripts
Improved error logging for Scheduled and S2S Scripts
Portal Changes
We have made the following portal improvements:
Design
Core App Info | Application IDs
New option to retrieve friends when using Facebook Limited Login added to the Facebook tab
Core App Info | Advanced Settings
New compatibility feature: Include legacy lobby ‘owner’ field in API output. Note – the new code + features that use this flag aren’t completely ready yet – so changing the flag is disabled. The flag will be set to true (enabled) for both new and existing apps.
Cloud Code | Scripts
There is a new search box on the cloud code scripts page. Just type a few letters, and click on the name of the script you want to view/edit!
Leaderboards | Leaderboard Configs
The Leaderboard Configs page has been refactored to better support apps with thousands of leaderboards
General
Privileges + Permissions handling – We have re-worked the underlying permissions and privilege caching and enforcement code to be more consistent
Monitoring
User Monitoring | User Summary
You can now change a user’s email identity credentials by clicking on the pen icon next to their email identity in the Credentials section of the page. When editing the user’s email identity, you are also given the option to change the user’s contact email as well.
You can also change the user’s contact email directly via the pen icon by the Contact Email field in the Account Information section.
Warning
Note that changing a user’s contact email alone does not change their email identity (which is the email address used to log into your app).
API Changes
The following changes/additions have affected the brainCloud API:
Bridge
New Sleep( <millis> ) call added to facilitate waiting before retry operations. Can only be called from cloud-code. Note – the max sleep time is restricted to the timeout setting of the script.
New GetSessionForValidatedCredential() allows an S2S script to acquire a client session for the account associated with the provided user credentials, after first confirming that the credentials are valid, of course
Friend
New AddFriendsFromPlatform() call allows devs to add multiple friends to the internal brainCloud friends list, specifying the platform-specific external IDs, instead of brainCloud profileIds. ← saving multiple lookup calls.
Global App
New SysGetAppSecret() method returns the secret for the current session. Useful for apps using the Shared Accounts feature (between Parent and Child apps), and that don’t want to package the secrets of all child apps in the client binary.
Global Files V3
New cloud-code only methods for confirming files exist: CheckFilenameExists() and CheckFullpathFilenameExists().
Identity
New cloud-code only SysChangeEmailIdentity() method allows the email address associated with a user to be changed without having the user’s password. This is of course a dangerous method not suitable for client usage – so it is cloud-code only.
Leaderboard
New SysCreateLeaderboard() call allows for the programmatic creation of Group as well as Player leaderboard. The old call, CreateLeaderboard(), only supported the creation of Player leaderboards – and has been deprecated.
New SysEditLeaderboard() call likewise allows the editing of group leaderboards.
Lobby
We have added 3 new methods in preparation for our upcoming Join-in-progress and Long-lived Lobbies features: SysRoomStopped(), SysMemberLeft(), and SysGetLobbyMember(). Stay tuned!
User
New cloud-code only SysGetUserExport() call allows a script to retrieve an export of the specified user’s data.
We have also deprecated the following methods:
Leaderboard
CreateLeaderboard() – replaced with SysCreateLeaderboard() method (see above)
EditLeaderboard() – replaced with SysEditLeaderboard() method (see above)
Miscellaneous Changes / Fixes
Updated libraries
All supported libraries have been updated with the latest API enhancements. Go get ’em!
Documentation updates
Updates to tutorials and API References to match the new features/APIs in this release
Important Fixes
BCLOUD-29 – LobbyService joinLobby() is broken in some circumstances
BCLOUD-56 – [PROD] Tournament rewards with only “custom” rewards cannot be claimed
BCLOUD-68 – Logging performance improvement
BCLOUD-519 – User Monitoring / Logs – Fix handling of mismatched request/response data for displayed packets.
BCLOUD-575 – Add packetId as a field in requestResponse logs
BCLOUD-634 – ErrorLogEntry timestamps are slightly off
BCLOUD-698 – Handle “duplicate key” exception on Leaderboard Service – Post Dynamic (player or group score)
BCLOUD-707 – Allow Tournament Scores to be posted to Division Set Instance for round started before joined tournament
BCLOUD-710 – ACE Editor: when copying and pasting content sometimes that pasted content is missing from the submitted data.
BCLOUD-793 – Defect in memcached lock handling for temporary sessions
And fixed issue with “edit leaderboard” APIs potentially resetting pacer settings
Plus miscellaneous fixes and performance enhancements…
Release 4.7.5 is a surgical release to improve brainCloud support in a few key feature areas (mostly Purchases + Promotions). We hope you dig it!
Release Highlights
Promotions
This release addresses some limitations of the existing promotions system and introduces a few cool new tricks.
The improvements, in no particular order, are:
Added new Purchase Rewards Hook – a new API Hook that allows apps to override the configured reward amounts for product purchases. This is useful for companies that like double the rewards of a promotional item, instead of offering the same items for less $. You can find a script example here.
Added max # of purchases for Automated Promotions – you can now configure Automated Promotions to expire early if a user makes a purchase – limiting that special deal to the first <x> purchases they make.
Added max # of re-triggers for Automated Promotions – you can now configure Automated Promotions to re-trigger a finite number of times
New AppStore RefreshPromotions() call refreshes the Segments and Promotions of the current user. Useful for apps that want to check if a promotion became active during the play session. Note – cloud-code only for now.
In addition, we have addressed a limitation where Automated Promotions targeting existing Segments would not trigger for users already in that Segment. Those users (in existing segments) will now have the promotion applied by a new job that kicks off when the Automated Promotion is enabled.
Purchases
We have also made improvements to the saved purchase transaction data – as viewed via the User Monitoring | Transactions page. For new purchases, you can now see:
Any rewards associated with the purchase
Where the purchase was made during a promotion
And whether the purchase has been refunded. Note – for purposes of brainCloud, chargebacks also appear as refunds. Also, note that these states only apply to Facebook purchases.
Miscellaneous
Builder API – Our “official official” beta release of Builder API begins now. Our planned 4.7.0 roll-out was delayed while we put in some finishing touches. Note – still for private licensees and approved BaaS customers only.
Cloud-code Script Hook – we have added a cloud code script pre-hook. This can be helpful when re-organizing scripts into folders (using our new Cloud Code Folders feature). This hook can allow you to rework your script organization, while still supporting existing clients attempting to run scripts from their old locations. See this article for an example of how to use it.
Events – we have added more flexible ways of deleting incoming events for a user. See the API Changes section for more details…
Room & Relay Servers – we have reworked our room/relay server mechanisms to be more efficient. You may notice more responsive cleaning-up of server resources.
RTT – Improved clean-up (server-side) of stale client connections.
Portal Changes
We’ve made the following portal changes:
Design
Cloud Code | API Hooks
Added new AppStore PurchaseRewardHook – configure it as a “Post” hook to dynamically override the default awards of an item.
Added the ScriptService to the list of services that support API Hooks. So for example you can now add a Pre-hook to “RunScript” that adjusts the name/path of a script before running it. Useful when migrating to Cloud Code folders while still maintaining compatibility with existing clients.
Cloud Code | Scripts
We have updated the Scripts screen to default to showing up to 100 scripts per page. You are welcome! 🙂
Promotions | Automated
You can now set the max # purchases and max # re-triggers for automated promotions. Leave the value blank for unlimited – which is the default.
Monitoring
Global Monitoring | Recent Errors
Updated the source of legacy servicemix errors to the more up-to-date cron and datastream sources
User Monitoring | Transactions
We have beefed up the Transactions page to show rewards, promotions and refund status of transactions. There is also more transactional info shown via the Transaction Action menu for Facebook purchases.
Steam pending transactions are no longer shown (by default). There is a new toggle button to toggle viewing pending transactions.
API Changes
The following changes/additions have affected the brainCloud API:
AppStore
The GetEligiblePromotions() method (and other promotions methods) now include the new num purchases and retriggers counts in the responses when appropriate.
Added a cloud code method, RefreshPromotions(), that refreshes the segments and promotions associated with a user. Note that a user’s segments and promotions are automatically refreshed when they authenticate. Calling this method allows apps to periodically refresh the segment + promotion data for the user during the play session. Note that this is an expensive call – calling it is equates to 2 API counts (technically 1 API + 10 bulk API) – so use it sparingly!
Events
New event deletion methods – DeleteIncomingEvents(), DeleteIncomingEventsOlderThan() and DeleteIncomingEventsByTypeOlderThan().
Note that all of the new methods are cloud-code only for now – but will be added to the client libraries for brainCloud 4.8.
Miscellaneous Changes / Fixes
Updated libraries
No changes to the Client Libraries for 4.7.5.
Documentation updates
Updated API Reference docs and examples
Important Fixes
BCLD-7072 – Automated Promotion job to run when promotion created or new target segment added
BCLD-7095 – Failure to extend the TTL of an RTT cx should result in the termination of the socket connection
BCLD-7201 – Product pricing lookups should be specific to store type
Plus miscellaneous fixes and performance enhancements…
brainCloud 4.7 is a big release – with lots of new features and even more under-the-covers. Hold onto your hats!
Release Highlights
Cloud Code Folders
The big feature of 4.7 is cloud code folder management. Yes – you will finally be able to organize your cloud code scripts properly!
We know – some of you have been waiting for this feature forever. To be fair – when we originally built brainCloud, with the rich API we had designed (now at > 500 API calls!), we expected custom scripts to be few (i.e. less than a dozen) and small (i.e. less than 100 lines). Let just say that some of you have greatly exceeded those expectations. 🙂 This feature is for you!
Key components of this feature:
Folder Tree – Updated Design | Cloud Code | Scripts Screen with support for creating and navigating within folders
Enhanced Import & Export Support – Enhancements to Import and Export functions to allow importing/exports of the entire script collection (with folders intact), or optionally individual folders (with recursion, of course).
Deployment Support – The Deploy features have been enhanced to support cloud code folders. The full script tree will be pushed when you deploy from one app to another. Note – using the new Builder CLI, you can even push individual folders of scripts from one app to another – great for syncing common scripts between apps!
Rename Scripts – Scripts now have scriptIds that help to preserve linkages to scripts as they are moved or renamed. And hey, you can now rename scripts!
Author History – We also now record the name of the team member who made script changes
Smart Updates – finally, before updating a script during a Deploy Push or Import, we first take a look to see if it really changed. If not, we skip the update without increasing the version – which makes the version history of scripts smaller and much more meaningful!
Information
Note that the new Scripts screen, with Folder Support, will not be enabled immediately upon release of 4.7. Out of an abundance of caution, we will wait a few days to ensure that there aren’t any unforeseen issues with the underlying schema changes before turning this feature on fully.
Arcade-style Leaderboards
Building a game with an old-school feel? brainCloud 4.7 adds support for arcade-style leaderboards – where users can have more than one entry in the leaderboard! Great for daily or weekly rotating high scores!
Characteristics of arcade-style leaderboards:
Players can have more than one entry in the leaderboard (unlimited)
Arcade-style leaderboards are created by setting the Leaderboard type to Arcade High (i.e. higher scores are better) or Arcade Low (i.e. lower scores are better). Note that the leaderboard type must be set at the time of leaderboard creation. You cannot change an existing leaderboard to/from Arcade-style – due to the differences in how the data is stored.
Arcade-style leaderboards must rotate at least weekly; otherwise, the stored data would grow at an uncontrollable rate.
Arcade-style leaderboards do not currently support tournaments or divisions. We will consider adding support in the future if demand warrants.
The standard Leaderboard APIs work as-is for Arcade-style leaderboards, with the following adjustments:
RemovePlayerScore() removes all of a player’s scores(s) from the specified leaderboard
GetPlayerScore() returns only a single score (i.e. the player’s best score) from the specified leaderboard
A new method, GetPlayerScores(), returns all of a player’s scores (up to a max limit) from the specified leaderboard
GetPlayerScoresFromLeaderboards() returns only the best score per leaderboard specified
Facebook Limited Login Mode
brainCloud adds support for the new Facebook Limited Login mode – which allows apps to utilize a Facebook Login while adhering to new Apple guidelines (and user preferences) that prohibit sharing of tracking data with 3rd parties.
For more information on this feature, see the blog post here.
Steam and Playstation Friend Support
brainCloud now has direct support for Steam and Playstation friends.
This means your apps can more easily create social features (including social leaderboards) on those platforms. Full Steam and Playstation support have been added to the Friend Service and Leaderboard Service APIs.
As a bonus, we have also reworked how the caching of friend data works. This should mean fewer calls to the 3rd party systems (i.e. Facebook, Steam, and Playstation) and faster responses to the social API calls – including ListFriends(), GetSocialLeaderboard(), etc.
Improved Unity Plug-in
brainCloud has a new-and-improved Unity Plug-in. Redesigned and re-implemented from the ground up, the new plug-in:
Has a cleaner User Interface
Is more secure – no longer stores appIds, secrets, etc. in plain text. Now requires a re-login to change settings.
Can now enable/disable logging from the Plug-in without code changes
brainCloud 4.7 marks the beta release of our Builder CLI tool (and the underlying Builder API).
The Builder API currently allows the following:
App management
create, update and delete apps within a team
manage app lifecycle – enable/disable, etc.
Deployment management
scriptable deployment of configuration meta-data (including files + scripts + unowned migrate-able custom entities) from app to app
deployment of scripts (independent of app metadata); support full script tree or individual folders
Script management
create, update and delete scripts within an app
Super features
plus additional features for private licensees
Note that the Builder API does not fully duplicate or replace the SYS APIs available via Client APIs and S2S. Its primary purpose is to provide higher-level access to features that are not appropriate at the Client and S2S API levels.
Information
Access to the Beta Release of the Builder CLI is limited to approved customers only. Contact support and/or your brainCloud Account Rep for access.
Additional Features
The following additional features are also included in this release:
Apple Push Notification HTTP/2 support
brainCloud now supports Apple’s HTTP/2 based APNS protocol – which is important as support for their legacy protocol ends on March 31st, 2021.
Note that no changes are required to your clients or app configurations to support the new protocol
Automated Promotions Improvements
We have added improvements to several common use-cases – including adding Automated Promotions to existing segments.
Update – we are delaying these improvements to a 4.7.1 patch that will be available shortly after the 4.7.0 release.
Improved Custom Entity Sharding Support
Horizontal Sharding allows you to spread your custom entity collection across our MongoDB cluster – improving read/write response times for large collections
Sharding a collection means a key must be chosen to use to distribute the data. This key must be backed by a custom index in the collection.
Owned collections are always sharded via the “ownerId” field. As of 4.7, brainCloud now automatically adds an { “ownerId”: “hashed” } index for this purpose.
Unowned collections are sharded on a custom basis based on the entity schema, and the usage patterns of the app. Once the key has been chosen, a custom index must be chosen (or created) to support that key – and must be marked as a shard key index. Indexes marked as a shard key index cannot be deleted via the Design Portal.
Note – once set, the shard key for a collection cannot be changed. So choose wisely!
Sharding must be enabled on a per-entity basis by brainCloud Support Personnel. Contact support via the Chat Widget if you would like to discuss sharding one or more of your collections.
Improved Lobby Performance
The underlying Lobby Processing code had been re-written to be much more efficient.
Inventory Catalog Image-handling overhaul
We have improved how the system handles embedded images so that images are now properly copied when deployed from app-to-app.
MongoDB 4.0 Support
brainCloud 4.7 now officially supports MongoDB 4.0
All Private brainCloud deployments will be moved to MongoDB 4.0 within the next month
Oculus authentication
brainCloud has added direct support for Oculus authentication
Playstation Network authentication
To facilitate PSN Friend Support, brainCloud has added support for direct PSN authentication; previously apps had to use the external authentication feature for PSN authentication
Portal Changes
We have made changes to the following sections of the portal:
Design
Core App Info | Application Ids
Added new PSN and Oculus platform integration tabs
Core App Info | Platforms
Added new Oculus platform
Core App Info | Advanced Settings
Added new “Use Legacy Player Id” flag, which if true, causes the legacy playerId field to function and be returned in some APIs in addition to the newer, proper profileId field. Note the fields are synonymous (and contain the same values).
Added new “Add custom paths for Item Catalog images in API” flag to determine whether the Item Catalog allows custom image paths in the image field. Going forward, this behaviour has been deprecated; developers are free to include custom image information in the JSON blob that can be attached to catalog items.
Cloud Code | Scripts (Legacy)
The old cloud code scripts screen is still available (for a limited time) – but have been labeled with (Legacy).
Note that you can only edit scripts present in the root script folder using this screen.
Cloud Code | Scripts
The new Scripts service!
Allows full editing and management of scripts – including creating folders, moving scripts, exports and imports.
Cloud Data | Custom Entities
We now indicate which entities are Sharded, and if un-owned, which Index is used to back up the Shard key.
Note that sharding a Custom Entity collection is done by brainCloud Support Personnel upon request
Leaderboards | Leaderboard Configs
Added new Arcade High and Arcade Low leaderboard types.
Promotions | Automated
Now properly enforces that an Automated Promotion must target at least one Segment.
You must now create and save an Automated Promotion before enabling it. This is because enabling an Automated Promotion now triggers a batch process against all the users of the configured segments – we want to encourage the developer to get the promotion configured properly before enabling it.
Monitoring
Global Monitoring | Leaderboards
Added support for new Arcade-style leaderboards
Global Monitoring | Server Logs
Added new Elapsed time column to easily convey incoming S2S and webhook performance
User Monitoring | Select User
Added PSN and Oculus IDs to the available search filters
User Monitoring | Friends
Added support for Steam and PSN friends
API Changes
The following changes/additions have affected the brainCloud core APIs:
Client APIs:
BrainCloudWrapper
Added new authenticate and smart-switch calls for FacebookLimited, PlaystationNetwork, and Oculus.
Authentication
Methods for the new authentication types – AuthenticateFacebookLimited(), AuthenticatePlaystationNetwork(), AuthenticateOculus()
CustomEntity
The existing sysDropIndex() method has been deprecated and replaced with the new sysDropIndexName()method – which requires the index Name to be provided in addition to the keys of the index. This fixes an issue where it was unclear which index to delete in cases where multiple indexes have the same keys, but different collation settings.
Friend
Added support for ”Steam” and ”PlaystationNetwork” to Friend APIs
Added new method, GetMySocialInfo() that returns social platform info for the current user
Identity
Added new Attach, Detach and Merge calls for the new FacebookLimited, PlaystationNetwork, and Oculus identity types.
ItemCatalog
The Item Catalog service has been refactored to enable better image-file handling – especially when migrating items from app to app during deployment
To facilitate this, the service (by default) no longer allows for custom image paths (i.e. non-brainCloud anchored paths) to be set in the image field. Apps wanting to use custom image URLs can use the custom JSON section or resource data sections for this information.
There is a new compatibility flag, Allow custom paths for Item Catalog images in API, which controls the enforcement of this new behavior.
Leaderboard
Added new method, GetPlayerScores(), for use with Arcade-style leaderboards
User
SysGetPage() and SysGetPageOffset() calls updated to return profileId instead of playerId. New compatibility flag added (and defaults to true for existing apps) to preserve old behaviour.
S2S APIs:
CustomEntity
The new sysDropIndexName() call has been added to the available S2S APIs.
Presence
The getPresenceOfUsers() call has been added to the S2S APIs.
Note that we have corrected the documentation to accurately reflect that only the “sys” calls, plus the getPresenceOfUsers() call, are available via S2S.
Miscellaneous Changes / Fixes
Updated libraries
All libraries have been updated with the latest API enhancements. Go get ’em!
Better RTT disconnect handling in libraries
Documentation and Examples updates
API Reference updated with the latest API calls
All Unity Examples updated with the new Unity Plug-in
The Unity Space Shooter example now features an Arcade-style leaderboard
New Google IAP Unity Example and tutorial for integrating with brainCloud
Unreal S2S has a new c++/blueprint unreal project to demonstrate using brainCloud s2s calls
Miscellaneous doc + example updates
Important Fixes
BCLD-7012 – Core App Info | Advanced Settings – The App Disabled reason needs to allow only JSON maps
BCLD-6932 – On deploy/import config, no longer drop Custom Entity indexes in target app if not in source app and record entity config indexes not applied
BCDL-6689 – User Service – GetSysPage/Offset returning profiled as “playerId”. Fixed, and compatibility flag added.
Plus miscellaneous fixes and performance enhancements…
brainCloud 4.6 is mostly an under-the-covers technology refresh:
We have reworked our database access layer to be compatible with MongoDB 4.0 and beyond – all while maintaining API compatibility for our customers, of course.
We have moved our reporting services from our API Servers to our Datastream Servers for improved performance and stability for larger exports.
We have improved the RTT connection handling code in our client libraries.
We have removed a slew of older deprecated calls from our client libraries.
On top of all that, we did add a few new features – so read on for the details!
Release Highlights
Script API Usage Stats
We have added a new feature to our API Explorer and Script Editor to help you assess and tune the performance of your scripts.
The new API Usage log lists the API calls (by service and operation) that your script made, and calculates the API Count that will be used for billing purposes. Handy!
(Remember, the first 3 calls from a script are free – and each call after that is 1/2 count).
brainCloud has been enhanced to support SAML for end-user authentication. This is mostly relevant for non-gaming* customers who want to integrate their brainCloud app with a corporate directory.
Our SAML authentication builds upon the External Authentication feature, providing several key endpoints that can be used for initiating calls and receiving callback from the SAML identity provider.
See the SAML Authentication knowledge-base article for more information.
Advice
brainCloud for non-gaming apps? Certainly! All the qualities that make brainCloud great for games (fast, reliable, scalable and inexpensive) make it great for enterprise apps as well as games. Heck – even the gaming features are useful for engaging consumers via Gamification. brainCloud for all the things! 🙂
Random Custom Entities
We have added a new API that supports the retrieval of random custom entities.
The new API is called GetRandomEntitiesMatching() and takes as parameters the entityType, a JSON query filter, and the number of entities to return.
API Keys
We are developing a new Builder API mechanism for developers. This will enable API-driven management of teams, apps, and scripts via external services and tools.
We are hopeful that this, together with Cloud Code folders (coming soon), will allow devs to more efficiently integrate brainCloud with their build processes.
Our new API keys system is a foundational building block. To access any Builder API method, the following conditions must be met:
Builder API access must be enabled for the Team itself
Builder API access must be enabled for the User who owns the key (on the target Team)
The Builder API key must be valid and not expired
We will provide more information on the Builder API in the coming months.
RTT Connection Handling
As mentioned above, we have made significant improvements to RTT Connection Handling in the client libraries.
The improvements across all libraries include:
Refactored the underlying code to keep track of RTT connection state via a new RTTConnectionStatus enum with the following values – CONNECTED, DISCONNECTED, CONNECTING and DISCONNECTING.
Added a new GetConnectionStatus() method to return this status.
The existing IsRTTEnabled() call still works – but now simply returns true if the status is CONNECTED.
In Unity and Unreal, we have also:
Added a new WebsocketStatus enum (with values OPEN, CLOSED, MESSAGE, ERROR, and NONE) which is used internally to keep track of the WebSocket status. This allows the library to catch an annoying Android background app bug where the RTT connection closes because of the WebSocket closing — and notify the client app to re-establish its RTT connection.
Improved error handling in Unity RTT now gives more information about what happened with the RTT connection.
Portal Changes
We have made the following portal changes:
Team
Manage | Members
Added a column to show which users have API Keys defined for this team
Also added a new Builder API Access option to the Permissions tab of the user settings
Manage | Team Info
Added a toggle for enabling Builder API Access
Design
Cloud Code | API Explorer
The new API Usage Stats log is now added to response when cloud code scripts are called.
Cloud Code | Scripts, Script Editor
The new API Usage Stats log is also appended to the responses in the Run tab of the Script Editor.
Cloud Data | Custom Entities
The index list screen now displays the index key fields – providing a much better overview of index coverage.
Integrations | Manage Integrations
A new SAML Settings section has been added to the integrations screen.
Monitor
Group Monitoring | Groups
We have added a new feature that allows Portal users to remove members from groups.
User Monitoring | Recent Users
We now capture and display the version of the client app that users are using to login.
User Monitoring | Logs
A new [Refresh] button has been added. Very useful when viewing the live logs of a user while debugging.
App Version now displayed in Recent Users list…
Reporting
API Usage
We now break down custom entity operations by entity type – providing better insight into the performance of individual entity types.
General
Edit Profile | API Keys
You can now create API Keys for use with our Builder API – coming soon!
API Changes
The following changes/additions have affected the brainCloud API:
Custom Entity
(New!)GetRandomEntitiesMatching() call added for returning a set of random entities from a filtered list of candidates.
File
(New!)FileUploadFromMemory() call added to allow uploads to happen in situations where local file access is not possible or convenient. For example, screenshots from Unity-based WebGL apps. Note – Unity client only.
Group
(Improved!) Sys APIs for Groups and Group Entities are now available from S2S
RTT
(New!)GetConnectionStatus() call returns the status of the RTT WebSocket connection ( CONNECTED, DISCONNECTED, CONNECTING and DISCONNECTING).
The following methods are newly marked as deprecated:
PlayerState
UpdateName() deprecated – use UpdateUserName() instead… (which is no longer marked as deprecated – it was a mistake!)
The following previously deprecated methods have been removed from the 4.6+ client libraries:
Authentication
GenerateGUID() and GenerateNewAnonymousId() removed – use GenerateAnonymousId() instead.
Client
GetGameId() removed – use GetAppId() instead.
GetGameVersion() and GetVersion() removed – use GetAppVersion() instead.
Entity
GetSharedEntityForPlayerId() removed – use GetSharedEntityForProfileId() instead.
GetSharedEntitiesForPlayerId() removed – use GetSharedEntitiesForProfileId() instead.
GetSharedEntititesListforPlayerId() removed – use GetSharedEntitiesListForProfileId() instead.
Friend
FindPlayerByUniversalId() and FindUserByUniversalId() removed – use FindUserByExactUniversalId() or instead.
ReadFriendPlayerState() removed – use ReadFriendUserState() instead.
Gamification
ResetMilestones() removed from client libs – still available from cloud code.
PlaybackStream
GetStreamSummariesForInitiatingPlayer() removed – use GetRecentStreamsForInitiatingPlayer() instead.
GetStreamSummariesForTargetPlayer() removed – use GetRecentStreamsForTargetPlayer() instead.
PlayerState
DeletePlayer() removed – use DeleteUser() instead.
ReadPlayerState() removed – use ReadUserState() instead.
ResetPlayer() removed – use ResetUser() instead.
UpdatePlayerName() removed – use UpdateUserName() instead.
UpdatePlayerPictureUrl() removed – use UpdateUserPictureUrl() instead.
PlayerStatistics
IncrementPlayerStats() removed – use IncrementUserStats() instead.
ReadAllPlayerStats() removed – use ReadAllUserStats() instead.
ReadPlayerStatsForCategory() removed – use ReadUserStatsForCategory() instead.
ReadPlayerStatsSubset() removed – use ReadUserStatsSubset() instead.
ResetAllPlayerStats() removed – use ResetAllUserStats() instead.
PlayerStatisticsEvent
TriggerPlayerStatisticsEvent() removed – use TriggerStatsEvent() instead.
TriggerPlayerStatisticsEvents() removed – use TriggerStatsEvents() instead.
Product
This legacy Product service has been been removed. Use the replacement AppStore or VirtualCurrency services instead.
Miscellaneous Changes / Fixes
Updated libraries
All libraries have been updated. Go get ’em!
Documentation updates
Added new knowledgebase articles for dozens of portal screens. Look for the Learn More links!
Important Fixes
BCLD-6427 – In API Explorer/Scripts/S2S Explorer the up/down arrows in the log are not working
BCLD-6389 – Restore Checkpoint now properly deletes new custom collections (created or imported) since the selected checkpoint
BCLD-6344 – When viewing indexes, the index fields box is not pretty printed
BCLD-6352 – ADHOC Division Set Leaderboard Template with Tournament in progress is losing required tournament data on import/deploy
BCLD-6320 – C++ cannot tear down WebSocket on Win32
BCLD-6343 – Deleting custom indexes shows wrong text – asks if you want to delete the “entity type” instead
BCLD-6327 – Import/Deploy custom entity configs (and migratable custom entities) only if target app has applicable billing plan
BCLD-6251 – Added support to manage groups and group entities from S2S
brainCloud 4.5.6 is a very focused release – but much more significant than the version number would imply.
This update brings the release of our new Version 2Relay Servers – which are more reliable, more feature-rich, and faster to launch than our original Relay Servers.
Important: The RelayComms V2 Protocol (used by brainCloud 4.5.6 and newer libs) is not compatible with the RelayComms V1 Protocol (used by brainCloud 4.5.5 and older libs). The recommended migration process is described later in this document.
Release Highlights
Improved Relay Servers
As more and more apps use brainCloud’s Relay Servers, we have realized some limitations with our initial implementation:
Defect – reliable acknowledgments don’t consider all combinations of channel * reliable bit * ordered bit * net id (from user). Combinations of reliable/ordered would FAIL if used within the same channel Id. This issue would normally only happen with higher player counts – but it is definitely an issue.
Limitation – no way to send a message to a subset of players (e.g. your team in a competitive game). V1 only allowed for sending to all, or to a single specified user
Limitation – no protocol version embedded in the protocol – which makes it near impossible to modify/extend/correct the protocol and maintain compatibility with older clients.
Unoptimized – the Docker container used to launch the relay servers wasn’t properly optimized to improve launch times.
The good news is that we have addressed these limitations with Version 2 of our RelayComms Protocol – and incorporated it into our new Relay Servers and 4.5.6 Client Libraries.
The better news is that the Client APIs for the new RelayComms is almost completely compatible – that is, you don’t need to change your client code to use the new servers – other than:
In C#-only, you need to adjust for the new netId parameter in the RelayCallback() method ← note, this was a defect. The other languages already had that parameter in their callback method.
If migrating a Live application, you will need to substitute in the new lobby ids (see the migrationprocedure section below)
The bad news is that our new V2 Relay Servers are not compatible with our 4.5.5 and older client libraries – so they only work with brainCloud 4.5.6 libs and greater. Conversely – the new 4.5.6 libs do not work with the legacy Relay Servers – so migrating your apps to the new Relay Servers (which we highly recommend) must be done carefully. We provide the details on how to do this without interruption in a section below.
Note – The V1 RelayServers will continue to function for the foreseeable future (at least 1 year) – so you do not need to force a short-term upgrade to your app. It is highly recommended that apps upgrade when they get a chance however.
Matchmaking Optimizations
This release also includes some serious optimizations to brainCloud’s Online Matchmaking and Lobby System algorithms – resulting in:
greater lobby queue scalability
much faster best-case room/relay server launches
Note that these changes are completely under-the-hood – no API changes required.
Miscellaneous Changes
The following changes are also included in this release:
Amazon Platform detection – has been added to all of the libs (except C++). Important – be sure to turn on the “Amazon” platform on the Design | Core App Info | Platforms page for your app. This is important even if you aren’t using Amazon IAP – otherwise, your Android app won’t launch on Amazon devices!
Ability to clone Lobby and Server types – has been added to facilitate easier migration to the new Relay Servers
Improved WebPurify integration – are servers are now properly encoding problematic text characters before sending them to WebPurify
Procedure: Relay Server Migration
The following approach is recommended for migrating your app from V1 Relay Servers → V2 Relay Servers.
This approach has been designed to:
ensure the app is available to all players throughout the migration
support the various app store review processes
keep the developer in control of the timelines of the migration.
Approach
Benefits: This approach allows users of your old client to continue to play using the V1 Relay Servers – even as your updated client goes through app store reviews, soft launch, etc. using the new V2 Relay Servers. And then, after your release has been deployed globally and across all platforms, you can “force” users to upgrade to unite all players together again.
The executive summary of the recommended approach is:
Clone the Lobby and Server definitions of your app – producing a new set of V2 Lobbies and V2 Servers that will be used by the updated version of your app
Configure the V2 Server definitions to use Relay Protocol v2
Configure the V2 Lobby definitions to use the new V2 Server definitions
Modify your Client App to use the new V2 Lobby definitions, as well as the appropriate 4.5.6 Client Library
Optionally (but recommended), ensure that your Client App reacts to the Minimum Version setting from the Design | Core App Info | Platform page. This will allow you to “force” your users to upgrade to the new client when you are ready (see Version Enforcement)
Step-by-step
This section describes step-by-step how to modify your app to implement the recommended migration approach.
Design Portal
Go to Design | Cloud Code | My Servers – and clone the Relay Server entries to create new “V2” versions. A new [Clone Server] button has been added to assist with this. After cloning each entry, be sure to Edit it, and change the Relay Protocol to v2!
Go to Design | Multiplayer | Lobbies – and clone the Lobby entries to create new “V2” versions. A new Clone option has been added to the Action menu to assist with this. After cloning each entry, be sure to Edit it, and change it to refer to one of the V2 Servers that you created in Step 1.
App Code
Replace your brainCloud library with a new 4.5.6+ version of the client library.
Go into your source code, and change the names of the Lobbies that your client app references to the new V2 version of the lobby type name.
Rebuild and test your client app to ensure everything works.
(Optional – but highly recommended) If you haven’t already, enhance your app to pass the app version during the BrainCloudWrapper.Initialize() method, and display a “Client update required” dialog if it receives a 40322 – APP_VERSION_NOT_SUPPORTED error from the server during authentication. This will allow you to force users to upgrade to the new client when you are ready. Note – the required app versions are controlled via the Design | Core App Info | Platforms page.
For more information on implementing Version Enforcement in brainCloud, see the article at the link.
App Submission & Migration
Submit the updated app (which uses the V2 Relay Servers) to the various app stores for approval. Existing users will continue to play using the V1 Relay Servers.
Officially Release your app. During this stage of launch, your player liquidity is split – between the older and newer servers.
(Optional – but highly recommended) Once you are ready (and are confident that the app updated has been distributed globally to all appstores), you can update the minimum required versions on the Design | Core App Info | Platforms page to force users to upgrade, and re-unite your player base!
And voila – you have successfully migrated your app to the V2 Relay Servers without interruption!
Portal Changes
We have made the following portal changes:
Design
Cloud Code | My Servers
Added new [Clone Server] button to make it easier to duplicate server configurations
Messaging | Chat
The Replace Profanity with setting now properly defaults to “*”
Multiplayer | Lobbies
Added a Clone option to the Action menu to make it easier to duplicate lobby configurations
API Changes
Reminder – The 4.5.6 client libs only work with the V2 Relay Servers.
If your app is live and using Relay Servers, do not upgrade to the 4.5.6 Client Libraries until you are ready to migrate your app according to the procedure described in these release notes.
Although the Client libraries have changed significantly to support RelayComms V2, the APIs themselves have not.
There is just one fix to the C# libraries that affect a method signature:
The RelayCallback() method signature has changed. It now includes a netId parameter.public delegate void RelayCallback(short netId, byte[] data);
Miscellaneous Changes / Fixes
Updated libraries
All libs have been updated to use RelayComms V2!
All libs (except C#) now include Amazon Platform detection. Important: If your app supports Android, and you want your Android apps to run on Amazon devices, remember to enable the Amazon platform on the Design | Core App Info | Platforms page!
Documentation updates
The API Reference has been updated to include the updated C# RelayCallback
Important Fixes
BCLD-6304 – Error sending certain chat messages with WebPurify support enabled
BCLD-6240 – Presence updates sometimes failing due to improper TTL setting
BCLD-6239 – Lobby matchmaking NPE
Plus miscellaneous fixes and performance enhancements…
In Release 4.5.5 we added support for Amazon In-app Purchases. As part of that feature, we also expanded brainCloud to include Amazon devices as a separate Platform – essentially so that devs implementing Amazon IAP would be able to get a better feel of the monetization of users on that platform.
Regrettably, we neglected to properly anticipate and publicize the side effect of that change – with is that brainCloud apps using the 4.5.5+ libs running on Amazon now need to have the new “Amazon” platform enabled.
So – if you are building Android apps, and you want them to run on Amazon devices (whether you are using IAP or not), please go now and turn on Amazon platform supportbefore upgrading to our 4.5.5 libs.
(Note – to be precise, only the Unity 4.5.5 libs have Amazon platform detection right now. The rest of the libs are getting a 4.5.6 update soon with it though.)
The bad news is that delivering the full 4.6 Release (with Cloud Code Folders support) is taking longer than expected. Our adjusted schedule puts that release in September. (boo!)
The good news is that there are a bunch of smaller features that we are finishing up now – and so instead of making you wait until 4.6 for everything, we are going to do an early 4.5.5 release instead! (yay!)
PS – Don’t let the .5 release number fool you – there is a lot here!
Important Compatibility alert! – Our C# 4.5.5 Unity Libs now recognize when they are being run on Amazon Fire devices, and set the “platform type” appropriately (for better analytics). As a side effect of this, you need to enable the new Amazon platform on the Design | Core App Info | Platforms page for it to run on Amazon devices! You will need to do this even if you aren’t using Amazon IAP.
Pricing alert! – This release includes a new feature for Auto-Deleting Dormant Users. This is in preparation for charging devs for storing Dormant Users – which will become effective in January 2021. Read on for more details!
Release Highlights
Amazon In-App Purchase Support
At long last, brainCloud brings support for Amazon AppStore In-app Purchase items. This includes support for both Consumable and Non-consumable items (i.e. Entitlements). Basic subscription support is in place as well.
Perform the following steps to add Amazon IAP support to your app:
Register your app (and it’s IAP products). Create a Product for each price entry you wish to manage in brainCloud.
In the brainCloud Design Portal
Configure the Shared Secret key on the Design | Core App Info | Application IDs page – Amazon tab of the brainCloud Design Portal. You can find your shared secret key here.
On the Design | Marketplace | Products page – configure the Amazon Product SKUs for the appropriate price entries.
In your app
Integrate the latest brainCloud and Amazon libs into your app
Call AppStore.GetSalesInventory(), passing in the new “amazon” platform, to get a list of the products and their current prices (i.e. Amazon IAP SKUs)
Use the appropriate Amazon APIs to perform the purchase.
Verify the receipt that is returned via the AppStore.VerifyPurchase() call
Global Files V3 Portal Support
In 4.5, we introduced our new Global File service – which enables developers to organize files into folders – and to allow migrating of uploaded User Files →Global Files.
In 4.5.5, we have made the Global File service more accessible, by giving it its own page in the Design Portal. Simply navigate to Design | Custom Config | Global Files and start uploading your files!
From the Design Portal, you can:
upload, move, copy and delete files
create, move, and delete folders
download an archive of all of an app’s global files
restore an archive of an app’s global files
In addition, brainCloud 4.5.5 now migrates Global Files during deployment.
Slack Alerts (beta)
We have added our first cut of Slack integration to brainCloud!
With this integration, you can configure a custom channel (or channels) to receive alerts from selected categories, including:
chat – profanity filter violations
deploys – app deployments
hosting – room servers spinning up / down
integration – push notification expiry warnings
jobs – background reporting jobs started / completed
See this knowledge base article for instructions on configuring the slack webhooks for integration.
Custom Entity Singleton API
Here is an interesting statistic:
The UpdateSingleton() call for User Entities is by far the most heavily called client method. It is called >5X more often than it’s closest rival.
The reason is that it allows devs to bypass micromanaging ids. For example – You don’t need to know the entityId of the “CampaignSave” object to read and update. Your app just knows that there is only one of them per user – and updates them via the type (i.e. “CampaignSave”) instead of the id.
Given the popularity of the singleton pattern – we thought it fitting to bring a singleton API to Owned Custom Entities as well!
The following new methods have been added:
UpdateSingleton() and UpdateSingletonFields() ← partial updates for singletons!
ReadSingleton() and DeleteSingleton().
Note that the singleton API only works for owned Custom Entities.
Auto-Delete Dormant Users
At long last, brainCloud will now support the automatic deletion of Dormant Users.
brainCloud defines a dormant user as a user that has an account in an app, but hasn’t logged into it in the past 180 days (i.e. 6 months).
The evils of Dormant users:
The storage (and backups) of dormant users greatly adds to the costs of running brainCloud – and weighs down the performance of apps – with little or no benefit to developers (and their marketing teams) – as most users are anonymous and have probably already uninstallled your app!
brainCloud is making 3 key changes to combat the evils of dormant users:
Adding a new Auto-delete feature that devs can enable to automatically delete dormant users. This feature is safe and highly configurable – see details below.
Adding a new Dormant Users Fee to brainCloud’s monthly invoices. Devs will be charged $75 per Million dormant users (pro-rated). (Note – this line item is actually already on invoices – but the cost is currently set to $0 / million).
Finally, we will not start charging the fees until January 2021 – so that devs have the opportunity to delete their users first. Auto-deletion isn’t instantaneous – it works slowly in the background so as not to impact brainCloud system performance. Some brainCloud apps have over 100 million dormant users – it will take time to delete them!
Auto-deletion settings
The new Auto-deletion process is highly configurable. It allows you to set:
# of days of inactivity – brainCloud considers an account dormant after 180 days – but you can decide to only delete accounts after 1 year, for example.
exceptions – easily exclude users who have made purchases, have e-mail addresses, have XP levels greater than some threshold, have currency balances greater than a threshold, or are members of selected segments.
(optional) email notifications – want to warn users (that you have email addresses for) that their accounts will be deleted soon? You can send two notices. Of course, any users that login after the notice and before the deletion date are automatically removed from the deletion queue.
(optional) archive service – want to archive the users (temporarily) before deletion? We have that covered as well! Just configure an Owned Custom Entity type and we’ll temporarily store an archive of the user there – you decide for how long. Note that standard Custom Entity charges apply. Also – there is no automated way to restore an archived user – though it is certainly possible to manually do so – all the data is there in the archive JSON.
Note that the Auto-Deletion process does consume some API counts – in accordance to how it has been configured – namely:
+1 Bulk API Count for each user deleted
+1 Email Sent API Count for each email notification sent
We understand that this is a big change – and that deleting users can be scary – but we have worked hard to build a safe solution that keeps developers in control of their user data and infrastructure costs. We hope you agree!
This feature will not be enabled immediately upon 4.5.5 release. We have got a bit of final testing on the production hardware before we turn it on. Plus – as a reminder – billing for Dormant User retention will not begin until January 2021.
Additional Feature and Improvements!
The following new features aren’t headliners – but they are worth a mention!
Leaderboard Deployment Options – new options to allow deployment to production apps without touching or destroying dynamically created leaderboards.
Custom Entity DeletionQueries – we have added some new deletion calls that support query filters. Much more efficient than individually calling delete for each entity!
Product & Promotion Management APIs – we have added new S2S and cloud-code APIs for managing Products & Prices, and both Scheduled and Automated Promotions. These new APIs contain feature enhancements as well, including the ability to attach custom JSON objects to both Prices and Promotions.
Segment, Currency, and Notification Queries – in support of the above APIs, we have added several utility methods that retrieve the current segments for a user, the overall segment list, the list of push notification templates, and the list of virtual currency types. We have also added a new method to dynamically refresh the user’s segment list (to recalculate the segments since they logged in).
Unreal 4.25 Support! Technically, 4.25 support was added as a library patch for brainCloud 4.5 – but it’s totally worth mentioning.
RTT – we have added additional edge-case handling to prevent unnecessary disconnects – especially in regards to the Java client
Room & Relay Server launches – are now handled more efficiently in the background
RTT & Relay Comms – there are improvements in every client release. In particular, there are improvements in the Java Libraries this release
Portal Changes
We have made the following changed to the Design Portal:
Design
Core App Info | Application IDs
Added a new Amazon tab where you can fill in the Shared Secret necessary for validating Amazon AppStore receipts
(New!) Core App Info | Auto Delete Users
New screen for configuring the auto-deletion of dormant users
Note – this screen will not show up for a few weeks as we complete final testing.
Cloud Code | My Servers
You can now pick a relay protocol to use for your Relay Servers. The only choice currently is V1 – but V2 is coming very soon with improved performance and reliability!
(New!) Custom Config | Global Files
Manage the files and folders for the Global Files V3 service
Integrations | Manage Integrations
Integrate brainCloud with your Slack instance
Marketplace | Products
Configure Amazon IAP pricing for products
Expanded support for custom JSON on products
Promotions | Automated
The UI for targeting segments align better with the Scheduled Promotions screen
Added the ability to attach custom JSON to promotions
Promotions | Scheduled
Added the ability to attach custom JSON to promotions
Fixed an odd behavior where you had to set the start time to the future when editing scheduled promotions.
Also of note – user counts throughout the portal should now be more accurate – taking into account deleted and merged accounts (as well as accounts created directly via the User Service).
API Changes
The following changes/additions have affected the brainCloud API:
Client APIs
Custom Entity
New!Singleton APIs – DeleteSingleton(), ReadSingleton(), UpdateSingleton(), and UpdateSingletonFields().
New!Delete multiple entities in a single call using DeleteEntities() & SysDeleteEntities(). Note that apps are charged +1 Bulk API Count per entity deleted, in addition to the API Count for the call itself.
New!IncrementData() call added to client libs
Product Management
New! APIs for managing products and their associated prices
SysAddProductPrice()
SysCreateProduct()
SysDeleteProduct()
SysDeleteProductPrice()
SysGetProductList()
SysReadProduct()
SysSetDefaultProductPrice()
SysUpdateProduct()
SysUpdateProductPrice()
Note that all of the above methods are available via cloud-code and S2S only.
Promotions
New! APIs for managing both scheduled and automated promotions
SysCreatePromotion()
SysDeletePromotion()
SysEnablePromotion()
SysGetPromotionList()
SysReadPromotion()
SysUpdatePromotion()
Note that all of the above methods are available via cloud-code and S2S only.
Push Notification
New! SysGetNotificationTemplates() API to return the list of notification templates configured in the portal.
Segment
New! Two methods have been added for retrieving the user’s segment, and the full list of segments respectively: GetMySegmentsLegacy() and SysGetSegmentList(). We have made these methods cloud-code only because we plan to introduce schema changes in this area in the future, and don’t want client apps to be caught flat-footed.
New! We have also added the RefreshMySegments() cloud-code call to allow dynamically refreshing of segments during a session. Note that segments are already automatically refreshed upon authentication – this method can be used to cause segments to refresh mid-session – for example, after completing a level.
Virtual Currency
New! The following methods have been added for retrieving the list of currency types that have been defined in the portal:
SysGetCurrencyTypes()
SysGetParentCurrencyTypes()
SysGetPeerCurrencyTypes()
Note that all of the above methods are available via cloud-code and S2S only.
S2S APIs
All of the SYS calls described above are available via the Server-to-Server API as well.
Miscellaneous Changes / Fixes
Updated libraries
All client libraries have been updated with the latest API enhancements – go get ’em!
The following client libraries have additional improvements:
Unreal Lib – now supports Unreal 4.25!
Java Libs – there are some good RelayComms fixes in there.
In general, it is always best to update to our latest client libs!
There have been no changes to the S2S libraries themselves. The generic mechanism employed by our S2S libs is API agnostic – and thus the 4.5 libs already support all 4.5.5 APIs.
Documentation updates
All new methods are documented in our APIREF – https://getbraincloud.com/apidocs/apiref
