brainCloud 4.7 is a big release – with lots of new features and even more under-the-covers. Hold onto your hats!

Release Highlights

Cloud Code Folders

The big feature of 4.7 is cloud code folder management. Yes – you will finally be able to organize your cloud code scripts properly!

We know – some of you have been waiting for this feature forever. To be fair – when we originally built brainCloud, with the rich API we had designed (now at > 500 API calls!), we expected custom scripts to be few (i.e. less than a dozen) and small (i.e. less than 100 lines). Let just say that some of you have greatly exceeded those expectations. 🙂 This feature is for you!

Key components of this feature:

• Folder Tree – Updated Design | Cloud Code | Scripts Screen with support for creating and navigating within folders
• Enhanced Import & Export Support – Enhancements to Import and Export functions to allow importing/exports of the entire script collection (with folders intact), or optionally individual folders (with recursion, of course).
• Deployment Support – The Deploy features have been enhanced to support cloud code folders. The full script tree will be pushed when you deploy from one app to another. Note – using the new Builder CLI, you can even push individual folders of scripts from one app to another – great for syncing common scripts between apps!
• Rename Scripts – Scripts now have scriptIds that help to preserve linkages to scripts as they are moved or renamed. And hey, you can now rename scripts!
• Author History – We also now record the name of the team member who made script changes
• Smart Updates – finally, before updating a script during a Deploy Push or Import, we first take a look to see if it really changed. If not, we skip the update without increasing the version – which makes the version history of scripts smaller and much more meaningful!

Arcade-style Leaderboards

Building a game with an old-school feel? brainCloud 4.7 adds support for arcade-style leaderboards – where users can have more than one entry in the leaderboard! Great for daily or weekly rotating high scores!

Characteristics of arcade-style leaderboards:

• Players can have more than one entry in the leaderboard (unlimited)
• Arcade-style leaderboards are created by setting the Leaderboard type to Arcade High (i.e. higher scores are better) or Arcade Low (i.e. lower scores are better). Note that the leaderboard type must be set at the time of leaderboard creation. You cannot change an existing leaderboard to/from Arcade-style – due to the differences in how the data is stored.
• Arcade-style leaderboards must rotate at least weekly; otherwise, the stored data would grow at an uncontrollable rate.
• Arcade-style leaderboards do not currently support tournaments or divisions. We will consider adding support in the future if demand warrants.
• The standard Leaderboard APIs work as-is for Arcade-style leaderboards, with the following adjustments:
  • RemovePlayerScore() removes all of a player’s scores(s) from the specified leaderboard
  • GetPlayerScore() returns only a single score (i.e. the player’s best score) from the specified leaderboard
  • A new method, GetPlayerScores(), returns all of a player’s scores (up to a max limit) from the specified leaderboard
  • GetPlayerScoresFromLeaderboards() returns only the best score per leaderboard specified

Facebook Limited Login Mode

brainCloud adds support for the new Facebook Limited Login mode – which allows apps to utilize a Facebook Login while adhering to new Apple guidelines (and user preferences) that prohibit sharing of tracking data with 3rd parties.

For more information on this feature, see the blog post here.

Steam and Playstation Friend Support

brainCloud now has direct support for Steam and Playstation friends.

This means your apps can more easily create social features (including social leaderboards) on those platforms. Full Steam and Playstation support have been added to the Friend Service and Leaderboard Service APIs.

As a bonus, we have also reworked how the caching of friend data works. This should mean fewer calls to the 3rd party systems (i.e. Facebook, Steam, and Playstation) and faster responses to the social API calls – including ListFriends(), GetSocialLeaderboard(), etc.

Improved Unity Plug-in

brainCloud has a new-and-improved Unity Plug-in. Redesigned and re-implemented from the ground up, the new plug-in:

• Has a cleaner User Interface
• Is more secure – no longer stores appIds, secrets, etc. in plain text. Now requires a re-login to change settings.
• Can now enable/disable logging from the Plug-in without code changes
• Refer to Github Documentation here: https://github.com/getbraincloud/braincloud-csharp/tree/master for details on implementing the new plugin into your projects 

