Big things are happening with brainCloud in 2020. Here’s what you will find in 4.5.

The executive summary:

• Shared Cloud Code Scripts (beta)
• Global Files V3 API (beta)
• Custom Entities Official Release + Templates!
• Improved Room Server Support for Unity and Unreal!
• Facebook Graph API v3.2
• New (better!) Batch User Processing API
• Updated UTC-based calls in Client Libs (see note immediately below)
• and more!

Release Highlights

Shared Cloud Code Scripts (beta)

At long last, our initial version of shared scripts is available for use! No more copy-and-pasting functions from script-to-script or loading them into custom properties! 

Starting in Release 4.5, to include another script, you simply use the new bridge.include(“scriptname.ccjs”) operation.

For example – say you have this script:

MathFunctions script

function sumNums( num1, num2 ) {
  return (num1 + num2);  
}

function prodNums( num1, num2 ) {
  return (num1 * num2 );  
}

You can include it from another cloud code script very simply:

"use strict";

bridge.include("MathFunctions.ccjs");

function main() {
   var response = {};
   response.answer = sumNums(data.number1, data.number2);
   return response;
}

main();

The following rules apply:

• A script can import multiple scripts (of course!)
• The scripts must all be present within the app… (i.e. no including scripts from other apps)
• bridge.include() calls must come first in a script. The only lines allowed to be before bridge.include() are blank lines, // comments, and/or the ”use strict”; directive
• The extension is ignored by the call – but we recommend you append .ccjs anyway ← this may be helpful in the future (we have plans!) 

Note – we consider this a beta release. The syntax is safe (feel free to use it!) – but there are a few more kinks to work out in future releases, namely:

• we don’t yet support arranging the scripts into sub-folders (coming soon!) 
• we haven’t yet determined the best way to adjust our cloud code pricing. This capability will change the way devs use our scripts – opening the door to larger, more powerful scripts. We will need to adjust our pricing to accommodate the changes to server resource utilization. As always, anything we do will be cost-effective and elastic for our customers!

Global Files V3 API (beta)

We’ve got a new version of our Global Files API, with some significant improvements:

• Support for Folders
• Support for Uploads (i.e. migrating uploaded User Files → Global Files)
• Full File Management API

Important notes:

• Uploading of files is accomplished by Uploading a User File, and then migrating it to V3 Global Files. Note that we also included a method for migrating to the legacy Global Files as well.
• The V3 API is a clean break from the older Global Files / S3 API – you can use either API (for now), but files are not shared between the two.
• The V3 API does not have Design Portal support yet – so, for now, you would need to use the APIs to upload files, create directories, etc.
• V3 Global Files are also not currently included in imports/exports and deploys.

Custom Entities – Official Release + Templates!

Custom Entities are now fully live in brainCloud (yay!) – which unfortunately means that we will now begin charging for them (boo!). For pricing details, see our Deep Data Pricing article.

Note – as part of this change, access to Custom Entities now requires a Plus plan. We needed to make this change due to the Custom Entity feature’s ability to handle very large datasets (even in Development) – which could incur very large storage and backup costs. Note that the $4.99 Development Plus plan does include support for Custom Entities.

As a refresher, Custom Entities are our new, super-charged improvement to both Global Entities and User Entities.

Custom Entities offer:

• Custom Indexes for super-fast lookups
• Deployment support for easy migration of entities between Dev and Prod apps
• Owned vs. Un-Owned variations
• ACL support
• Time-to-live (TTL) support
• Import / Export Support
• Both Global and User Data Editors

And now – JSON Templates! You can now add a template for the data section of your type, along with a convenient field description. You can even use markdown! Super convenient when manually creating / editing entities!

Misc Changes

But wait – there is more! Release 4.5 also includes the following:

• Improved Unity and Unreal Room Server support  –  Now with spiffy new S2S libraries. Check out the all-new docs for creating Room Servers using Unity and Unreal.
• Facebook Graph API upgrade – we have updated our backend to utilize Facebook Graph API v 3.2
• Batch Improvements – we have added a new Batch User Processing call that allows you to specify a script to run once all of the specified users have been processed. 
• RTT Optimizations – Improved Event and Disconnect handling
• Deep Data billing – usage billing for advanced data usage. Details in this article.

Portal Changes

We’ve made the following portal changes:

Design

• Core App Info | Application IDs
  • Removed the [x] Enable Facebook Scores setting from the Facebook Platform options. Facebook’s APIs no longer support this functionality.
• Cloud Data | Custom Entities
  • Added the ability to define (and describe) custom JSON templates for entity data.
  • Important: A Plus Plan is now required to access this screen.
• Gamification | Achievements
  • Removed the [Facebook Register Achievements] button from the main screen, as well as the Facebook specifics from the sub-screens. Facebook’s APIs no longer support this functionality.

Monitoring

• Global Monitoring | Custom Entities
  • Updated the Create and Edit entity screens to support the new JSON templates.
  • Important: A Plus Plan is now required to access this screen.
• User Monitoring | Custom Entities
  • Updated the Create and Edit entity screens to support the new JSON templates.
  • Important: A Plus Plan is now required to access this screen.

Reporting

• Analytics
  • Split out and corrected the Total Users vs. Total Dormant Users stats.
• API Usage
  • Added a new Deep Data Usage section.

General

• Login / Registration
  • The Registration page is now more mobile-friendly.
• Personal Preferences
  • Timezones are now specified via a region/city – hopefully no more issues when Daylight Savings Time changes!
• Portal Version
  • We are now prefacing our Master Release versions with “R”. 

API Changes

As mentioned in the executive summary, we found inconsistencies in the client-implementation of some of our time-based calls. 

The following methods have thus been deprecated in the 4.5 libraries:

• Leaderboard
  • PostScoreToDynamicGroupLeaderboard() – deprecated in favor of PostScoreToDynamicGroupLeaderboardUTC()
  • PostScoreToDynamicLeaderboard() – deprecated in favor of PostScoreToDynamicLeaderboardUTC()
  • PostScoreToDynamicLeaderboardDays() – deprecated in favor of PostScoreToDynamicLeaderboardDaysUTC()
• Tournament
  • PostTournamentScore() – deprecated in favor of PostTournamentScoreUTC().
  • PostTournamentScoreWithResults() – deprecated in favor of PostTournamentScoreWithResultsUTC()
• Script
  • ScheduleRunScriptUTC() – deprecated in favor of ScheduleRunScriptMillisUTC()

In addition, the following new methods have been added to brainCloud API:

• Bridge
  • There is a new GetAppVersion() call in the bridge to retrieve the version of your app (as provided by your app to the client library). Handy!
• GlobalFile (New V3!)
  • Client APIs – GetFileInfo(), GetFileInfoSimple(), GetGlobalCDNUrl(), GetGlobalFileList(), 
  • The following methods are available from cloud-code only:
    • File retrieval – SysGetGlobalCDNUrl(), SysGetGlobalFileList(), SysGetFileInfo(), SysGetFileInfoSimple()
    • File management – SysCopyGlobalFile(), SysDeleteGlobalFile(), SysDeleteGlobalFiles(), SysMoveGlobalFile()
    • Folder management – SysCreateFolder(),  SysDeleteFolder(), SysLookupFolder(), SysMoveFolder(), SysRenameFolder()
  • Special mention – the SysMoveToGlobalFile() method can be used to copy/move a UserFile to a GlobalFileV3 file.
