Release 3.9.0

brainCloud 3.9 is here! Check out the new hotness!


Release Highlights

Online Presence

Online Presence allows an app’s users to know which of their friends are currently online and available for collaboration.

Presence builds upon brainCloud RTT to deliver a rich solution which communicates:

  • online status – which users (friends, group members) are currently online
  • activity – customizable, rich activity data

In addition, presence supports:

  • real-time notification of status changes
  • ability of subjects to appear invisible (i.e. offline)

For more information, see the Presence Service API Reference.

Note – Online Presence requires brainCloud RTT.

Tournament Divisions

brainCloud already allows games to increase player engagement through global tournaments, which reward prizes (currency, xp, etc.) to users for their play in recurring and/or adhoc tournaments.

Unfortunately, the lure of tournaments diminish as the number of participants grow and the player’s chance of winning decreases. It is tough to motivate players when they need to rank at the top of a leaderboard with thousands of players.

That is where Divisions come in. Divisions horizontally divide your players into separate leaderboards (which we call division instances) of a set size – say 100 players each.

The advantages are significant:

  • Greater engagement – players are playing against a smaller set of opponents, and are more motivated because they have a greater chance of winning
  • Greater control – there is a greater ability to tune the risk / reward structure of the contest, since the numbers are constrained
  • Greater liquidity – divisions hide the actual size of your tournament pool, which can be advantageous when your app is still growing

For more information, see the new Division APIs in the Tournament Service API Reference.

Note – Divisions are available to Business Plan customers and above.


Refactored Currency and In-App Purchase APIs

We have completely refactored the Currency, Purchase, and Product / Pricing / Promotions APIs that were previously jammed together in our old Product Service.

We’ve created two shiny new services to contain the new goodness:

  • AppStore Service – houses the new purchase and Product / Pricing / Promotions APIs. The Purchase APIs have been completely re-designed for the new service.
  • VirtualCurrency Service – handles all the currency APIs (other than the move, the APIs are barely changed).

Have no worries – we will ensure that the legacy Product Service continues to work until July 1, 2020, but we strongly suggest that new apps move to the new APIs now, and older apps migrate when they can.

For more information, see the new AppStore Service and VirtualCurrency Service API References.


Customer Requests

We have also added a handful of features to satisfy key customer requests. Hopefully you’ll find yours here!

  • Global Pre-hooks
    • You can now set up a single pre-hook that gets invoked before any API call – which is especially useful if you want to significantly restrict the calls that can be made from the client, without having to individually configure the hook for each service + operation combination.
  • Global Properties
    • New JSON support – you can now directly add/edit JSON in your properties!
    • Deployment Enhancements – you can now preserve the values of select Global Properties though deploys. This is especially useful if you need to accomodate alternate property values in development vs. production, for example.  (Admittedly, using a JSON structure for the value, indexed by AppId is a decent solution for that as well!) 
  • Facebook
    • We’ve updated our Facebook libraries to support Graph API v 2.8
  • Improved Script Engine
    • Turns out our cloud code implementation had an issue where objects being passed and returned from scripts were being set to read-only – even though they were copies. This resulted in issues invoking certain methods on the objects, and of course not being able to modify them without performing another deep-copy within your script. This has been resolved. This result is fully back-wards compatible.



Last but not least, we have a few more improvements under-the-hood:

  • Improved Cloud Code performance
    • we’ve improved the caching of cloud code scripts for even better performance!
  • Improved Leaderboard caching
    • as part of our Tournament Division work, we improved the caching of leaderboard configuration data. The improvement will be most noticeable for apps with lots of leaderboards.
  • Improved Design Portal performance
    • We’ve been reworking our core Design Portal tech. You should notice improved zippiness all around when using the portal!


Portal Changes