[Beta] Builder CLI

brainCloud 4.7 marks the beta release of our Builder CLI tool (and the underlying Builder API). 

The Builder API currently allows the following:

• App management
  • create, update and delete apps within a team
  • manage app lifecycle – enable/disable, etc.
• Deployment management
  • scriptable deployment of configuration meta-data (including files + scripts + unowned migrate-able custom entities) from app to app
  • deployment of scripts (independent of app metadata); support full script tree or individual folders
• Script management
  • create, update and delete scripts within an app 
• Super features
  • plus additional features for private licensees

Note that the Builder API does not fully duplicate or replace the SYS APIs available via Client APIs and S2S. Its primary purpose is to provide higher-level access to features that are not appropriate at the Client and S2S API levels.

Additional Features

The following additional features are also included in this release:

• Apple Push Notification HTTP/2 support
  • brainCloud now supports Apple’s HTTP/2 based APNS protocol – which is important as support for their legacy protocol ends on March 31st, 2021.
  • Note that no changes are required to your clients or app configurations to support the new protocol
• Automated Promotions Improvements
  • We have added improvements to several common use-cases – including adding Automated Promotions to existing segments.
  • Update – we are delaying these improvements to a 4.7.1 patch that will be available shortly after the 4.7.0 release. 
• Improved Custom Entity Sharding Support
  • Horizontal Sharding allows you to spread your custom entity collection across our MongoDB cluster – improving read/write response times for large collections
  • Sharding a collection means a key must be chosen to use to distribute the data. This key must be backed by a custom index in the collection.
    • Owned collections are always sharded via the “ownerId” field. As of 4.7, brainCloud now automatically adds an { “ownerId”: “hashed” } index for this purpose.
    • Unowned collections are sharded on a custom basis based on the entity schema, and the usage patterns of the app. Once the key has been chosen, a custom index must be chosen (or created) to support that key – and must be marked as a shard key index. Indexes marked as a shard key index cannot be deleted via the Design Portal.
    • Note – once set, the shard key for a collection cannot be changed. So choose wisely!
  • Sharding must be enabled on a per-entity basis by brainCloud Support Personnel. Contact support via the Chat Widget if you would like to discuss sharding one or more of your collections. 
• Improved Lobby Performance
  • The underlying Lobby Processing code had been re-written to be much more efficient.
• Inventory Catalog Image-handling overhaul
  • We have improved how the system handles embedded images so that images are now properly copied when deployed from app-to-app.
• MongoDB 4.0 Support
  • brainCloud 4.7 now officially supports MongoDB 4.0
  • All Private brainCloud deployments will be moved to MongoDB 4.0 within the next month
• Oculus authentication 
  • brainCloud has added direct support for Oculus authentication
• Playstation Network authentication
  • To facilitate PSN Friend Support, brainCloud has added support for direct PSN authentication; previously apps had to use the external authentication feature for PSN authentication

Portal Changes

We have made changes to the following sections of the portal:

Design

• Core App Info | Application Ids
  • Added new PSN and Oculus platform integration tabs
• Core App Info | Platforms
  • Added new Oculus platform
• Core App Info | Advanced Settings
  • Added new “Use Legacy Player Id” flag, which if true, causes the legacy playerId field to function and be returned in some APIs in addition to the newer, proper profileId field. Note the fields are synonymous (and contain the same values).
  • Added new “Add custom paths for Item Catalog images in API” flag to determine whether the Item Catalog allows custom image paths in the image field. Going forward, this behaviour has been deprecated; developers are free to include custom image information in the JSON blob that can be attached to catalog items.
• Cloud Code | Scripts (Legacy)
  • The old cloud code scripts screen is still available (for a limited time) – but have been labeled with (Legacy). 
  • Note that you can only edit scripts present in the root script folder using this screen.
• Cloud Code | Scripts
  • The new Scripts service!
  • Allows full editing and management of scripts – including creating folders, moving scripts, exports and imports.