• S3 Handling
  • We’ve added SysMoveToLegacyGlobalFile() to support moving a User File to the Legacy Global File system.
• Script
  • There are 3 new S2S APIs for running batch scripts on users with a completion scriptat the end:
    • RunBatchUserScriptAndCompletionScript() targets all users
    • RunBatchUserScriptForProfilesAndCompletionScript() targets specific users (specified via profileId)
    • RunBatchUserScriptForSegmentsAndCompletionScript() targets the users in specific segments.

Miscellaneous Changes / Fixes

• Updated Client Libraries
  • All supported libraries have been updated with the latest API enhancements. Go get ’em!
  • Important Client Library Fixes
    • BCLD-5686 – Automatically remove the trailing “/” if set by the client in serverURL
    • BCLD-5718 – UTC fixes for all libs
    • BCLD-5772 – Change the comms packet timeouts from 15,10,10 to 15, 20, 35, 50
• New S2S Libraries
  • New C#/Unity and Unreal S2S Libraries
• Documentation updates
  • All new 4.5 APIs added to API Ref
  • New Knowledgebase Articles:
    • Custom Multiplayer Server with Unity
    • Custom Multiplayer Server with Unreal
    • Custom Entities
• Important Server Fixes
  • BCLD-5749 – Special characters in email or universal ID addresses were not being encoded correctly during URL creation
  • BCLD-5748 – Both “identifier” and index keys (keysJson keys) need to allow period (.) in the Custom Entity configs
  • BCLD-5787 – ‘Reference Price’ displayed in the Transaction screen is incorrect
  • BCLD-5743 – Update APIServer containers to Tomcat 8.5.51 to fix Ghostcat vulnerability
  • BCLD-5620 – Add cloud code support for various PushNotificationService methods
  • BCLD-5779 – Remove double logging of tournament service errors
  • BCLD-5763 – Optimized RTT Event Handling
• Plus miscellaneous fixes and performance enhancements…

We have bad news and good news.

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:

• In the Amazon Developer Services portal
  • 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.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
• purchases – customer purchase notifications ← fun!

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:

1. 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.
2. 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).
3. 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 Deletion Queries – 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
  • You’ll find our new Amazon IAP tutorial here
• Important Fixes
  • BCLD-5722 – Unreal blueprint tutorial on website is out of date for UE 4.24. will crash on initialize app.
  • BCLD-5724 – Unreal C++ tutorial on website is out of date, method getInstance() doesn’t exist in BrainCloudClient class.
  • BCLD-6072 – Price entries can be created for products without an appstore defined with it
  • BCLD-5960 – Users should not be able to use ‘.’ (dot) in external auth type
  • BCLD-6105 – Should be able to edit Scheduled Promotion without setting it’s start time to the future
  • BCLD-6090 – brainCloud java client sends empty RTT ping packets that cause immediate disconnect from event server
  • BCLD-5922 – Matchmaking process is blocked by room/relay server spin-up
  • BCLD-5909 – User counts on Manage | Apps and Reporting | Analytics don’t exclude deleted users OR include users created via UserService
  • BCLD-5738 – Java RelayComms double queue UDP ordered relay packets
• 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 support before 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.)

Apologies for the confusion!

brainCloud 4.4 kicks off a year of big updates to brainCloud. We hope you like where we’re headed!

Release Highlights

Custom Entities

Release 4.4 brings the full power of Custom Entities to brainCloud. As you may recall, Custom Entities are like Global Entities + User Entities combined, and then super-charged! You get all the features of our standard entity systems (with ownership, ACL, time-to-live, and concurrency versioning) – plus support for Custom Indexes (i.e. much faster!) and Deployment Migration (i.e. more convenient!). 

New features in 4.4 include:

• New Custom Entity Editor available under Global Monitoring
  • With full searching and Import/Export functionality
• Bonus Custom Entity Editor available under User Monitoring
  • Easily view/edit the entities owned by a specific user!

In addition, you’ll find the Custom Entity configuration screens have moved. We have created a new section called Cloud Data for them under Design – to give them better overall visibility.

Note – in the future Custom Entities will be a Plus Plan feature – but for now, Custom Entities are available to everyone!

Cloud Code Improvements

We have big plans for Cloud Code in 2020 – but to start things off, we have a few small improvements:

• Upgraded JavaScript Engine – we’ve updated to Rhino Engine 1.7.12 for additional features, performance, and stability.
• EcmaScript 6 Support – the updated Rhino engine enables new language features. Rhino isn’t fully ES6 compliant, but it’s miles ahead of the level of support that we had before. 

Note – for compatibility reasons, the new ES6 support is disabled by default for existing apps. You can enable this feature by going to the new Cloud Code settings section of the Design | Core App Info page.

Sign in with Apple

We have added Sign in with Apple support to brainCloud. This works similarly to all of our other authentication types.

To take advantage of this feature, be sure to grab the latest brainCloud 4.4 Client Libs.

Faster API Reference

This one is a big quality-of-life improvement.

As you know, as the brainCloud API has grown (over 400+ API calls and counting!) – the time to load our API Reference had gotten slower and slower.

We put the devs on it – and they were able to optimize it for a huge performance improvement. Now instead of taking 60+ seconds to load – it opens in 5-10 seconds from cold – even faster if you have it cached. 

Check it out – you’ll find it in the usual location here. 

Misc

As usual, a few additional requests have made it into this release:

• Google OpenID Support – we have added support for Google’s new (modern) OpenID authentication system
• Item Catalog Deployment Option – you can now opt-out of updating your Item Catalog during an app deployment. This feature allows you to maintain a more dynamic marketplace where your Item Catalog is managed directly in your live app, instead of strictly publishing updates from dev → prod.
• New and fixed API calls – we have fulfilled a bunch of customer requests for specific API calls. Check the API Changes sections – we hope your favorites are there!

Portal Changes

We’ve made the following portal changes:

Design

• Core App Info | Advanced Settings
  • We have added a new Cloud Code section, where you can enable the new ES6-level JavaScript support
  • We have also added a new compatibility flag, Return legacy-format Multi Social Leaderboard results, to preserve the old behavior for the GetMultiSocialLeaderboard() call for existing apps.
• Cloud Data | Custom Entities
  • We’ve moved the Custom Entities configuration screen out from under Custom Config.
  • You can now specify an identifier field to use to label your objects when viewing them in the Entity Editor lists.
  • There is also a new Monitor option on the Action menu, that jumps you into Global Monitoring to view the entities of that type.

Monitoring

• Global Monitoring | Custom Entities
  • The new Custom Entity Editor screens in Global Monitoring allow you to view and edit all of the custom entities of your application.
  • You can search for entities using the Filter dropdown.
  • You can import and export entities from JSON files.
• User Monitoring | Custom Entities
  • We also allow you to view Custom Entities at the user level
  • In this view, you only see owned collections – and specifically, only entities that are owned by the selected user.

General

• We have re-ordered the screens under Global Monitoring to be alphabetical.

API Changes

The following calls have been added to the brainCloud API:

• Authentication
  • New AuthenticateApple() call for Sign in with Apple support.
  • New AuthenticateGoogleOpenId() call for Google’s OpenID authentication.
  • Improved Password Reset calls (with control over when the URL links expire)
    • ResetEmailPasswordWithExpiry()
    • ResetEmailPasswordAdvancedWithExpiry()
    • ResetUniversalIdPasswordWithExpiry()
    • ResetUniversalIdPasswordAdvancedWithExpiry()
  • Note that we have deprecated the older password reset calls where you do not explicitly set an expiry.
