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 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…
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 own 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. (Prior to 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)
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.
[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.
[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.
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).
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. See this blog post for migration instructions. 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:
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. For details, see the updated Statistics Grammar page.
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…
Release 3.11 provides some key feature requests with some under-the-hood improvements that will be delivered upon in Release 4.0 (coming soon!).
Release Highlights
SendGrid Dynamic Templates
We have updated our Mail APIs and integration code to work with Sendgrid’s new Dynamic Template format, which includes support for Handlebarssyntax.
This means that you can:
Use Dynamic Templates for brainCloud’s Email Authentication and Tournament Notification
Use Dynamic Templates with brainCloud’s SendAdvancedEmail*() APIs
Take advantage of the Handlebars syntax (with substitution, conditions and iterations) in your templates
Even send attachments!
And of course, Sendgrid’s legacy templates still work.
Please note – the substitution parameter format of SendGrid’s API for new dynamic templates is different. So if you are using the SendAdvancedEmail*() calls and are changing from legacy → dynamic templates, you’ll need to modify the serviceParams JSON that is provided with the call.
UniversalId Wildcard Searching
If your app supports looking up other users (for friends, challenges, etc), we highly recommend that you identify and lookup users by UniversalId instead of by user name.
UniversalIds are better than user name because:
They guarantee uniqueness
They are case insensitive
Searching is 3 – 5 times faster! (because they are unique, case insensitive, and we anchor all searches at the beginning)
But… until now we really weren’t providing you with enough search flexibility. Which is why we have added some new methods:
FindUserByUniversalIdStartingWith() – use for wildcard-like searches
FindUserByExactUniversalId() – use for exact searches
And remember, we do provide a handy method that allows your app to use UniversalId’s (to identify/lookup users) without using them as authentication methods – check out AttachNonLoginUniversalId().
A few notes:
We have deprecated the old FindUserByUniversalId() – its spec was pretty misleading (looked like an exact search – but performed like a wildcard search – and an unoptimized one at that!). Note – it will still work if your app was already using it.
For those of you stuck with already-implemented user name searching, we’ve added some improvements as well:
FindUsersBySubstrName() is now 10-20% faster
FindUsersByNameStartingWith() (new!) is ~50% faster than FindUsersBySubstrName() – so switch to this one if you can!
Improved Cloud Code Debugging
Good news for you cloud code developers – we’ve added some new smarts to the API Explorer and Cloud Code Editor that makes it a lot easier to trace and debug your scripts!
The two big additions are:
Activity Window Logs – log entries that your script creates are now visible in the activity window on the right-hand-side of the Cloud Code Editor and API Explorers
Debug Log-level – we have also added a new debug log level that only prints to the Activity Window log. This is perfect for analyzing and debugging your scripts, without unnecessarily clogging up your logs otherwise.
New JSON context methods– we have also expanded to provided Logging APIs to provide new methods that allow you to log JSON contexts directly (without stringifying them first)
Bridge access– finally, we have added all these new logging methods directly to the bridgefor maximum convenience!
Check out the GIF below to get a feeling for how the new script logging works.
Miscellaneous
Plus a few more shiny features, including:
Lobby Event Optimizations – a bunch of the data in the Lobby RTT events was unnecessary – we’ve trimmed it down to be more efficient
Faster user name lookups in the Design Portal
View WebHooks calls in the Server Logs
Filter the Server Logs
Export a user’s data from the User Summary page
and more!
Portal Changes
Design
Cloud Code | API Explorer
Activity pane now shows log messages
Cloud Code | Scripts | Script Editor
Activity pane now shows log messages
Segmentation | Segments
Page should load faster now
Monitoring
Global Monitoring | Server Logs
Incoming WebHooks calls are now captured here
Added ability to Filter the logs shown by type, source, date, etc.
User Monitoring | User Summary
Select User– faster searching by user name! ← Popular Customer Request!
(beta!) Debug data export – new ability to export a user’s data. Very useful for debugging!
API Changes
Client API
The following changes/additions have affected the client API:
Client
isRTTEnabled() convenience method added to allow apps to check their RTT state
Entity
GetSharedEntityListForProfileId()and GetSharedEntitiesForProfileId()now return entityListCount for convenience
Friend
New Universal ID searches:
FindUserByExactUniversalId()
FindUsersByUniversalIdStartingWith()
New name search methods
FindUsersByNameStartingWith()
Group
ReadGroupMembers() – now returns the profile picture URL (if present) for each member
Identity
SwitchToChildProfile()and SwitchToSingletonChildProfile() cloud code methods have been simplified to align with the client versions of these calls. To clarify, the new methods no longer require you to pass in values for platform, language, etc – these values are all inherited from the current session.
Cloud Code
Bridge
Added logging calls to the bridge for convenience – LogInfo(), LogInfoJson(), LogWarning(), LogWarningJson(), LogError()and LogErrorJson()
Also added new debug log calls – LogDebug()and LogDebugJson(). Note these calls are not available on the logging service itself, because they do write to the persistent logs.
Added new context calls – getScriptName(),getAppName(), and getEnvironmentName().
HttpClient
Added new PostJsonOffboard() call – for efficient posting of HTTP requests in scenarios where it isn’t necessary to wait for the result
Logging
Added new JSON-context calls – LogInfoJson(), LogWarningJson(), and LogErrorJson()
RTT (Beta) Events
We have made some small changes to the Lobby events being returned – essentially just removing some redundant / unnecessary fields.
We largely removed:
Nested and redundant id information (i.e. nested fields like id, seq, appId, etc.)
lobbyTypeDev, settings, connectDataand occasionally members fields from events that didn’t require them
For full details on Lobby Event composition, check out the details here.
Note – although RTT is still in beta, we don’t take changes like this lightly. Rest assured, we have reached out to our live RTT customers separately to give them a heads up re: these changes.
Miscellaneous Changes / Fixes
Updated libraries
All client libraries have been updated for this release. Be sure to grab them!
We have added additional killswitch code to prevent errant apps from endlessly spamming our servers on authentication failures. As a rulefolks, retrying an operation in an endless loop is bad form! Do not do that! 🙂
Release 3.10 is a modest release that fulfills a number of customer requests before the holidays. We hope that you find something you like!
Release Highlights
Chat Profanity Filter
We have added profanity filter support to our chat service. With it, you can automatically filter profane words (across multiple languages), as well as email and web urls from chat conversations. Offending word segments will be replaced with the character that you specify.
You can configure this via the Design | Messaging | Chat page in the Design Portal. Note that you must have signed up for WebPurify and configured it via the Design | Integrations | Manage Integrations page first.
Email Validation Enhancements
We have added two new features to make incorporating email verification into your apps easier.
Validation hooks – brainCloud can now automatically trigger a cloud code script to run when a user clicks on the validation URL included in the verification email. The script to be called is configured with the Design | Cloud Code | API Hooks page – just choose the EmailAuth service and assign scripts to Post and/or PostFail.
Continue button – we have also added a configurable [Continue] button to the web screen that pops up for email validation. This button is configured to send the user to the web URL of your choice when clicked. Very useful if you want to bring the user to your site login (or back into your app) after validating their email.
The continue button is enabled by configuring a validation hook script (see above) that returns results in the following format when run:
There are times when it is handy to share a brainCloud login when traversing across multiple software systems (or apps) in real-time. For example, a user logs into App A, but to perform some action needs to be passed to a separate user flow in App B.
Accomplishing this in brainCloud is possible, but challenging. All three potential solutions have drawbacks:
Passing the user’s credentials from one system to another <- major security concern
Asking the user to login again <- usability issue
Passing the active brainCloud sessionId to the other system <- doesn’t work due to packetId synchronization
So – we have created a new way to do this, which we call Handoff. The idea is pretty simple:
App A: The user is logged into brainCloud normally, and a session created
App A: The app calls the new CreateHandoffId() method, that creates a temporary handoffIdand securityTokenthat can be used to remotely log that user in. This id + token is only valid for a short period (~ one hour) and can only be used once.
App A: The handoffId + securityToken is passed to the other app/system. How that is done is app-specific. It could be as simple as passing it along in a URL. You could even separate the data – send the id in an email with a clickable link, but text the user the token so that they have to manually enter it <- useful for more security intensive use cases
App B: The app calls the new AuthenticateHandoff() API call to log the user into brainCloud
Voila!
Pro-tip: Hand-off can be combined with the Email Validation Enhancements above to redirect the user back into your app’s registration flow!
Non-login Universal IDs
The brainCloud profile nameproperty is a handy way for users to identify themselves. It is used throughout brainCloud (and brainCloud apps) for displaying player names in leaderboards, chat, lists of friends, etc.
Although handy, the nameproperty does have some inherent limitations:
Names are not unique. Like in the real world, multiple people can have the same name.
Searches can be slow. Searching through non-unique collections is slower.
We have long-advocated that developers assign Universal Identities to user accounts to easily enforce uniqueness and make them more searchable. To keep users from being able to inadvertently login via these ids, a generated GUID can be used as the password.
We have now taken the next step and implemented direct support for non-login Universal IDs.
Usage is simple:
Call AttachNonLoginUsername( <username> ) to create a Universal Identity and attach it to the current profile. It will return an error if the username is not unique.
Finally, in the Design Portal search by Universal ID — not by Name! — to find the user.
Pro-tip: brainCloud just uses a string for universal identities. They are pretty free-form (i.e. can have spaces, in front, in back, special characters, etc.) If you want to be more restrictive, be sure to filter them and apply your restrictions before creating them!
S2S Library
We have always had a handy https-based S2S (Server-to-Server) API – but up until now we’ve left the heavy lifting of calling it to your custom server code.
Enter our new S2S Client Javascript libraries! You can grab them from our GitHub repo, or from npm.
They are fairly minimal – you still need to specify raw service and operation, together with a properly constructed data object for the parameters (use the S2S Explorer as your guide to how to format things). We just handle the drudgery of forming the actual requests and sending them to brainCloud servers. And we use the more optimal S2S session-based protocol – so your communications are more efficient and cost you less! It’s win-win!
Server Logs
Finally, we are working to make brainCloud’s server-to-server interactions a lot more understandable / debuggable. As a first step in that, we are now logging all incoming S2S requests to a new log that can be viewed on the Monitoring | Global Monitoring | Server Logs page.
This page is currently limited to only a maximum of the last 100 requests. It will be enhanced significantly in upcoming releases.
Portal Changes
Design
Cloud Code | API Explorer
There are new API Calls available in the Authentication, Identity, and HttpClient services.
Cloud Code | API Hooks
Added the new EmailAuth hook for automatically triggering scripts when a user clicks on the link in the validation email.
Messaging | Chat
Added new Profanity Filtering config settings. Note that you need to configure the WebPurify integration from the Integrations | Manage Integrations screen first.
Segmentation | Segments
Improved the performance of retrieving the list of Segments
Monitoring
[New!] Global Monitoring | Server Logs
New page collects S2S requests and responses for easier debugging of server scenarios
Note – currently a beta page – will be enhanced soon with pagination features (and later with filtering!)
API Changes
Client API
The following changes/additions have affected the client API:
Added a new PostJsonResponseText() method for those weird APIs <cough> slack </cough> that post in JSON but return the result as a string? I mean really – who does that? 🙂
The existing PostJsonResponseJson() method also more gracefully handles text-only returns – enclosing them in a JSON object with the text in a field called jsonString.
Miscellaneous Changes / Fixes
Updated Client libraries
The following libraries have been updated with the new 3.10 feature set:
Unity + C# libraries
Java libraries
Javascript libraries
Objective-C + Swift libraries
Unreal
ActionScript (minus RTT features)
Additional notes
Javascript
We have combined our two node.js packages (one for node.js server, one for react) into a single package!
Our Javascript library now directly supports NPM. Include “braincloud-js” to grab it!
C++ (PS4)
FileUploader in place.
Objective-C
Chat and Lobby services updated.
Unreal
Unreal wrapper handling smart switching better.
We highly recommend that all apps update to the latest libs!
Miscellaneous changes
Improved handling of anonymous device ids
Certain scenarios, like profile merges, result in dormant anonymous ids being associated with a user’s profile.
brainCloud will now limit the maximum # of device ids per profile, and if there are more, delete then oldest <n> of them at each login – eventually returning the user to the proper maximum.
The default maximum has been set to 10.
Page performance
Improved the performance of the Design | Segmentation | Segments and Design | Core App Info | Admin pages.
Documentation updates
Improvements to content and accuracy of code examples.
Important Fixes
BCLD-3715 – Fix to SendMessage to allow passing in full jsonContext
BCLD-3860 – Scripts: Double-slashes in example parameters were not being preserved during export/import
BCLD-3737 – Chat service NPE when attempting to retrieve group chat listeners for a group
BCLD-3861 – NPE in lobby service runMatchmaker() API
And many, many more!
Plus miscellaneous fixes and performance improvements.
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
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.
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.
Miscellaneous
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:
Design
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:
First create a tournament-enabled Leaderboard to act as a template (setting the template flag to enabled)
Then create the division set, selecting the Leaderboard template and configuring the maximum # of players per division instance
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
Monitoring
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)
General
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!
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
New Division Set calls have been added – mostly used when querying and joining a Division Set instance.
brainCloud 3.8 marks the beta release of our new Real-time Tech, which we ingeniously call brainCloud RTT.
The brainCloud Platform is built upon a request + response foundation – which provides great flexibility and reliability, together with incredible performance and scalability. There are times, however, when more adhoc communications are desirable (online gaming, chat, monitoring, etc) – and that is where RTT comes in.
brainCloud RTT adds a real-time channel to our client API. This channel allows clients to listen for and react to real-time events – without polling.
This enables a whole suite of new brainCloud features – the first of which you’ll see in brainCloud 3.8!
Note – brainCloud RTT is available to customers using the Business Plan and above<- this has changed – see below! Usage pricing above the initial set of included concurrent users will be announced soon!
To enable RTT, check [x] Real-time Tech (RTT) Enabled on the Design | Core App Info | Advanced Settings page.
Update – As of 4.0, brainCloud now supports Plus Plans – which provide RTT features across a variety of usage levels. For more information on Plus Plans, see our 4.0 plan announcement.
Release Highlights
Chat
Thanks to RTT, brainCloud now supports online chat!
We have focused primarily on supporting chat for groups, but we also provide support for global chat channels – which are available to all users of an app.
Chat offers the following features:
global and group channel types
simple or rich content messages (developer defined)
caching of recent chat history
support for system messages (from the app, instead of an end-user)
support for hidden (semantic) messages
ability to edit / delete chat messages
Note – Chat requires brainCloud RTT to be enabled for the app.
For more info, check out the Chat API page, and try out our example chat app – bcChat!
Messaging
brainCloud now provides a Messaging service as well. Messaging is different from chat, in that:
recipients are addressed directly (i.e. not via channels)
message history is managed on a user-by-user basis (i.e. not by channel)
RTT is optional; if enabled, users will receive real-time notification of new messages
Messaging features:
Support for multiple recipients
Messages are organized into incoming (“inbox”) and sent (“sent”) messageboxes
Support for readvs. unreadmessages
Support for system messages (from the app, instead of an end-user)
Automatic clean-up / deletion of expired messages (important to keep storage utilization low)
With RTT, brainCloud now directly supports the development and integration of custom servers for shared experiences – such as online games (async or otherwise), online meetings, shared document editing, etc.
Room Servers
Room Servers are custom servers used to provide a shared experience (i.e. an online game, online meeting, etc.) to a set of users.
These servers are light-weight and simple to develop, and can easily integrate with brainCloud’s new Lobby and Online Matchmaking services.
In 3.8, Custom Room Servers must be hosted outside of brainCloud, but future brainCloud releases will support hosting the services directly under brainCloud via Docker containers.
Lobbies
Lobbies are used to gather up users prior to launching Room Servers. They provide an online matchmaking service (as opposed to the offline strategy provided by our existing Matchmaking service).
Lobbies provide:
support for multiple teams – with min / max # of users
automatic assignment of users to teams (users can switch afterwards)
management of user settingsand readystatus
support for multiple lobby types
support for calling an external room server managerto launch a room serverwhen the lobby is ready
Lobby Matchmaking
Online matchmaking is used to match up users with lobbies, in preparation for entering Room Servers.
The Lobby Matchmaking APIs allow the developer to:
specify the type of lobby / room to match with
specify the player rating to target
specify an algorithm to use when escalatingthe search
provide a custom filter script to use to filter out candidates
We have greatly enhanced our Leaderboard and Tournament systems to make the scheduling of tournaments more flexible.
brainCloud previously supported only regularly recurring tournaments – which are tournaments that happen daily, weekly, monthly, etc… (i.e. at preset intervals). brainCloud 3.8 introduces new On Demand / Adhoc Tournaments – to support irregularly scheduled tournaments (i.e. major holidays, new releases, etc.)
To create an adhoc tournament, create a leaderboard and choose the “Adhoc Tournaments” rotation type. Then manually add each tournament period.
Cloud Code Import / Export
Finally, we are reworking our cloud code management sytems. As part of this, we have created a new serialization format for cloud code scripts, that makes it easier to export the scripts, edit them locally on your workstation, and upload them back to us.
The handy cloud-code method below allows you to post a score to multiple leaderboards:
var result = {};
result.posted = 0;
result.errors = 0;
result.errorsList = [];
// Grab the parameters
var leaderboards = data.leaderboards;
var score = data.score;
var extras = data.extras;
var _leaderboard = bridge.getLeaderboardServiceProxy();
var postResult = {};
// Loop through the leaderboards
for (var i = 0; i < leaderboards.length; i++ ) {
// Post the score
postResult = _leaderboard.postScoreToLeaderboard(leaderboards[i], score, extras);
if (postResult.status == 200) {
result.posted++;
} else {
result.errors++;
result.errorsList.push(postResult);
}
}
// Return the results
result;
//*** ------------- brainCloud meta-data begins now - do not hand-edit -----------------
// "scriptName":"PostToLeaderboards",
// "clientCallable":true,
// "s2sCallable":false,
// "peerCallable":false,
// "scriptTimeout":10,
// "description":"Posts a score to multiple leaderboards",
// "parms":"{\n \"leaderboards\": [\"weekly\", \"alltime\"],\n \"score\": 1000,\n \"extras\": {}\n}",
// "version":3,
// "updatedAt":1530799500264
To import it into your app:
Click here to download the serialized version of the cloud code script to your workstation
Launch the Design Portal, and go to Design | Cloud Code | Scripts, and choose the Import Script option from the Import / Export menu button
Navigate to your download directory, and choose the PostToLeaderboards.cloudcode.js.zip script
Click okay – and voila, you should now have the script, with all setting intact.
This new serialization format is the first step to a bunch of new features that we hope will make creating and managing cloud code scripts a lot easier for devs. We hope you like it!
Portal Changes
The following additions and changes have made to the Design Portal:
Design
Core App Info | Advanced Settings
Added a new setting to enable RTT to the App Settings section.
Cloud Code | Scripts
Added new options for importing and exporting Cloud Code scripts.
Leaderboards | Leaderboard Configs
This dialog has been completely re-designed to better handle Tournament scenarios, including new On Demand Tournaments.
One tournaments are enabled, a new Tournament Periods section appears – allowing the developer to select and edit the settings of a specific tournament rotation.
Recurring tournaments will always show the current period, followed by the next (recurring) period. Changes to either period will affect all periods that follow.
Adhoc tournaments will show the the current period (if there is one) and any future periods. Adhoc tournament periods do not repeat – you must individually schedule each one.
Messaging | Chat
Used to enable and configure the new Chat service.
The settings determine how much chat history is preserved.
Messaging | Chat Channels
Used to configure the list of Global Chat Channels for the app.
Messaging | Messaging
Used to enable and configure the Messaging service.
The settings determine message retention, and whether outgoing copies of messages are saved.
Multiplayer | Lobbies
Used to enable the Lobby service, and configure the list of Lobby Types.
Lobby type settings include:
team definitions – including min / max number of partipants
progression rules – including timing and ready-up percentages
matchmaking filter – used to customize matchmaking beyond the built-in skill, lobby-type and team space algorithm
room server manager – the web call to make to allocate a room server for the experience
custom config – custom json parameters to pass onto the room server at the start of the experience
Monitoring
Global Monitoring | Leaderboards
Updated the leaderboard viewer to view On Demand / Adhoc Tournaments
API Changes
The following changes/additions have been made to the brainCloud API:
We are happy to present Release 3.7.0. It’s a mid-sized update that satisfies some key customer requests and incorporates some foundational changes that we will be leveraging in upcoming releases!
Release Highlights
Inherited Friends!
The Shared Accounts feature in brainCloud allows developers to build relationships between apps – so that users can log into a single master account (i.e. parent profile), and utilize that account (and data) across a suite of related apps. The user data from each app is still stored independently (allowing independent save state, achievements, scores/leaderboards, etc.) in a separate sub-account (i.e. child profile).
We have now extended this mechanism to better support social relationships between users. So, instead of having to manage a set of friends individually for each app, child apps can now inherit friends from their parents. This is a great boon for social leaderboards – and means that new entrants in a suite of apps can easily extend the social graph of related apps.
If you are already using Shared Accounts, you can enable Inherited Friends by going to the Design | Authentication | Shared Accounts page and checking the [x] Include Friends of Parents option.
Our matchmaking service has been enhanced to offer more flexibility – namely support for overriding the player’s ranking that is the basis of the search, and the ability to substitute in a different matchmaking filter.
Note – for security purposes, these new calls are cloud-code only.
Updated Developer Roles / Permissions
We have tweaked the permissions associated with the default development roles of the system to incorporate customer feedback.
The following changes have been applied:
Support role
Removed write access to all of Global Monitoring, except for Leaderboards.
Removed access to Reporting | API Usage – leaving only access to Reporting | Error Analytics
Full read+write access to User Monitoring remains
Limited read+write access to Design remains as is
Read-only role
Removed access to Design | Core App Info (all sections) and Design | Integrations
Change E-mail Identity
We’ve added a new api that allows you to change the email address associated with a user’s EmailIdentity.
The new ChangeEmailIdentity() call takes as parameters the existing email and password (for security purposes), and the new email address to use. You can also optionally tell the method to update the user’s contact email as well (recommended).
Note – this method does not currently support our email verification system, so no verification email (with link to confirm) is sent. We plan to add that support in a future release.
Portal Changes
We’ve made the following portal changes:
Design
Authentication | Shared Accounts
Added the new [x] Include Friends of Parents option
Leaderboard | Leaderboard Configs
You can no longer add Tournaments to the active rotation of a leaderboard if it already has scores. The tournament will be queued to activate on the next rotation
Monitoring
Global Monitoring | Leaderboards
Now showing the status of the Tournament auto-claim and auto-join settings per leaderboard rotation
Team
Home | Audit Log
We now log any password reset requests for security purposes…
API Changes
The following changes/additions have affected the brainCloud API:
Identity
New ChangeIdentityEmail() method for changing the email address that a user uses to login.