• Cloud Data | Custom Entities
  • We now indicate which entities are Sharded, and if un-owned, which Index is used to back up the Shard key.
  • Note that sharding a Custom Entity collection is done by brainCloud Support Personnel upon request
• Leaderboards | Leaderboard Configs
  • Added new Arcade High and Arcade Low leaderboard types.
• Promotions | Automated
  • Now properly enforces that an Automated Promotion must target at least one Segment.
  • You must now create and save an Automated Promotion before enabling it. This is because enabling an Automated Promotion now triggers a batch process against all the users of the configured segments – we want to encourage the developer to get the promotion configured properly before enabling it. 

Monitoring

• Global Monitoring | Leaderboards
  • Added support for new Arcade-style leaderboards
• Global Monitoring | Server Logs
  • Added new Elapsed time column to easily convey incoming S2S and webhook performance
• User Monitoring | Select User
  • Added PSN and Oculus IDs to the available search filters
• User Monitoring | Friends
  • Added support for Steam and PSN friends

API Changes

The following changes/additions have affected the brainCloud core APIs:

Client APIs:

• BrainCloudWrapper
  • Added new authenticate and smart-switch calls for FacebookLimited, PlaystationNetwork, and Oculus.
• Authentication
  • Methods for the new authentication types – AuthenticateFacebookLimited(), AuthenticatePlaystationNetwork(), AuthenticateOculus()
• CustomEntity
  • The existing sysDropIndex() method has been deprecated and replaced with the new sysDropIndexName()method – which requires the index Name to be provided in addition to the keys of the index. This fixes an issue where it was unclear which index to delete in cases where multiple indexes have the same keys, but different collation settings.
• Friend
  • Added support for ”Steam” and ”PlaystationNetwork” to Friend APIs
  • Added new method, GetMySocialInfo() that returns social platform info for the current user
• Identity
  • Added new Attach, Detach and Merge calls for the new FacebookLimited, PlaystationNetwork, and Oculus identity types.
• ItemCatalog
  • The Item Catalog service has been refactored to enable better image-file handling – especially when migrating items from app to app during deployment
  • To facilitate this, the service (by default) no longer allows for custom image paths (i.e. non-brainCloud anchored paths) to be set in the image field. Apps wanting to use custom image URLs can use the custom JSON section or resource data sections for this information.
  • There is a new compatibility flag, Allow custom paths for Item Catalog images in API, which controls the enforcement of this new behavior.
• Leaderboard
  • Added new method, GetPlayerScores(), for use with Arcade-style leaderboards
• User
  • SysGetPage() and SysGetPageOffset() calls updated to return profileId instead of playerId. New compatibility flag added (and defaults to true for existing apps) to preserve old behaviour.

S2S APIs:

• CustomEntity
  • The new sysDropIndexName() call has been added to the available S2S APIs.
• Presence
  • The getPresenceOfUsers() call has been added to the S2S APIs.
  • Note that we have corrected the documentation to accurately reflect that only the “sys” calls, plus the getPresenceOfUsers() call, are available via S2S.

Miscellaneous Changes / Fixes

• Updated libraries
  • All libraries have been updated with the latest API enhancements. Go get ’em!
  • Better RTT disconnect handling in libraries
• Documentation and Examples updates
  • API Reference updated with the latest API calls
  • All Unity Examples updated with the new Unity Plug-in
  • The Unity Space Shooter example now features an Arcade-style leaderboard
  • New Google IAP Unity Example and tutorial for integrating with brainCloud
  • Unreal S2S has a new c++/blueprint unreal project to demonstrate using brainCloud s2s calls
  • Miscellaneous doc + example updates
• Important Fixes
  • BCLD-7012 – Core App Info | Advanced Settings – The App Disabled reason needs to allow only JSON maps
  • BCLD-6932 – On deploy/import config, no longer drop Custom Entity indexes in target app if not in source app and record entity config indexes not applied
  • BCDL-6689 – User Service – GetSysPage/Offset returning profiled as “playerId”. Fixed, and compatibility flag added.