• CustomEntity
  • Added SysUpdateEntityOwner() call to migrate custom entities between users. 
• GlobalApp
  • SysUpdatePropertyString() and SysUpdatePropertyJSON() have been added to both Client and S2S Cloud Code interfaces for devs building offboard tools.
• GlobalEntity
  • Added S2S Cloud Codeimplementations for the following missing calls
    • DeleteEntity()
    • GetRandomEntitiesMatching()
    • IncrementGlobalEntityData()
    • MakeSystemEntity()
    • UpdateEntity()
    • UpdateEntityAcl()
    • UpdateEntityOwnerAndAcl()
    • UpdateEntityTimeToLive()
• Identity
  • New AttachAppleIdentity(), DetachAppleIdentity() and MergeAppleIdentity() calls
  • New AttachGoogleOpenId(), DetachGoogleOpenId() and MergeGoogleOpenId() calls
• Leaderboard
  • Fixed GetMultiSocialLeaderboard() so that it doesn’t return friends that haven’t played on any of the leaderboards requested. There is a new compatibility flag to preserve the old behaviour.
  • Added SysResetNeverLeaderboard() to arbitrarily reset/rotate leaderboards. 
• PlayerState
  • New UpdateTimeZoneOffset() and UpdateLanguageCode() calls – useful in certain scenarios. 
• PushNotifications
  • Added the following missing methods to the S2S Cloud Code proxy:
    • DeregisterPushNotificationDeviceToken()
    • ScheduleNormalizedPushNotificationUTC()
    • ScheduleNormalizedPushNotificationMinutes()
    • ScheduleRawPushNotificationUTC()
    • ScheduleRawPushNotificationMinutes()
    • ScheduleRichPushNotificationUTC()
    • ScheduleRichPushNotificationMinutes()
    • SendNormalizedPushNotification()
    • SendRawPushNotification()
    • SendRichPushNotification()
    • SendRichPushNotificationWithParams()
• Script
  • Added GetScheduledCloudScripts() to the Client libs – it was previously Cloud Code only. 
  • Added GetRunningOrQueuedCloudScripts() call (to both Client and Cloud Code) 
• User
  • New password reset calls with better control over when the URLs expire:
    • SysSendPasswordResetEmailWithExpiry()
    • SysSendPasswordResetEmailAdvancedWithExpiry()
    • SysSendPasswordResetUniversalIdWithExpiry() 
    • SysSendPasswordResetUniversalIdAdvancedWithExpiry()

Bonus API

In addition, we’ve added a new Cloud Code Utility method that can be used to efficiently create RSA signatures (since doing so through raw Javascript is pretty slow).

The new method can be found in the Bridge Utility service – i.e. bridge.utils().signRSASha256(). See the APIRef for more info!

Miscellaneous Changes / Fixes

• Updated libraries
  • We’ve been busy adding our Relay Comms APIs to all the missing libraries. Unity/C#, Unreal, Java, and JavaScript are now good. C++ / Objective-C / Swift support is still outstanding, but coming soon.
  • The libraries have otherwise been updated with the latest 4.4 APIs. Grab them while they’re hot! 
• Documentation updates
  • New Faster API Reference!
  • Plus we’ve documented all the latest APIs
• Important Fixes
  • To-be-compiled
• Plus miscellaneous fixes and performance enhancements…

This is a small release that addresses some specific customer requests.

Release Highlights

Quest Management API

We’ve added an API for managing Quests. The API is available directly via S2S, and also via cloud-code.

In doing this work, we cleaned up two aspects of Quests:

• We added a new title field to Quests – to make them easier to manage
• We have also made the new APIs return the embedded milestones (which we call tasks) in an array field called tasks now instead of the old milestones field. 

To prevent issues with existing apps, a new compatibility flag has been added to control this behavior (accessible from the Design | Core App Info | Advanced Settings) page. The compatibility flag defaults to on for existing apps.

The Quest Management API methods are part of the Gamification service.

Milestone Management API

And, if you can edit Quests, it only makes sense that you can edit Milestones as well! So there is now an API for that as well.

The Milestone Management API methods are part of the Gamification service.

Reset Password APIs

We have added some new cloud-code accessible APIs for triggering password reset emails. These APIs are mostly useful if you are building a management portal for your app.

You’ll find these new APIs in the User service.

Custom Entity Paging

Finally, we’ve tweaked our Custom Entity paging APIs to be more consistent with the other Entity APIs. They now take a single context object instead of requiring each of the component parts to be sent in separately.

Since Custom Entities are still in beta, we’re being more aggressive than usual about replacing those old methods. The old methods are being removed immediately from the 4.3.5 libraries. That said, moving to the new versions is super simple, and the old libs will continue to work for you for now.

Portal Changes

There aren’t a lot of portal changes in this release.

Design

• Core App Info | Advanced Settings
  • A new compatibility flag, Return milestones field instead of tasks field for older client Quest APIs, has been added. As usual, this flag defaults to enabled for existing apps, and disabled for new apps.
• Gamification | Quests
  • Quests now have a separate title from the description field
  • When editing pre-existing Quests, the title will default to the questId.

API Changes

The following changes/additions have affected the brainCloud API:

• CustomEntity
  • New Paging calls – GetEntityPage(), GetEntityPageOffset(), SysGetEntityPage(), SysGetEntityPageOffset()
• Gamification
  • New Quest Management API calls – SysCreateQuest(), SysReadQuest(), SysUpdateQuest(), SysDeleteQuest(), SysAddQuestTask(), SysUpdateQuestTask(), SysDeleteQuestTask(), SysReorderQuestTasks(), SysGetQuestPage(), SysGetQuestPageOffset()
  • New Milestone Management APIs calls – SysCreateMilestone(), SysReadMilestone(), SysUpdateMilestone(), SysDeleteMilestone(), SysGetMilestonePage(), SysGetMilestonePageOffset()
• User Service
  • New APIs for triggering Password Reset emails – SysSendPasswordResetEmail(), SysSendPasswordResetEmailAdvanced(), SysSendPasswordResetUniversalId(), SysSendPasswordResetUniversalIdAdvanced()

We have deprecated the following methods:

• CustomEntity
  • GetPage(), GetPageOffset(), SysGetPage(), SysGetPageOffset() – replaced with the new versions described above, which are more consistent with our other Entity APIs.

Miscellaneous Changes / Fixes

• Updated libraries
  • There are only two new Client-library API calls – the new GetEntityPage() and GetEntityPageOffset() calls of the CustomEntity service. All other calls are cloud-code only.
• Documentation updates
  • The new API calls have been added to the APIRef
• Important Fixes
  • Uploaded File Types – we have enhanced brainCloud to automatically assign content types based on file extensions when uploaded via the portal, instead of blindly setting everything to the generic application/octet-stream content type. The old behavior was problematic for some devs when dealing with apps running in Internet Explorer. 
• Plus miscellaneous fixes and performance enhancements…

Release 4.3 fulfills a bunch of community requests – there is something for everyone!

Release Highlights

Geo Matchmaking

We have enhanced our Online Matchmaking support to automatically match players up into lobbies in the best server regions (for them).

The process is simple, and works like this:

• When a lobby is first created, it is assigned to the region closest to the user that initiated it
• As users look for lobbies (i.e. online matchmaking), the lobby’s rating and region location (i.e. ping data) are automatically considered

Essentially, the best matching (rating-wise) lobby in an acceptable region will be automatically selected.