We have made the following portal changes:


  • Core App Info | Application IDs
    • Added a new Bundle Id field in Apple platform settings, which if filled in, is used to perform additional receipt validation in the new AppStore Service.
  • Core App Info | Advanced Settings
    • A new compatibility flag, [x] Enable legacy Purchase Collection support, has been added. It defaults to enabled for both new and existing apps.
      • Apps with existing purchases should keep this enabled – it will allow the new purchase APIs and old purchase APIs to coexist nicely
      • New apps can feel free to disable this and use the new APIs only.
  • Cloud Code | API Hooks
    • We have added new Dispatcher and S2SDispatcher support for pre-hooks.
    • Configuring a pre-hook against those services will cause the pre-hook script to run before any client or S2S call respectively.
  • Custom Config | Global Properties
    • When creating / editing a property, you can now configure the editor for String or JSON editing. Note that the underlying value is still stored as a String.
    • You can also choose whether the property value should be protected from being overwritten during deploys. This is useful for values that are set uniquely per brainCloud app instance (i.e. the profileId of a system user, a to tell the client that this is a prod vs. debug instance, that sort of thing).
    • Note that during deployment, the deploy process obeys the configuration specified in the source app, not the target app.
  • Leaderboards | Leaderboard Configs
    • You can now flag tournament-enabled leaderboards to act as templates for Divisions. Template tournament/leaderboards do not appear in the regular leaderboard lists, and cannot be joined.
    • You can also now quickly clone leaderboards by choosing the Duplicate option from the action menu.
  • Loaderboards | Tournament Templates
    • Quickly clone tournament templates by choosing the Duplicate option from the action menu.
  • Leaderboards | Division Sets
    • Jump into our new Tournament Divisions feature by defining Division Sets!
    • Division Sets allow you to break tournaments into random sub-tournaments for greater engagement.
    • To configure a division:
      1. First create a tournament-enabled Leaderboard to act as a template (setting the template flag to enabled)
      2. Then create the division set, selecting the Leaderboard template and configuring the maximum # of players per division instance
      3. Use the new Tournament Division APIs to join the tournament!
  • Marketplace | Products
    • We have made a bunch of under-the-hood changes to allow for easier integration of new AppStores in the future
    • The screen should work largely as before – let us know if you experience any issues!
  • Messaging | Presence
    • New screen for configuring the new Presence service
    • Once enabled, any RTT connection established by a client will contain basic presence info (i.e. online/offline) as well
    • From there, rich activity and real-time updates can be enabled as well


  • Global Monitoring | Leaderboards
    • We have added a “Choose a division…” option to the Leaderboard selection menu (for apps that are using Divisions). Use it to view the leaderboard results for a Division instance.
    • Rationale – division instances are hidden from the Leaderboard lists (because there may be hundreds of them).
    • Pro-tip – You can use the API explorer to find the division instances related to a particular player
      • Go to Monitoring | User Monitoring, and find the player in question
      • If the Live Lock banner is showing, click the lock to unlock it
      • Click on [Login as User] to login as this user in the API explorer
      • Choose the Tournament service, and the GetMyDivisions() operation, and click [Run].
      • Voila – a list of the division ids instances for that player. Note that each id contains both the division set code, and the instance id (a number).
  • User Monitoring
    • We’ve added a new Recent Users tab to make it easier to find users that have recently logged into your app
    • Note that this is a log, so you may see the same user listed multiple times (only really noticeable at low activity counts)
  • User Monitoring | Transactions
    • Updated to support the new purchase services and transaction formats
    • You can now view purchase receipts, and even delete purchases if you would like (useful during testing)


  • Improved Portal Tech
    • We’ve been doing some work under-the-covers to improve our Portal technology
    • The first thing you should notice is a performance boost – yay!
    • You may also notice a few CSS-related bugs. Feel free to report those so that we can stamp them out!

API Changes

The following changes/additions have affected the brainCloud API:

  • AppStore Service
    • New AppStore Service for querying products / pricing / promotions, and performing in-app purchases.
    • The product / pricing / promotions APIs are identical to the Product Service versions – but the IAP APIs are all new!
  • Group Service
  • Leaderboard Service
  • Product Service
    • Important: The Product Service is being deprecated in favour of the new AppStore and VirtualCurrency services.
    • The service and its APIs will continue to work until July 1st, 2020.
    • There is a new compatibility flag in the portal under Design | Core App Info | Advanced Settings, which controls how purchase transactions are written to the database. Keep [x] Enable legacy Purchase Collection support checked if your app uses the old Product APIs, or a mixture of the old Productand new AppStoreAPIs. New apps that will only use the new AppStore APIs can feel free to clear that flag.
    • Although deprecated, we did add the missing cloud-code version of the VerifyItunesReceipt() back to the service (for those who need it!)
  • Presence Service
    • There is an all-new Presence service. Check it out!
  • Tournament Service
  • VirtualCurrency Service
    • New VirtualCurrency Service for currency operations. The operations are largely the same, with a bit of clean-up.

Miscellaneous Changes / Fixes

  • Updated libraries
    • All libraries have been updated with the latest API enhancements (with a few exceptions). Go get ’em!
      • C# / Unity – fully up-to-date for 3.9
      • Unreal – fully up-to-date for 3.9
      • C++ – fully up-to-date for 3.9 (though UWP and Nuget packages are outstanding)
      • Java – fully up-to-date for 3.9
      • JavaScript – fully up-to-date for 3.9
      • Objective-C / Swift – fully up-to-date for 3.9
      • AS3 – does not include RTT or RTT-related features (Chat, Presence, Lobbies) but otherwise supports all 3.9 APIs
  • Documentation updates
    • API references have been updated for 3.9
  • Important Fixes
    • BCLD-3513 – Calling RemoveMember on a lobby instance that only has 1 member causes a null pointer exception
    • BCLD-3388 – When receiving a peer currency reward from an xp upgrade, the peer currency balances were not being returned
    • BCLD-3321 – Wrong error code returned for invalid lobby id
    • BCLD-3265 – Unreal and objective-C – fix set profileId after merge call
    • BCLD-3348 – ‘View tutorials’ link in Portal was broken
    • BCLD-3217 – Improved RETRY and PACKET_IN_PROGRESS handling for Unity client library
    • BCLD-3211 – Improved RETRY and PACKET_IN_PROGRESS handling for JavaScript client library
  • Plus miscellaneous fixes and performance enhancements…