• Plus miscellaneous fixes and performance enhancements…

Apple is introducing comprehensive changes to iOS 14.5, iPadOS 14.5 and tvOS 14.5 that will require apps to ask users for their permission to track them across apps and websites owned by other companies.

At first glance, this seems like something that would mostly affect apps that are using user data for advertising-based monetization — but in truth, the implications are deeper than that.

For the record, we at brainCloud very much appreciate and advocate for user privacy. All user data associated with a brainCloud app is private to that app — the data is not aggregated or shared across apps or companies in any way. So if your app is using brainCloud without 3rd party authentication, you can feel confident that that data is not being shared in any way.

That said, brainCloud does support authentication-based integrations with third party providers — most importantly Facebook.

The Frequently Asked Questions from the Apple page linked above clarify their guidance in this area:

By this interpretation, just offering a classic Facebook Account login for your app — which is prety standard practice — requires you to get the user’s permission for tracking across apps and websites owned by other companies. The rationale is that your app may not be sharing the data — but Facebook itself certainly is.

Aside from Facebook’s objections to these changes (we don’t want to get into that) — Facebook has offered a recommended technical solution — they have extended their Facebook Login feature to include a new Limited Login Mode.

So — Limited Login mode seems like a pretty good solution to this problem. There is a pretty big limitation here though. If users opt for the Limited Login mode, the app will not have access to the Graph API.

For games and social apps — this is a pretty big limitation. It means that the app (and backend services like brainCloud that act on it’s behalf) will lose the ability to query Facebook for the user’s friends. This will have a huge impact on games that depend upon those sorts of social interactions for engagement and monetization.

It is therefore highly recommended that games pop-up their own informational message before Apple’s built-in pop-up, to educate the user on any features that may become unavailable as a consequence of their choice.

Another issue is that the identification information returned from the new Limited Login mode is different than with the Classic Login. This means that backend services, like brainCloud, need to implement changes to work with this new mode. The silver lining is that the underlying id of the user remains the same between the two modes — so a user who flips back and forth between the two modes can still be associated with the same back-end account — phew!

We at brainCloud are working hard to incorporate the necessary changes — and will be releasing brainCloud 4.7 with Facebook Limited Login mode before the end of March 2021.

A few more details about the changes in brainCloud 4.7:

• Full Support for Facebook Limited Login mode across the authentication + identity APIs. The same user using either mode will be linked to the same underlying brainCloud profile.
• brainCloud will automatically handle the loss of the Graph API for Limited Login mode users — so for example, users will simply appear to have no Facebook friends (instead of the client app having to deal with errors).
• Coincidentally, brainCloud 4.7 will include new support for Steam and Playstation Network friends — so apps can extend their friend support in other areas.
• brainCloud already supports self-managed Friend APIs.

We hope that this helps to clarify the impact of these changs to iOS 14.5, and how brainCloud can help your apps to adapt.

Happy Coding!

brainCloud 4.6 is mostly an under-the-covers technology refresh:

• We have reworked our database access layer to be compatible with MongoDB 4.0 and beyond – all while maintaining API compatibility for our customers, of course.
• We have moved our reporting services from our API Servers to our Datastream Servers for improved performance and stability for larger exports.
• We have improved the RTT connection handling code in our client libraries.
• We have removed a slew of older deprecated calls from our client libraries.

On top of all that, we did add a few new features – so read on for the details!

Release Highlights

Script API Usage Stats

We have added a new feature to our API Explorer and Script Editor to help you assess and tune the performance of your scripts.

The new API Usage log lists the API calls (by service and operation) that your script made, and calculates the API Count that will be used for billing purposes. Handy!

(Remember, the first 3 calls from a script are free – and each call after that is 1/2 count).

Fewer calls = lower server utilization = lower costs = faster scripts. It’s win-win-win folks!

SAML End-user Authentication

brainCloud has been enhanced to support SAML for end-user authentication. This is mostly relevant for non-gaming* customers who want to integrate their brainCloud app with a corporate directory.