To utilize geo matchmaking:

• Create lobby types with servers in multiple regions
• Specify both ping data and rating in the compound matchmaking algorithm (see below)

Example algo json object for geo matchmaking:

{
  "strategy":"compound",
  "algos":[
    { "criteria":"ping", "strategy":"absolute", "alignment":"absolute" },
    { "criteria":"rating", "strategy":"ranged-percent", "alignment":"center" }
  ],
  "compound-ranges":[
    [ 40, [ 10, 20.5, 80 ] ],
    [ 70, [ 20, 20.5, 80, 160 ] ],
    [ 140, [ 80, 160 ] ],
    [ 210, [ 80, 160 ] ]
  ]
}

Custom Entity (Beta) Migration

We continue to improve our support for custom entities.

As you may-or-may-not-know, Custom Entities are an improved version of Global Entities and are available to users of our Plus Plans. 

Custom Entities allow developers to build data-rich applications with much larger and more complex data-sets. The power comes from storing each entity type in its database collection and allowing the developer to define custom indexes unique to that entity type.

This release adds several new features to the mix:

• New screen under Design | Custom Config | Custom Entities for defining custom entity types, and the indexes associated with them. (Before this you had to use the API to do this)
• You can now mark a Custom Entity to be migrated automatically during app deployment (i.e. when pushing an updated configuration from the development version of your app to the production version). Note that only un-owned entities can be migrated.

Next up: we’ll be editing a Custom Entity editor screen to Global Monitoring soon, so you’ll be able to create and edit custom entities directly.

Set-top Handoff API

We have added a second, more flexible hand-off API that can be used for authenticating brainCloud apps on devices with limited inputs (like the Apple TV or a VR headset).

The API enables a use case where:

• the user can log into a brainCloud app via a normal smartphone login
• the smartphone app generates a simple set-top handoff code via CreateSettopHandoffCode() cloud code API. The handoff code’s composition, length, and duration that it’s enabled is specified by the app.
• the user then enters the code into the Apple TV app or VR headset, which authenticates the user via the new AuthenticateSettopHandoff() API call

User Service

By popular request, we’ve added a new User service to brainCloud.

This service provides the following advanced, cloud-code only APIs:

• SysCreateUser*() – useful in certain app scenarios. Allows an app to dynamically pre-create a user account (separate from the normal account during user login/registration)
• SysGetPage() / SysGetPageOffset() – allows a cloud code script to iterate through the users in an app.

Note that for system performance reasons, we have restricted the fields that can be used when querying the users to iterate through. These restrictions can be lifted in special circumstances for apps that will have constrained user sets (i.e. a few thousand users or less).

Pro-tip: Apps with a need to iterate through larger groups of users in more interesting ways are encouraged to create an owned Custom Entity for each user.

Misc Additions

The following additional tweaks (mostly from customer requests) have made it into release 4.3:

• User Items screen – we’ve added a new screen to User Monitoring to view the contents of the user’s inventory.
• Dynamic group leaderboards – we’ve added a new PostScoreToDynamicGroupLeaderboard() call to allow group leaderboards to be created on the fly
• Autojoin across multiple group types – the new AutoJoinGroupMulti() call allows you to specify a list of group types to choose from
• Reset quests – we’ve added ResetQuests() and ResetAllQuestsAndMilestones() API calls
• Counts APIs – we’ve added two methods to the GlobalApp service to retrieve some raw metric data about your app (DAU, MAU, that sort of thing). These APIs are cloud-code only.
• Updated client timeouts – the client libs automatically retry operations if they timeout – but the default timeouts were a bit low for some long-running scripts (which can go up to 60 seconds or more). So we have adjusted them to better we’ve updated the default client library retry timeouts from [15s, 10s, 10s] to [15s, 20s, 30s, 50s]. This change should be transparent to your app.
• Bundle compression – we have added optional bundle compression to our Unity libraries. It is currently off-by-default but can be enabled by the developer.
• OKTA authentication support – you can now write apps that implement OKTA authentication via our External Auth mechanism. To validate the JWT token passed in, simply use the new verifyOktaJwt() method that we have added to the Identity service. 
• Cloud code editor extension change – we’ve changed the default extension for our cloud code scripts from .js to .ccjs (i.e.  cloud code javascript) – this mostly makes it easier for our sites and support teams to share example script. Pro-tip – configure your IDE to treat .ccjs files as javascript!
• Facebook Graph API v 2.11 – support was added as a patch to 4.2 actually… (added previously as a 4.2.X patch)
• Google Play Service V3 – the system is now using latest (V3) APIs… (added previously as a 4.2.X patch)

Portal Changes

The following changes have been made to the portal:

General

• Branding/Themes
  • Pretty! We’ve greatly improved the customizability of the working area of the portal. You will see the impact of this with more varied themes as we go from release to release… (and more branding flexibility for our private instance licensees)

Design

• Custom Config | Custom Entities
  • This new screen allows you to define Custom Entity types, and the custom indexes that go along with them.

Monitoring

• User Monitoring | User Items
  • New screen allows you to view and/or delete the items owned by a user
• User Monitoring | Logs
  • We’ve added an Elapsed Time column to the user logs to show how much server-time was spent processing a request bundle

API Changes

The following changes/additions have affected the brainCloud API:

• Authentication
  • AuthenticateSettopHandoff() call added – allows users to login using simple codes
• Gamification
  • Added new ResetQuests() and ResetAllQuestsAndMilestones() calls to cloud code – helpful for testing and debugging
• GlobalApp
  • Added SysGetDailyCounts() call to return the counts for your app for a single day
  • Added SysGetMonthlyCounts() call to return the counts for your app for the specified calendar month 
• Group
  • AutoJoinGroupMulti() call added – enables joining a random group selected from multiple group types
• Identity
  • CreateSettopHandoffCode() call added – creates a code that can be used to log the user in via AuthenticateSettopHandoff()
  • VerifyOktaJWT() call added for verifying OKTA JWT tokens
• Leaderboard
  • PostScoreToDynamicGroupLeaderboard() call added to allow group leaderboards to be dynamically allocated
• User
  • Create users in cloud-code via the new SysCreateUserEmailPassword(), SysCreateUserUniversalId() and SysCreateUserExternalAuth() calls
  • Page through your app’s users via the new SysGetPage() and SysGetPageOffset() calls

We have also deprecated the following methods:

• Gamification
  • Deprecated ResetMilestones() in the client libs – this method is now cloud-code only, like the new ResetQuests() and ResetAllQuestsAndMilestone() calls

Miscellaneous Changes / Fixes

• Updated libraries
  • All libraries have the new 4.3 client APIs
  • All libraries also have the new connection timeout values
  • The Java and C++ libs have been updated with geo/ping-data support – meaning that all libs except Objective-C/Swift and AS3 support this now.
  • The Unity library now supports bundle compression for sends and receives. It is disabled by default.
• Documentation updates
  • The docs have been enhanced with the latest API calls.
• Important Fixes
  • <to-be-compiled>
• Plus miscellaneous fixes and performance enhancements…

Release 4.2 contains the first versions of some new heavy-hitter features. Read on for details!

Release Highlights

Item Management

We are very pleased to introduce the first iteration of brainCloud’s new Item Management system – which incorporates both an ItemCatalog service to manage the master catalog of items, and a UserItems service to manage the list of items that users own.

Together with a new Catalog Editor, these services make it easy to create experiences where users can be awarded, purchase, sell, trade and consume a rich variety of items (with custom behaviours).

Key features of this system include:

• Localizable names and descriptions
• Item categories and tags for organization
• Item pricing (in multiple virtual currencies)
• Custom item meta-data
• Item “use” management
• Activate-able status effects
• Cool-down and recovery times
• Stackable items
• Upload images and assign resource/asset tags
• Publishing states – draft, published, retired and revoked
• Deployment integration
• And with brainCloud’s new Blockchain Framework, you can even trade items on the Blockchain! (see below!)

Custom Entities (beta!)

brainCloud already has some great APIs for managing data in your apps – but due to the challenges of keeping things light and scalable, none of them offer the true flexibility needed for heavy data-oriented applications.

Our existing Global Entity system, for example, only indexes entities by the fixed entityIndexedId. Although fine for simple applications – in most scenarios this means that Global Entities don’t scale efficiently past 1000 objects.

Our Custom Entities system is different, in that it allows the developer to define multiple, custom indexes per entity type. This totally opens the door to much richer applications, with more intense data needs.

Note – because it’s brainCloud, Custom Entities still include:

• ACL ownership
• TTL
• createdAt, updatedAt timestamps
• concurrency versioning

Note – this is a beta release, so there are some limitations:

• We don’t have a web UI yet – so you cannot view / edit / delete custom entities in our Design Portal. You can access them via the API Explorer, of course.
• We don’t yet support importing / exporting / pushing of custom entities. So basically custom entities are currently trapped within the apps that created them (for now).

We plan to address these limitations very soon. And also note, when Custom Entities is released it will be a premium feature with additional data storage charges. Details coming soon.

And that’s not all. We have big plans for Custom Entities going forward – so stay tuned!

Timed Status Effects

When building our Item Management system we thought it would be nice to include status effects – as in, when you use an item, you might trigger a status effect like “double-xp” or “invulnerability” for a period of time.

Once we got to implementing things though, we realized that this status system would be useful on its own as well – so we’ve made it accessible via new APIs in the PlayerState service.

It’s super-simple to use. Just apply a “named” status effect to the user via the SetUserStatus() call – specifying a duration that it should be applied for, and optionally some custom JSON. We’ll save that state – and return it if you call GetUserStatus() – as well as automatically when the user logs in.

Note – brainCloud won’t pro-actively notify you that a status has expired. The app should set it’s own timers based on the data returned by the APIs.

Blockchain Integration

We’ve been busy adding blockchain support deep into the heart of brainCloud.

This is part of our continuing efforts to ensure that brainCloud is the best foundation for your apps – both today and for the future! 

Elements of the blockChain integration in 4.2 include:

• Blockchain Integration Framework (BIF) – brainCloud has been enhanced with a new framework to allow connections to multiple blockChain technologies. Currently EOS integration is in place (more will come soon!)
• Blockchain configuration – attach a blockchain configuration to an app. Currently limited to a single blockchain per app, but we may enhance that in the future.
• Blockchain Identities – attach a users public key to a user’s profile – used to identify and modify items that the user owns on the blockchain ← note, it’s up to the client app to ensure that the user is who they say they are!
• Item Management Blockchain Sync – items can be published to and traded on the blockchain – with updates automatically synced in brainCloud
• Blockchain Entity Support – brainCloud’s new Custom Entities are built to support integration with the BIF for blockchain-based ownership management
• Blockchain Purchase Support – with the key Blockchain Integration and Blockchain Identity components now in place, brainCloud is now ready to support custom blockchain-based purchases (either via Item Trades or custom AppStores)

Obviously, this is just the beginning. Stay tuned as we evolve our blockchain support in future releases!

Kafka Integration

brainCloud now offers Kafka integration in addition to our pre-existing Segment integration for DataStream events.

With Kafka and Segment both supported out-of-the-box, there are literally hundreds (if not thousands) of systems that you can hook up to your brainCloud apps for deeper data analytics, data mining, etc. 

Other Features

But wait – there is more! brainCloud 4.2 also includes these goodies:

• Crash Reporting – new API calls for sending crash reports to DataStream services like Segment and Kafka.
• New platforms! – brainCloud private instances now support both Google Cloud Platform and Microsoft Azure.
• External lookups! – ability to lookup users via the External ID in User Monitoring

Portal Changes

We’ve made the following portal changes:

Design

• Integrations | Blockchain
  • A new screen where you can configure the blockchain integration settings for your app
• Integration | Manage Integrations
  • Kafka has been added as a new DataStream destination
• Item Management | Catalog
  • New screen for creating your app’s item catalog

Monitoring

• Group Monitoring | Group Entities
  • The group entity editor has been greatly improved!
• User Monitoring | Select User
  • You can now look-up users via their External Auth id (if they have one) 

API Changes

The following changes/additions have affected the brainCloud API:

• Authentication
  • AuthenticateExternal – We’ve added the ability for External Auth scripts to override the externalId that will be stored, and to even provide the specific profileId to load. More details in the Advanced section of the External Authentication overview page in API Docs.
• DataStream
  • New CrashReporting API has been added. Send crash reports to your back-end system for further analysis.
  • For more information, see the DataStream service documentation
• [New!] Item Catalog
  • These APIs allow devs to read and modify the central item catalog
  • Purchases and other operations are handled via the User Items Service (below)
  • For more information, see the ItemCatalog service documentation
• Player State
  • New Timed Status Effect API methods have been added to the Player State service
  • For more information, see the PlayerState service documentation
• [New!] User Items
  • This service provides the functionality for purchasing, selling, trading, and using items
  • For more information, see the UserItem service documentation

Miscellaneous Changes / Fixes

• Updated libraries
  • The 4.2 libraries have the latest APIs – and will be release very soon – stay tuned!
  • C#/Unity
    • Updated HTTP libraries (note, wrapped in the Braincloud namespace, so they shouldn’t conflict with anything)
    • Added BC_DEBUG_LOG_ENABLED macro for better log control, and improved profiler performance
    • Important: Unity folder structure has been changed. Clients will need to delete their brainCloud plug-in and re-import it to properly update the folder structure on older projects. The brainCloud Folder needs to be directly in the Assets folder. Changes were made because the plugin’s Resources folder was conflicting with the Unity Resources folder, and messing with some build systems. Thus we have restructured our assets and renamed our resources folder to BCResources to compensate.
  • Javascript
    • Ping data APIs now supported (for geo matchmaking)
  • AS3
    • 4.2 version coming soon.
• Plus miscellaneous fixes and performance enhancements…

Note – you can also view the highlights in our new Roadmap!

Release Highlights

Group Leaderboards

Although brainCloud has long supported filtering leaderboards to group members, it has not supported true Group Leaderboards – where each entry in the leaderboard represent’s a Group’s (not a Player’s) score. Until now that is.

Now, when creating a leaderboard, you will first choose whether it is a Player or a Group Leaderboard. 

Important notes regarding Group Leaderboards:

• Any member of a group can post a score on behalf of their team
• Post group scores via the new PostScoreToGroupLeaderboard() method. Additional new calls are described in the API section (below).
• Group Leaderboards cannot be used as the basis for Tournaments or Divisions

Note – we are considering adding Group Tournament and Division support in the future. If it is important to you, vote for it in our Roadmap!

Group Enhancements

We have made a bunch of enhancements to Groups and the Group APIs to go along with the new leaderboard support:

• Group Summary Data – we have added the concept of summary data to groups. This is an additional bit of custom JSON, associated with your groups, that can be read by non-members. This is useful when searching for groups with specific qualities and also when viewing group leaderboards ← the summary data gets returned in the leaderboard calls
• Enhanced Searching – when searching for groups, you can now include additional fields (isOpenGroup, updateAt, createdAt, and summaryData) in the filter and sorting clauses.
• Get Random Groups – we have added a new API call for retrieving a random selection of groups that fit the specified criteria. See GetRandomGroupsMatching().

Voting Leaderboards

Since we were already in the Leaderboard code, we thought we would cover another customer request.

Voting Leaderboards are special leaderboards where the user doesn’t post their own score – rather, a player increments the score of another player. This makes the most sense for a CUMULATIVE leaderboard (where posts from players increment a total). You can imagine using this system to allow players to vote on custom content created by other players – like custom maps layouts, etc.

Important notes:

• This technically isn’t a new type of leaderboard – it’s merely a new leaderboard call – PostScoreToLeaderboardOnBehalfOf(). Note that this call be made from Cloud Code only.
• The API does not prevent users from voting (i.e. posting on behalf of another user) multiple times. We leave that enforcement up to the app (if desired, of course).

Multi-Region Support

In V4 we introduced the ability to host Relay and Room Servers. When configuring your servers, you had the ability to choose which region to host them in.

This was a good start, but for global coverage developers would need to create individual server configurations for each of the regions they want to support. And if they’re using our matchmaking and lobby services, they would need to set up separate lobby configurations for each region as well.

Release 4.1 greatly improves things:

• You can now select multiple regions for a Room or Relay Server configuration in My Servers
• There are new Client APIs that allow you to retrieve the list of regions associated with lobby type(s), and calculate the latency (i.e. ping times) to them
• When launching a Room or Relay Server from a lobby, the Lobby Service will now automatically choose the best region for the members of that lobby

Dynamic Chat Channels

And last but not least, this release introduces a new type of chat channel.

Dynamic chat channels are special channels that any user can create and/or join. They exist only for as long as there is activity. Once the channel inactivity timeout expires (typically 30 days), the history (and the channel itself) are automatically deleted and cleaned up.

Note that developers need to manage the “membership” to the channels themselves. If a user of an app connects to a dynamic channel during a session, and you want them to reconnect the next time the app launches as well – you’ll need to save that information somewhere in your app (likely in a user entity).

Portal Changes

We have made the following portal changes:

Design

• Core App Info | Application IDs
  • Renamed “Facebook Secret” to “Facebook App Secret” to better clarify what it is
• Core App Info | Admin Tools
  • Added new options to the Deployment section to prevent overwriting the Lobbies and MyServers page settings. This is important because you very likely want to configure different performance + availability settings for dev vs. prod environments