Our SAML authentication builds upon the External Authentication feature, providing several key endpoints that can be used for initiating calls and receiving callback from the SAML identity provider.

See the SAML Authentication knowledge-base article for more information.

Random Custom Entities

We have added a new API that supports the retrieval of random custom entities.

The new API is called GetRandomEntitiesMatching() and takes as parameters the entityType, a JSON query filter, and the number of entities to return. 

API Keys

We are developing a new Builder API mechanism for developers. This will enable API-driven management of teams, apps, and scripts via external services and tools.

We are hopeful that this, together with Cloud Code folders (coming soon), will allow devs to more efficiently integrate brainCloud with their build processes.

Our new API keys system is a foundational building block. To access any Builder API method, the following conditions must be met:

• Builder API access must be enabled for the Team itself
• Builder API access must be enabled for the User who owns the key (on the target Team)
• The Builder API key must be valid and not expired

We will provide more information on the Builder API in the coming months.

RTT Connection Handling

As mentioned above, we have made significant improvements to RTT Connection Handling in the client libraries.

The improvements across all libraries include:

• Refactored the underlying code to keep track of RTT connection state via a new RTTConnectionStatus enum with the following values – CONNECTED, DISCONNECTED, CONNECTING and DISCONNECTING.
• Added a new GetConnectionStatus() method to return this status. 
• The existing IsRTTEnabled() call still works – but now simply returns true if the status is CONNECTED.

In Unity and Unreal, we have also:

• Added a new WebsocketStatus enum (with values OPEN, CLOSED, MESSAGE, ERROR, and NONE) which is used internally to keep track of the WebSocket status. This allows the library to catch an annoying Android background app bug where the RTT connection closes because of the WebSocket closing — and notify the client app to re-establish its RTT connection.
• Improved error handling in Unity RTT now gives more information about what happened with the RTT connection.

Portal Changes

We have made the following portal changes:

Team

• Manage | Members
  • Added a column to show which users have API Keys defined for this team
  • Also added a new Builder API Access option to the Permissions tab of the user settings
• Manage | Team Info
  • Added a toggle for enabling Builder API Access

Design

• Cloud Code | API Explorer
  • The new API Usage Stats log is now added to response when cloud code scripts are called.
• Cloud Code | Scripts, Script Editor
  • The new API Usage Stats log is also appended to the responses in the Run tab of the Script Editor.
• Cloud Data | Custom Entities
  • The index list screen now displays the index key fields – providing a much better overview of index coverage.
• Integrations | Manage Integrations
  • A new SAML Settings section has been added to the integrations screen.

Monitor

• Group Monitoring | Groups
  • We have added a new feature that allows Portal users to remove members from groups.
• User Monitoring | Recent Users
  • We now capture and display the version of the client app that users are using to login. 
• User Monitoring | Logs
  • A new [Refresh] button has been added. Very useful when viewing the live logs of a user while debugging.

App Version now displayed in Recent Users list…

Reporting

• API Usage
  • We now break down custom entity operations by entity type – providing better insight into the performance of individual entity types.

General

• Edit Profile | API Keys 
  • You can now create API Keys for use with our Builder API – coming soon! 

API Changes

The following changes/additions have affected the brainCloud API:

• Custom Entity
  • (New!) GetRandomEntitiesMatching() call added for returning a set of random entities from a filtered list of candidates.
• File
  • (New!) FileUploadFromMemory() call added to allow uploads to happen in situations where local file access is not possible or convenient. For example, screenshots from Unity-based WebGL apps. Note – Unity client only.
• Group
  • (Improved!) Sys APIs for Groups and Group Entities are now available from S2S
• RTT
  • (New!) GetConnectionStatus() call returns the status of the RTT WebSocket connection ( CONNECTED, DISCONNECTED, CONNECTING and DISCONNECTING).

The following methods are newly marked as deprecated:

• PlayerState
  • UpdateName() deprecated – use UpdateUserName() instead… (which is no longer marked as deprecated – it was a mistake!)

The following previously deprecated methods have been removed from the 4.6+ client libraries:

• Authentication
  • GenerateGUID() and GenerateNewAnonymousId() removed – use GenerateAnonymousId() instead.
• Client
  • GetGameId() removed – use GetAppId() instead.
  • GetGameVersion() and GetVersion() removed – use GetAppVersion() instead.
• Entity
  • GetSharedEntityForPlayerId() removed – use GetSharedEntityForProfileId() instead.
  • GetSharedEntitiesForPlayerId() removed – use GetSharedEntitiesForProfileId() instead.
  • GetSharedEntititesListforPlayerId() removed – use GetSharedEntitiesListForProfileId() instead.
• Friend
  • FindPlayerByUniversalId() and FindUserByUniversalId() removed – use FindUserByExactUniversalId() or instead.
  • ReadFriendPlayerState() removed – use ReadFriendUserState() instead.
• Gamification
  • ResetMilestones() removed from client libs – still available from cloud code.
• PlaybackStream
  • GetStreamSummariesForInitiatingPlayer() removed – use GetRecentStreamsForInitiatingPlayer() instead.
  • GetStreamSummariesForTargetPlayer() removed – use GetRecentStreamsForTargetPlayer() instead.
• PlayerState
  • DeletePlayer() removed – use DeleteUser() instead.
  • ReadPlayerState() removed – use ReadUserState() instead.
  • ResetPlayer() removed – use ResetUser() instead.
  • UpdatePlayerName() removed – use UpdateUserName() instead.
  • UpdatePlayerPictureUrl() removed – use UpdateUserPictureUrl() instead.
• PlayerStatistics
  • IncrementPlayerStats() removed – use IncrementUserStats() instead.
  • ReadAllPlayerStats() removed – use ReadAllUserStats() instead.
  • ReadPlayerStatsForCategory() removed – use ReadUserStatsForCategory() instead.
  • ReadPlayerStatsSubset() removed – use ReadUserStatsSubset() instead.
  • ResetAllPlayerStats() removed – use ResetAllUserStats() instead.
• PlayerStatisticsEvent
  • TriggerPlayerStatisticsEvent() removed – use TriggerStatsEvent() instead.
  • TriggerPlayerStatisticsEvents() removed – use TriggerStatsEvents() instead.
• Product
  • This legacy Product service has been been removed. Use the replacement AppStore or VirtualCurrency services instead.

Miscellaneous Changes / Fixes

• Updated libraries
  • All libraries have been updated. Go get ’em!
• Documentation updates
  • Added new knowledgebase articles for dozens of portal screens. Look for the Learn More links!
• Important Fixes
  • BCLD-6427 – In API Explorer/Scripts/S2S Explorer the up/down arrows in the log are not working
  • BCLD-6389 – Restore Checkpoint now properly deletes new custom collections (created or imported) since the selected checkpoint
  • BCLD-6344 – When viewing indexes, the index fields box is not pretty printed
  • BCLD-6352 – ADHOC Division Set Leaderboard Template with Tournament in progress is losing required tournament data on import/deploy
  • BCLD-6320 – C++ cannot tear down WebSocket on Win32
  • BCLD-6343 – Deleting custom indexes shows wrong text – asks if you want to delete the “entity type” instead
  • BCLD-6327 – Import/Deploy custom entity configs (and migratable custom entities) only if target app has applicable billing plan
  • BCLD-6251 – Added support to manage groups and group entities from S2S
  • BCLD-6304 – Identity – GET_EXPIRED_IDENTITIES throwing exception for expired/invalidated Facebook identities
  • BCLD-6322 – Reporting | Analytics page not showing session graph if between 7-8 pm Eastern
  • BCLD-5969 – Added null check for “push content” call in Unity for Abandon/Complete Match with summary data
  • BCLD-6283 – VerifyReceipt() for product that is “Not for Sale” should still work
  • BCLD-6183 – User Items not being exported as part of user data export/archive
  • BCLD-6184 – User Items not being deleted when the user is deleted
  • BCLD-6294 – UpdateGroupData and UpdateGroupName methods not updating UpdatedAt field
  • BCLD-6246 – GoogleOpenId identity cannot be detached