• Cloud Code | My Servers
  • Enhanced the Room Server and Relay Server configuration screens to support multiple regions
  • Note that each region can use the default configuration settings (server size, # containers, etc); or you can override those settings on a region-by-region basis
• Leaderboards | Leaderboard Configs
  • When creating a new Leaderboard config, you can now choose between Player and Group entry types (default is Player).
  • Once the entry type has been set, it cannot be changed
  • Tournaments and Division Templates cannot be enabled for Group leaderboards
  • The entry type has been added to the Leaderboard Config list screen as well

Monitoring

• Global Monitoring | Leaderboards
  • Have been enhanced to show the results of Group Leaderboards
  • The column displayed now automatically change depending upon the leaderboard type being displayed
  • Clicking on a group id will bring you to the group.

General

• DOCS menu
  • Added a link to the new Roadmap site

API Changes

The following changes/additions have affected the brainCloud API:

• Chat Service
  • SysCreateChannel() can be used to create a new dynamic chat channel. Cloud code only.
  • SysDeleteChannel() is used to delete the specified chat channel. Cloud code only.
• Group Service
  • [New!] CreateGroupWithSummaryData() allows the creation of a group with summary data.
  • [New!] GetRandomGroupsMatching() returns a list of random groups that match the supplied criteria
  • [New!] SysChangeGroupType() changes the group type of a group. Useful for leveling up the maximum number of players in a group. Cloud code only.
  • [New!] UpdateGroupSummaryData() allows a member to update the summary data of the app. Note that the user must be the owner of the group; or the group’s data ACL must be set to “member”: 2 to perform the update.
  • [Update] ReadGroup(), GetMyGroups(), ListGroupsPage(), and ListGroupsPageByOffset() will now return the summaryData associated with groups
  • [Update] Additional fields (updatedAt, createdAt, isOpenGroup, and summaryData) can now be used as filter and sort criteria in group calls.
• Leaderboard Service
  • [New!] GetGroupLeaderboardView() and GetGroupLeaderboardViewByVersion() for retrieving the leaderboard results, relative to the specified group
  • [New!] PostScoreToGroupLeaderboard() for posting scores to group leaderboards. Note that the user must be a member of the specified group.
  • [New!] PostScoreToLeaderboardOnBehalfOf() for posting scores to a leaderboard on behalf of another player. Cloud code only.
  • [New!] RemoveGroupScore() for removing a group score.
• Lobby Service
  • [New!] GetRegionsForLobbies() retrieves a list of super-set of regions for the specified list of lobbies. Is used by the client app to determine with regions to ping test.
  • [New!] PingRegions() tells the client to ping the retrieved set of regions. Should be called after GetRegionsForLobbies() has completed.
  • [New!] CreateLobbyWithPingData(), FindLobbyWithPingData(), FindOrCreateLobbyWithPingData() and JoinLobbyWithPingData() are enhanced versions of the regular calls, with the obvious addition of ping data that the server will use to select the best region when launching a Room or Relay Server. Note that the library will automatically provide the ping data for those calls (there are no additional parameters)
  • [New!] SysSendSignal() allows cloud code scripts to send signals to members of a lobby.
  • [New!] SysDisbandLobby() allows cloud code scripts to disband a lobby.
• Tournament Service
  • [New!] PostTournamentScoreOnBehalfOf() for posting scores to a leaderboard on behalf of another player. Cloud code only.

Note that we have also made a small change to GetGlobalLeaderboardViewByVersion() and GetGlobalLeaderboardPageByVersion() to allow you to once again pass in -1 as the version id. That behaviour had regressed in 4.0. Apologies for the inconvenience!

Miscellaneous Changes / Fixes

• Updated libraries
  • All libraries have been updated for the 4.1 release! Go get ’em!
  • The Unreal Library now includes beta-level support for our Relay Communications protocol!
  • Warning – there is a known issue with Unity 2019 on IOS devices that affects brainCloud (and really any app making web requests). More info here!
• Documentation updates
  • New Roadmap Site – https://portal.productboard.com/braincloud/1-braincloud-baas-roadmap/tabs/35-coming-soon/tabs/4-coming-in-4-1
  • Significant updates to the S2S sections of the API Reference 
  • Docs updated with all 4.1 APIs
• Important Fixes
  • BCLD-4714 Mismatch of Service and Operation on API Explorer after quick authenticate
  • BCLD-4833 Importing an invalid script zip file and choosing “Full Sync” deletes all existing scripts
  • BCLD-4832 Facebook transactions – some transactions are being displayed as “null”
  • BCLD-4812 Need ability to preserve My Servers and Lobby configurations on Deploy and Import
  • BCLD-3193 SendEvent operations gives a positive response without entering profileID
  • BCLD-4751 Descriptive text on “Edit Lobby Type” popup is out-of-date
  • BCLD-4737 Can’t delete a group after using “Delete Users”
• Plus miscellaneous fixes and performance enhancements…

Hi folks,

We are currently tracking some oddities in the reliability of the brainCloud libraries running in Unity 2019.X on iOS devices.

Updates:

1. We have confirmed that this issue is limited to iOS only (edit: also probably tvOS). It does not occur on Android, Mac, Windows or WebGL.
2. A Unity Rep has confirmed the defect, and that they are working on a fix. See this Unity Forum thread.
3. The defect now appears in Unity’s Issue Tracker – click and add your +1 – https://issuetracker.unity3d.com/issues/ios-unitywebrequest-errors-large-packets-with-examples  
4. Further updates in this brainCloud Forum Post.

Executive Summary: We highly advise developers to stick with Unity 2018.X until further notice.

Symptoms

The symptom is that requests are being sent to brainCloud, and occasionally rejected with what brainCloud calls a signature error.

Signature errors are flagged if the content of the message that brainCloud receives doesn’t match the MD5 that has been calculated for the message. They generally mean that either the client had the wrong secret (likely a hacking attempt) or the message content has been tampered with (also likely a man-in-the-middle hacking attempt).

In this case, neither of these has occurred – rather, the message content has been corrupted somehow by Unity’s libraries (we suspect a combination of the UnityWebRequest and/or UploadHandler classes).  

This doesn’t happen all-the-time… (in fact, it very rarely occurs if requests are less than 2K). But we’re seeing it happening quite often with requests that are 7K or greater in size.

After enough of these errors occur, the UnityWebRequest class is locking up – causing the brainCloud client library to stop functioning properly – requiring the app to be terminated.

Note – the good news is that brainCloud’s servers catch this issue and prevent the bad message from corrupting your data. The bad news is that a client experiencing this issue might have to retry several times to send a request – impairing client performance.

Reproducing the error

We have only been able to reproduce this error in Unity 2019.1.X (as well as 2019.2.0b5 (alpha) and 2019.3.0a5 (beta)) and only when running on iOS devices. 

We do have reason to suspect that Android devices may also be impacted (but we haven’t had time to test + prove that yet). Update: We have since tested on Android and cannot reproduce the problem. So this appears to be an iOS-only issue. 

Certainly, the same code running from the editor on Mac and Windows workstations seems to run just fine.

And certainly, the same brainCloud libraries (with test code) running under Unity 2018.X runs fine as well. Also, our C++/Objective-C libraries are still running fine under iOS – this issue is limited to Unity. 

We have noted, as per their 2019 release notes, that Unity seems to be making significant changes to their iOS communications.

• 2019.1 Release notes
  • iOS: UnityWebRequest will use new backend based on NSURLSession. Old NSUrlConnection backed is still available (commented out in trampoline)
• 2019.1.4 Release notes:
  • iOS: Fixed larger than 2k payloads not sent by UnityWebRequest when HTTP/2 (1146305, 1152777)

Recommendation

For now, we recommend that developers limit their production iOS builds to Unity 2018.X or earlier.

We are constructing a limited function test app that we will submit to Unity when we report this defect. We will keep the community posted as to how that progresses.

Update – you can see the brainCloud forum post, with repro code and details, here.

In the meantime, we thought it best that our community have a heads up regarding this potential problem.

We apologize for the inconvenience and hope that through working with Unity, we can get a solution to you ASAP!

Release Highlights

RTT Official Launch!

With 4.0, we officially take the beta label off of RTT, and release it to the world!

As you know, RTT adds a bi-directional channel for real-time communications to the brainCloud platform, greatly expanding the types of experiences that can be delivered without additional tech.

The list of great new features that RTT has already enabled includes:

• Real-time Events
• Online Chat
• Real-time Messaging
• Online Matchmaking
• Lobbies

For 4.0 we are pleased to add:

• Async Matches
  • we’ve RTT-enabled Async Matches. So now you can use the Async API in real-time! (Don’t worry, you can still use it offline if you would like).
  • Oh, and while we were at it, we’ve made async matches automatically delete themselves after 90 days. So your apps no longer have to do the cleanup manually if they don’t want to.
• Integrated Hosting
  • we have integrated our new Hosting features with our RTT Lobby service

Plus we have officially launched our RTT-enabled Plus subscription plans that make these great features available at all usage levels.

Hosting (beta)

Did we mention hosting?

In brainCloud 3.8, we introduced support for custom Room Servers (i.e. game or experience servers) that integrate with our Lobby Service for matching up users.

The cool thing is that you have full freedom to custom code your Room Server yourself, in any technology. The not-as-cool thing was that you had to host (or arrange for hosting) of the servers yourself, plus you also had to code up a Room Server Manager, for us to integrate with (it was responsible for spinning up your servers and managing them). Suffice to say, that’s a bit more complicated than most people want.

So for 4.0 we’re pleased to announce that we can host your custom Room Servers for you – all managed by our built-in Room Server Manager. It’s truly as simple as giving us the name of the Docker image to use for your service. We handle the rest, spinning up servers and containers as needed – and charging you for the server cycles used.

Relay Servers (beta)

Even simpler than hosting a custom-built Room Server, is hosting our new built-in Relay Servers!

We have used our new RTT + Hosting infrastructure to add built-in Relay Server support to brainCloud.

Now building a real-time or near-real-time multiplayer experience on brainCloud is as simple as:

• Configure the relay servers on the new Design | Cloud Code | My Servers page
• Connect the relay server to your lobby via the Design | Multiplayer | Lobbies page
• Utilize our new Relay Communications APIs in your Unity apps!  (note – Unreal and other libraries will be supported soon!) 

New Billing Plans

With all this new infrastructure, there has to be some way to pay for them! Sorry! 🙂

But it’s not all bad news. Not only have we launched new Plus plans that add support for RTT and Hosting, but we are also introducing new lower-cost Lite plans! Plus we have significantly lowered the API usage costs (as you scale up) across all plans!

Also note that we have added a new Development Plusplan, which is a $5 / month plan that gives your apps in development access to Hosting features (i.e. hosted Room Servers and Relay Servers).

For full details on our updated billing plans, see our billing announcement.

And a bunch more!

And that’s not even all of it. brainCloud 4 also brings:

• [New!] brainCloud Bombers RTT
  • Our new example game fully demonstrates RTT and Relay Servers
  • Play it on Steam!
• [New!] Forums!
  • brainCloud now has forums for our development community. Check them out here!
• [Updated!] Tic-Tac-Toe example
  • Now supports the new RTT-enabled Async Match API
• DataStream Enhancements
  • Our DataStream service now pushes more events, including:
    • Tournament events
    • Group events
    • Chat events
    • Lobby Events
• Updated Facebook Integration
  • We now support Graph API 2.9

And be sure to check the API Changes below for a smattering of new APIs.  

Portal Changes

We’ve made the following updates to the portal:

Team

• Home | Start
  • We’ve added a link to the new brainCloud Forums!
• Manage | Apps
  • Go Live! reworked to support the new V4 billing plans
  • New Change Plan action menu item allows you to dynamically swap the plan for your app at any time
  • To terminate service for your app, just choose Delete from the action menu. The system will now automatically expire your subscription. You will be invoiced at the end of the month, on a pro-rated basis, for the amount of service your app used.
  • We have also added a new Plan column to the display to make it easier to tell exactly which plan your app is using

Design

• Core App Info | Advanced
  • Restore Checkpoints – brainCloud creates a checkpoint each time you deploy to an app and/or import to it. This new feature allows you to easily restore an app’s meta-data to a recent checkpoint.
• Authentication | Email Authentication
  • brainCloud can now send confirmations to users after they have successfully changed their passwords. Configure the emails here.  
• Cloud Code | My Servers
  • This is the screen formerly known as “S2S Config”
  • The screen has been expanded to support the configuration of multiple server types:
    • Custom Servers – these are the old S2S Configs-style servers
    • Relay Servers – deploy your own set of brainCloud Relay Servers
    • Room Servers – configure brainCloud to host your custom Room Server images
    • Room Server Managers – for integrating with a custom-developed, externally-hosted Room Server Manager
• Multiplayer | Lobbies
  • Room Server selection updated to use the new My Servers configurations (instead of referring to servers from Web Services, which 3.X did) 

Monitoring

• User Monitoring | User Summary
  • You can now trigger the sending of a password reset email to Universal Identity users (if they have a contact email stored against their profile). Click the mail button to send.
• User Monitoring | Recent Users
  • The New column has been replaced by a new “Logins” column – which shows the number of times that user had logged in. Much more informative!

Reports

• Reporting | Analytics
  • We have added a new section that reports the # of Dormant Users in your app. Dormant Users are defined as users who have not logged into your app in 180 days.
• Reporting | API Usage
  • We have added new RTTand Hosting usage statatistics

General

• DOCS top menu
  • We’ve added a Forums link to the DOCS menu. Hmm, maybe we should rename the menu to HELP?

API Changes

Important: The 4.0 libraries (especially Unity) contain changes that will be breaking for some apps. As always, the older libs continue to work for existing apps. We recommend all devs upgrade at their earliest convenience. 

The following changes/additions have affected the brainCloud API:

• Authentication
  • New ResetUniversalIdPassword() and ResetUniversalIdPasswordAdvanced() calls allow users to reset the passwords for their Universal IDs (via an email sent to them). Note that the contact email of the user must be set for this to work.
• Cloud Code Bridge
  • Added new GetSessionCacheObject() and SetSessionCacheObject() methods for saving custom objects in the user session. This is quite helpful if you want to cache frequently accessed data for use by multiple cloud code scripts.
• Global Statistics
  • Support for new MIN and MAX operations. Very useful for keeping track of the personal high scores of a player.
• Lobby
  • New CancelFindRequest() cancels an asynchronous FindLobby request.
  • New JoinLobby() call allows a user to skip matchmaking and immediately join the specified lobby instance (potentially with party members).
• Player Statistics
  • Support for new MIN and MAX operations. For details, see the updated Statistics Grammar page.
• RTTService
  • Migrated the RTT Initialization methods (EnableRTT(), RegisterRTTChatCallback(), etc.) to the RTTService for better API coherency

We have also deprecated the following methods:

• Wrapper
  • Removed the deprecated singletonmode
  • Removed EnableRTT(), RegisterRTTChatCallback(), etc. – and moved them to the RTT Service
• Client
  • Removed EnableRTT(), RegisterRTTChatCallback(), etc. – and moved them to the RTT Service

Finally, a few miscellaneous changes have been made:

• We are now wrapping all 3rd party libraries in a brainCloud namespace in the Unity / C# libraries
• We have renamed the Settings plugin in the Unity library

For more details and migration steps, see the V4 Client Changes blog post.

Miscellaneous Changes / Fixes

• Updated libraries
  • All libraries have been updated to include all 4.0 APIs, with the exception of the Relay Service
  • The new Relay Service APIs are currently available in the Unity / C# libraries only. Unreal + other libraries will follow soon.
• Documentation updates
  • TBC
• Important Fixes
  • BCLD-4679 – Duplicate leaderboard config issues (leaderboard Duplicate, new “MOCK” division set instance creation) if Enrol or Announcement minutes and called when rotation minutes remaining < (Enrol + Announce + Buffer) minutes
  • BCLD-4651 – Permissions issue with groups – ReadGroup() vs. ReadGroupData() with other=1
  • BCLD-4415 – [Documentation] – More documentation support for the parameter ‘isOpenGroup‘ for the ‘AutoJoin’ operation
  • BCLD-4650 – Issue in the UpdateGroupACL cloud code proxy
  • BCLD-4645 – UK Area code is missing from Authy
  • BCLD-4494 – Add documentation for ‘UpdateEntityIndexedId’ call in both API and S2S Explorer in the API Reference Docs.
  • BCLD-4524 – Add Server Session support for Leaderboard Service operations that are currently only supported for Player Session
  • BCLD-4337 – Sending null match state on create Async Match should not clobber the summary!
  • BCLD-3192 – ‘GetSharedEntityForProfileId’ returns positive log response without entering the profileID
  • BCLD-4307 – Improve speed of ChildEntity – UpdateEntity using updateFields instead of update
  • BCLD-4293 – Operations are not alphabetized on the APIHooks screen – should be
  • BCLD-3250 – PostScoreToLeaderboard has wrong name in Javascript example
  • BCLD-3232 – Client API – ‘ReadServerTime’ Operation returns a definite response, despite entering incorrect app ID
  • BCLD-4483 – DataStream Push Notifications – new safe mode to reduce excessive DataStream-related usage charges
  • BCLD-4499 – PostTournamentScoreWithResults is missing in the Unreal Client
  • BCLD-4503 – resetCurrency is missing from the virtual currency service
  • BCLD-4448 – Defect being seen in async match profile urls
  • BCLD-4498 – If a company is in a Suspended state, they are unable to edit their billing information to get out of that state…
  • BCLD-4488 – User can create Leaderboards with spaces and special characters using the ‘CreateLeaderboard’ API call
  • BCLD-4449 –  User can create Leaderboard with spaces and special characters using the ‘PostScoreToDynamicLeaderboard’ API call.
  • BCLD-4454 – StartTime matches Registration time for Monthly Tournament in ‘GetTournamentStatus’ call
  • BCLD-4228 – API: Updated player names and picture urls not reflected in turn-by-turn match summary
  • BCLD-4358 – Inconsistency between comms initialize parameter order and wrapper order for java android and desktop
  • BCLD-3200 – JSON error when saving a quest with an already existing name
  • BCLD-4268 – Attaching an email identity overwrites an exisiting contact email
  • BCLD-3470 – Monitoring -> Global Entities -> Bulk options -> Export should be disabled when there are no global entites for the app
  • BCLD-4294 – Missing data in the new AppStore VerifyPurchase() call…
  • BCLD-2788 – Portal: deleting an image in [Achievements] without saving the achievement causes a missing image
  • BCLD-3968 – Errors handing $and in Where clauses
  • BCLD-3969 – getRandomEntitiesMatching sometimes returns 0 items for max 1, even when items match
  • BCLD-3977 – Log processor is incorrectly attributing mongo log collection write failures (too to large log sizes) to a particular app
  • BCLD-3927 – Clicking on resetpassword email link twice gets user to a valid looking reset password screen
  • BCLD-4111 – Design Portal should not be able to configure invalid Steam product info
  • BCLD-4105 – Add the missing readUserStatsSubset() cloud code method
  • BCLD-4108 – Global Entities: allow filtering and sorting on entityId, version, and expiresAt
  • BCLD-3989 – File Storage being reported on the API Usage page appears to always show 0.0
  • BCLD-4118 – When we do a SwitchToChildProfile(), we should add a login log entry for the child profile
• Plus miscellaneous fixes and performance enhancements…