• Plus miscellaneous fixes and performance enhancements…

brainCloud 4.5.6 is a very focused release – but much more significant than the version number would imply.

This update brings the release of our new Version 2 Relay Servers – which are more reliable, more feature-rich, and faster to launch than our original Relay Servers.

Important: The RelayComms V2 Protocol (used by brainCloud 4.5.6 and newer libs) is not compatible with the RelayComms V1 Protocol (used by brainCloud 4.5.5 and older libs). The recommended migration process is described later in this document.

Release Highlights

Improved Relay Servers

As more and more apps use brainCloud’s Relay Servers, we have realized some limitations with our initial implementation:

1. Defect – reliable acknowledgments don’t consider all combinations of channel * reliable bit * ordered bit * net id (from user). Combinations of reliable/ordered would FAIL if used within the same channel Id. This issue would normally only happen with higher player counts – but it is definitely an issue.
2. Limitation – no way to send a message to a subset of players (e.g. your team in a competitive game). V1 only allowed for sending to all, or to a single specified user
3. Limitation – no protocol version embedded in the protocol – which makes it near impossible to modify/extend/correct the protocol and maintain compatibility with older clients.
4. Unoptimized – the Docker container used to launch the relay servers wasn’t properly optimized to improve launch times. 

The good news is that we have addressed these limitations with Version 2 of our RelayComms Protocol – and incorporated it into our new Relay Servers and 4.5.6 Client Libraries. 

The better news is that the Client APIs for the new RelayComms is almost completely compatible – that is, you don’t need to change your client code to use the new servers – other than:

• In C#-only, you need to adjust for the new netId parameter in the RelayCallback() method ← note, this was a defect. The other languages already had that parameter in their callback method.
• If migrating a Live application, you will need to substitute in the new lobby ids (see the migration procedure section below)

The bad news is that our new V2 Relay Servers are not compatible with our 4.5.5 and older client libraries – so they only work with brainCloud 4.5.6 libs and greater. Conversely – the new 4.5.6 libs do not work with the legacy Relay Servers – so migrating your apps to the new Relay Servers (which we highly recommend) must be done carefully. We provide the details on how to do this without interruption in a section below.

Note – The V1 RelayServers will continue to function for the foreseeable future (at least 1 year) – so you do not need to force a short-term upgrade to your app. It is highly recommended that apps upgrade when they get a chance however.

Matchmaking Optimizations

This release also includes some serious optimizations to brainCloud’s Online Matchmaking and Lobby System algorithms – resulting in:

• greater lobby queue scalability
• much faster best-case room/relay server launches

Note that these changes are completely under-the-hood – no API changes required.

Miscellaneous Changes

The following changes are also included in this release:

• Amazon Platform detection – has been added to all of the libs (except C++). Important – be sure to turn on the “Amazon” platform on the Design | Core App Info | Platforms page for your app. This is important even if you aren’t using Amazon IAP – otherwise, your Android app won’t launch on Amazon devices!
• Ability to clone Lobby and Server types – has been added to facilitate easier migration to the new Relay Servers
• Improved WebPurify integration – are servers are now properly encoding problematic text characters before sending them to WebPurify

Procedure: Relay Server Migration

The following approach is recommended for migrating your app from V1 Relay Servers → V2 Relay Servers. 

This approach has been designed to:

• ensure the app is available to all players throughout the migration
• support the various app store review processes 
• keep the developer in control of the timelines of the migration.

Approach

Benefits: This approach allows users of your old client to continue to play using the V1 Relay Servers – even as your updated client goes through app store reviews, soft launch, etc. using the new V2 Relay Servers. And then, after your release has been deployed globally and across all platforms, you can “force” users to upgrade to unite all players together again.

The executive summary of the recommended approach is:

• Clone the Lobby and Server definitions of your app – producing a new set of V2 Lobbies and V2 Servers that will be used by the updated versionof your app
  • Configure the V2 Server definitions to use Relay Protocol v2
  • Configure the V2 Lobby definitions to use the new V2 Server definitions
• Modify your Client App to use the new V2 Lobby definitions, as well as the appropriate 4.5.6 Client Library
• Optionally (but recommended), ensure that your Client App reacts to the Minimum Version setting from the Design | Core App Info | Platform page. This will allow you to “force” your users to upgrade to the new client when you are ready (see Version Enforcement)

Step-by-step

This section describes step-by-step how to modify your app to implement the recommended migration approach.

Design Portal

1. Go to Design | Cloud Code | My Servers – and clone the Relay Server entries to create new “V2” versions. A new [Clone Server] button has been added to assist with this. After cloning each entry, be sure to Edit it, and change the Relay Protocol to v2!
2. Go to Design | Multiplayer | Lobbies – and clone the Lobby entries to create new “V2” versions. A new Clone option has been added to the Action menu to assist with this. After cloning each entry, be sure to Edit it, and change it to refer to one of the V2 Servers that you created in Step 1.

App Code

1. Replace your brainCloud library with a new 4.5.6+ version of the client library.
2. Go into your source code, and change the names of the Lobbies that your client app references to the new V2 version of the lobby type name.
3. Rebuild and test your client app to ensure everything works.
4. (Optional – but highly recommended) If you haven’t already, enhance your app to pass the app version during the BrainCloudWrapper.Initialize() method, and display a “Client update required” dialog if it receives a 40322 – APP_VERSION_NOT_SUPPORTED error from the server during authentication. This will allow you to force users to upgrade to the new client when you are ready. Note – the required app versions are controlled via the Design | Core App Info | Platforms page.

For more information on implementing Version Enforcement in brainCloud, see the article at the link.

App Submission & Migration

1. Submit the updated app (which uses the V2 Relay Servers) to the various app stores for approval. Existing users will continue to play using the V1 Relay Servers.
2. Officially Release your app. During this stage of launch, your player liquidity is split – between the older and newer servers.
3. (Optional – but highly recommended) Once you are ready (and are confident that the app updated has been distributed globally to all appstores), you can update the minimum required versions on the Design | Core App Info | Platforms page to force users to upgrade, and re-unite your player base!

And voila – you have successfully migrated your app to the V2 Relay Servers without interruption!

Portal Changes

We have made the following portal changes:

Design

• Cloud Code | My Servers
  • Added new [Clone Server] button to make it easier to duplicate server configurations
• Messaging | Chat
  • The Replace Profanity with setting now properly defaults to “*”
• Multiplayer | Lobbies
  • Added a Clone option to the Action menu to make it easier to duplicate lobby configurations

API Changes

Reminder – The 4.5.6 client libs only work with the V2 Relay Servers.

If your app is live and using Relay Servers, do not upgrade to the 4.5.6 Client Libraries until you are ready to migrate your app according to the procedure described in these release notes.

Although the Client libraries have changed significantly to support RelayComms V2, the APIs themselves have not.

There is just one fix to the C# libraries that affect a method signature:

• The RelayCallback() method signature has changed. It now includes a netId parameter.public delegate void RelayCallback(short netId, byte[] data);

Miscellaneous Changes / Fixes

• Updated libraries
  • All libs have been updated to use RelayComms V2!
  • All libs (except C#) now include Amazon Platform detection. Important: If your app supports Android, and you want your Android apps to run on Amazon devices, remember to enable the Amazon platform on the Design | Core App Info | Platforms page!
• Documentation updates
  • The API Reference has been updated to include the updated C# RelayCallback
• Important Fixes
  • BCLD-6304 – Error sending certain chat messages with WebPurify support enabled
  • BCLD-6240 – Presence updates sometimes failing due to improper TTL setting
  • BCLD-6239 – Lobby matchmaking NPE
• Plus miscellaneous fixes and performance enhancements…

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…