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:

{

  "action": "continue",

  "label": "Continue",

  "hover": "Return to Login",

  "targetUrl": "http://myapp/login"

}

Hand-off API

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:

1. Passing the user’s credentials from one system to another <- major security concern
2. Asking the user to login again <- usability issue
3. 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:

1. App A: The user is logged into brainCloud normally, and a session created
2. 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.
3. 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
4. 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:

1. Names are not unique. Like in the real world, multiple people can have the same name.
2. 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.
• Later you can call UpdateUniversalIdLogin() to update the username if the user desires
• To search for the user via the api, use GetProfileInfoForCredential( “anId”, “Universal”)
• 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:

• Authentication
  • New Handoff Authentication call added: AuthenticateHandoff()
• Identity
  • New API for creating handoff ids: CreateHandoffId()
  • New AttachNonLoginUniversalId() API has been added.
• HttpClient
  • 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 3.9 is here! Check out the new hotness! 

Release Highlights

Online Presence

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

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

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

In addition, presence supports:

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

For more information, see the Presence Service API Reference.

Note – Online Presence requires brainCloud RTT.

Tournament Divisions

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

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

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

The advantages are significant:

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

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

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

Refactored Currency and In-App Purchase APIs

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

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

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

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

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

Customer Requests

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

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

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:
    1. First create a tournament-enabled Leaderboard to act as a template (setting the template flag to enabled)
    2. Then create the division set, selecting the Leaderboard template and configuring the maximum # of players per division instance
    3. Use the new Tournament Division APIs to join the tournament!
• Marketplace | Products
  • We have made a bunch of under-the-hood changes to allow for easier integration of new AppStores in the future
  • The screen should work largely as before – let us know if you experience any issues!
• Messaging | Presence
  • New screen for configuring the new Presence service
  • Once enabled, any RTT connection established by a client will contain basic presence info (i.e. online/offline) as well
  • From there, rich activity and real-time updates can be enabled as well

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!
• Group Service
  • Users can now call RejectGroupJoinRequest() to reject a join request that they have made
  • New APIs for managing groups: SetGroupOpen() and UpdateGroupACL()
• Leaderboard Service
  • New versioned social leaderboard calls – GetSocialLeaderboardByVersion(), GetPlayersSocialLeaderboardByVersion()
• Product Service
  • Important: The Product Service is being deprecated in favour of the new AppStore and VirtualCurrency services.
  • The service and its APIs will continue to work until July 1st, 2020.
  • There is a new compatibility flag in the portal under Design | Core App Info | Advanced Settings, which controls how purchase transactions are written to the database. Keep [x] Enable legacy Purchase Collection support checked if your app uses the old Product APIs, or a mixture of the old Productand new AppStoreAPIs. New apps that will only use the new AppStore APIs can feel free to clear that flag.
  • Although deprecated, we did add the missing cloud-code version of the VerifyItunesReceipt() back to the service (for those who need it!)
• Presence Service
  • There is an all-new Presence service. Check it out!
• Tournament Service
  • New Division Set calls have been added – mostly used when querying and joining a Division Set instance.
  • The new calls are: GetDivisionInfo(), GetMyDivisions(), JoinDivision() and LeaveDivisionInstance()
• VirtualCurrency Service
  • New VirtualCurrency Service for currency operations. The operations are largely the same, with a bit of clean-up.

Miscellaneous Changes / Fixes

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

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)

For more info, check out the Messaging API page.

RTT Online

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

For more info, check out the Lobby API page.

On Demand Tournaments

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 settings 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 been 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 participants
    • 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:

• [New!] Chat
  • Add online chat to your app quickly and easily!
  • Check out the Client and S2S Chat APIs.
• Client
  • [New!] EnableRTT() – Used to establish the RTT connection from the client.
  • [New!] DisableRTT() – Disconnect from RTT.
  • Plus methods for registering and de-registering RTT listeners for Chat, Events, Messaging and Lobbies.
• Event
  • No more polling! SendEvent() now sends a realtime event to the recipient if they are currently online, and RTT is enabled.
  • See the RegisterRTTEventCallback() API for details.
• GlobalEntity
  • Made the following system entity calls available from client session cloud-code scripts (they were previously S2S only)
    • CreateSystemEntity(), GetSystemEntityList(), GetSystemEntityListCount(), GetSystemEntityPage(), GetSystemEntityPageOffset(), and ReadSystemEntity().
  • GetListByIndexedId() now returns entityListCount in addition to the list of items.
• [New!] Lobby
  • Add online matchmaking, full lobby support and easy custom server integration to your app.
  • Check out the Client and S2S Lobby APIs.
• [New!] Messaging
  • Add user-to-user messaging to your app, with optional real-time delivery via RTT.
  • Check out the Client and S2S Messaging APIs.
• Product
  • Added the missing VerifyItunesReceipt() call to Cloud Code.

In addition, all brainCloud file downloads (global and user) are now resumable (we have added the “Accept-Ranges” header).

Miscellaneous Changes / Fixes

• Updated libraries
  • RTT support, with Chat, Messaging and Lobby APIs, have been added to the Unity, Java and Javascript libraries. More libraries will follow soon!
  • All libraries have been updated with improved retry and packet-in-progress handling
  • Our Javascript library now directly supports NPM. Include braincloud-js to grab it.
• Documentation updates
  • We have updated the docs to reflect the new brainCloud services
• Plus miscellaneous fixes and performance improvements

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.

The ListFriends(), GetSocialLeaderboard(), GetPlayersSocialLeaderboard() and GetMultiSocialLeaderboard() APIs have all been enhanced to utilize inherited friends.

More Flexible Matchmaking

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.

The new API methods are: FindPlayersUsingScript() and FindPlayersWithAttributesUsingScript().

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-onlyrole 
  • 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.
• Matchmaking
  • Two new cloud code APIs allow you to override the player rating and filter script used in matchmaking – FindPlayersUsingScript() and FindPlayersWithAttributesUsingScript()

Plus the ReadProperties() method is now available from the S2S API.

Miscellaneous Changes / Fixes

• Updated libraries
  • All libraries have been updated with the new APIs. We recommend that all apps upgrade!
• Documentation updates
  • We have updated the docs to reflect the new API calls
• Important Fixes
  • BCLD-2777 – Portal: when adding to the [Job Queue], the “Save” button becomes available without selecting a script
  • BCLD-2783 – Changing apps while on the script page causes the Peer Script Service not to update in the API Explorer
  • BCLD-2790 – Portal: [Monitoring] –> [Group Entities]: the data for a group entity is shown as an escaped JSON string, not nicely printed
  • BCLD-2904 – User Attributes don’t reset on reset
  • BCLD-2927 – fixed duplicate HTML ids across all pages
  • BCLD-2985 – User Monitoring | Friends – need space between friend name and email
  • BCLD-3003 – Team Select Screen – When the User adds a new team it does not appear in the select team drop down
• Plus miscellaneous fixes and performance enhancements…

This release is a minor update with some key optimizations and defect fixes.

Feature Highlights

Faster Leaderboards and Tournaments

We’ve spent considerable time profiling and optimizing key tournament and leaderboard APIs – we think you’ll like the results:

• GetGlobalLeaderboardView() is now up to 25X faster! This is especially apparent for leaderboards of 50K or more users where the player doing the retrieval is near the end of the leaderboard
• PostTournamentScoreWithResults() is also up to 50X faster! We had recently pulled that call out-of-service due to performance issues – we hope to reinstate it in a few days after we’ve got more real-world data

Miscellaneous Fixes

The following defects have been addressed in 3.6.6:

• BCLD-2782 – Portal: Trying to “View Team” from Super > Users switches to random team instead of the selected team
• BCLD-2777 – Portal: When adding to the Job Queue, the “Save” button becomes available without selecting a script
• BCLD-2793 – Portal: Super – System Properties’ Categories drop-down does not function properly once a category is selected
• BCLD-2847 – Portal: Part of WebHook URL changes to “null” after saving and re-opening it
• BCLD-2821 – Portal: User Monitoring | Statistics – always shows “0 records”
• BCLD-2802 – Portal: dropdown/context menu on Design | Custom Config | Files appears partly off the right side of screen
• BCLD-2861 – Portal: Core App Info | Admin Tools – Deployment: Checkbox of second option gets checked while clicking on the text of the third option.
• BCLD-2786 – Portal: Mouse-over texgt is either missing or incorrect (multiple locations)
• BCLD-2856 – API: In some cases, non-shareable files can be downloaded without a session
• BCLD-2826 – API: Leaderboard: GetGlobalLeaderboardView ranges now working properly with duplicate scores
• BCLD-2830 – API: PostTournamentScoreWithResults reports the wrong error if a player is not registered
• BCLD-2813 – Portal: Super user cannot perform “Sys Enable” action to enable an app that has been previously disabled
• BCLD-2824 – Portal: Design | Integrations – the first three fields for SendGrid integration should have * next to titles to indicate required
• BCLD-2825 – API: PostScoreToLeaderboard fails on any leaderboard that ever had a tournament attached

Portal Changes

There are no changes to the portal in this release.

API Changes

The following changes/additions have affected the brainCloud API:

• Tournament
  • PostTournamentScoreWithResults() – we have removed the previousLeaderboard section of the returned JSON. It was debugging information that mistakenly got left in the response during initial development.
• Client Library
  • We have added a new IGNORE_SSL_CHECK compiler directive to the C# library. Useful for when connecting an app to a developer-deployed brainCloud instance.

Miscellaneous Changes / Fixes

• Updated libraries
  • All libraries have been updated with the refactoring and latest API enhancements. We recommend that all apps upgrade!
• Important Fixes
  • See the list in the Feature section
• Plus miscellaneous fixes and performance enhancements…

We thought we’d take a moment to discuss the pros and cons of the design, and explain where and why we are going a different route.

Background

To start, lets review the purpose and design of the client library.

The goal of the client library is to simplify development of brainCloud-based applications. It does this by:

• providing local implementation of brainCloud client calls (instead of forcing the client app to use Raw REST calls)
• automating communications with the server (bundling of messages for efficiency, packet security, and more)
• performing standard error handling

The library is actually organized into two major components:

• the brainCloud Client Library – a pure, platform-independent wrapper of the brainCloud client-server protocol
• the brainCloud Wrapper – simplifies aspects of the API (especially authentication) by incorporating more client-side functionality, like saving and restoring anonymousIds and profileIds.

Use of the client library is required by apps. Use of the wrapper is highly recommended, but optional. Note – originally we only had the client library. The wrapper was added later as an aid to app developers. 

Delving deeper into the design, you can see that the client object maintains a list of services and internal components that work together to provide the client functionality. The wrapper on the other hand is quite simple, and merely adds an additional simplification layer to the API.

Of significance here is the use of singletons. There are two singletons in play – one for the client, and one for the wrapper. Not only are the singletons used as the reference from the client to the wrapper and/or client library objects – but they are also used for communications between BrainCloudWrapper and BrainCloudClient.

In hindsight, although our intentions were good – this usage of singletons was a mistake.

The cons (as we now see them) are:

• Complicates the client code (calling the static class methods to retrieve a reference to the wrapper and or client object is more painful than using a direct global of some sort)
• Complicates the documented code examples
• Restricts a client to have one-and-only-one connection to the brainCloud server [ this is a crippling restriction for some use cases – couch co-op anyone? ]

The fix

And so, we are fixing this.

The changes to the new client libraries are three-fold:

• BrainCloudWrapper objects now have their own reference to their associated BrainCloudClient companions
• BrainCloudWrapper objects also now provide direct methods for accessing the client services: you no longer have to call wrapper → client → service → operation, instead it is simply wrapper → service → operation

The result is that instead of your client code looking like this:

BrainCloudWrapper.Instance.GetBC().LeaderboardService.ListAllLeaderboards( ApiSuccess, ApiError);

It can look like this:

_bc.LeaderboardService.ListAllLeaderboards( ApiSuccess, ApiError);

The Changes

So – more flexibility and clearer code? What’s the catch?

The catch is that you need to make a few changes to your client to get this goodness. For new apps it’s no big deal at all – this could be a pain for existing apps though, so we are still including a legacy singleton mode in the client libraries – but that needs to be specifically enabled.

Update: Legacy Singleton Mode has been removed from brainCloud client libraries beginning with 4.0. 

Here are the steps to getting your app working using the updated libraries

1. Grab the latest brainCloud client library from the portal via the Team | Client Libs page.
2. Create an instance of BrainCloudWrapper and save it to a global accessible throughout your client app. In our documentation examples we use _bc, but it can be anything
3. Adjust any client code to use this new reference – try searching and replacing
   1. “BrainCloudWrapper.Client.” → “_bc.”
   2. “BrainCloudClient.Instance.” → “_bc.”

And that’s about it.

Note – you can optionally specify a _wrapperName to use creating the wrapper. This name will be used as a key when storing data about the session, like the anonymousId and profileId.

You only need to specify the _wrapperName if you are implementing a client with multiple concurrent connections to the brainCloud server (to help keep the session data separate). In particular, if you are updating an existing app, do not specify a profile-name – this ensures that the user does not lose their saved profile references when they upgrade to the latest version of your app!

_bc = new BrainCloudWrapper(); // optionally pass in a _wrapperName
_bc.initialize(_appId, _secret, _appVersion);

_bc = go.AddComponent<BrainCloudWrapper>();
_bc.WrapperName = "_example"; // optionally set a wrapper-name
_bc.Init();

Legacy Singleton Mode

Update: Legacy Singleton Mode has been removed from brainCloud client libraries beginning with 4.0. 

Want to move to the new libraries, but change as little code as possible? No worries, we have you covered. Here’s what you do:

1. Grab the latest brainCloud client library from the portal via the Team | Client Libs page.
2. Turn on legacy singleton mode via the BrainCloudClient.EnableSingletonMode() API call. Put the call in your code right before you initialize the library.
3. Unity only (and only if you were using the Client static class accessor):
   Adjust any calls to BrainCloudWrapper.Client.aService().anOperation() to use BrainCloudWrapper.Instance.Client.aService().anOperation() instead (Note the additional Instance step).

The following code snippet shows how to enable singleton mode in various languages:

BrainCloudClient.EnableSingletonMode = true;  // Turn on legacy singleton mode
BrainCloudWrapper.getInstance().initialize(_appId, _secret, _appVersion);

BrainCloudClient.EnableSingletonMode = true;  // Turn on legacy singleton mode
BrainCloudWrapper.getInstance().Init();

Conclusion

Anyway, thats the summary of what we have changed, and why.

We hope you agree that the improvements to functionality and readability are worth it.

If you have any feedback or concerns, feel free to hit the chat link and let us know.

Cheers!

We are pleased to present release 3.6.5 – just in time for the holidays!

Note that there are some breaking changes in the client libraries – but they are pretty simple to accomodate, and of course will not affect your app until you update. For more details, see the Refactored Client Libraries section below.

Feature Highlights

Fresher Matchmaking

We have added a new expiry feature to keep your matchmaking fresh. It is implemented via a nightly process that will disable the matchmaking flag for users that haven’t logged into the app within the specified number of days.

Enabling this feature will ensure that players don’t get matched with opponents who haven’t recently logged into your game.

Important notes:

• The nightly process only runs for Live apps. This feature does not affect apps still in development. (This saves server cycles, plus while in development it is tough to get enough players to match against already!)
• Auto-Expiry is turned OFF by default for existing apps.
• Auto-Expiry is turned ON by default for new apps (with expiry set to 30 days).
• Important: brainCloud will not automatically re-enable matchmaking for a disabled user once they login. Apps using this feature should directly call EnableMatchmaking() whenever a user launches the app.

Batch Scripts

A common customer request has been a way to iterate through the population of an app’s users, performing some operations on each user’s account. It has taken some time to find a proper way to do this that is scalable and safe – but we are pleased to announce that the first evolution of this is now in place.

We have introduced a new S2S Script Service method called RunBatchUserScript(). This script can be called via the S2S Explorer or from an external server – and queues the specified script to be run against each of the users in a app (or optionally, against particular segments). Although the RunBatchUserScript() is triggered from the S2S context, each individual script is run in the context of the current player – so it is as if the script was called by that user’s logged-in session – greatly simplifying the script code.

Here’s an example script that writes a global entity (singleton) for each player it is run upon:

var result;

_globalEntityService = bridge.getGlobalEntityServiceProxy();

var acl = { "other": 1 };
var customData = { "test": "info" };

result = _globalEntityService.createEntity(data.entityType, null, acl, customData );

result;

You can call it via the S2S Explorer like this:

Note that the scripts get queued to run on the users in the background – and depending upon the app’s population may take several minutes or potentially several hours to complete.

Refactored Client Libraries

The brainCloud client libraries have been refactored for greater simplicity and flexibility. Key improvements with these changes are:

• Support for multiple connections per device ← useful for devices that require multiple concurrent user logins – couch co-op, anyone?
• Saved wrapper data is now differentiated with a wrapperName value ← necessary to support multiple connections
• Access to all client services from the wrapper ← means the wrapper becomes largely invisible
• Simpler client code ← yay!

Key API changes

The key change that allows this is the deprecation of the singleton behaviour of the brainCloud client libraries. As you may or may not know, for convenience the brainCloud client libraries declared singletons for both the BrainCloudWrapper and BrainCloudClient library classes. This provided a bit of convenience for developers – but at considerable costs to flexibility (and frankly, some code readability issues). We are hereby deprecating this behaviour.

In addition, we are making the client services callable directly from the wrapper – which greatly simplifies calling them (and abstracts whether you are calling via the wrapper or directly from the client).

For comparison – here are what two calls to the leaderboard API look like – before and after this API change:

// Old: Call leaderboard API via the wrapper singleton, to the leaderboard service via the BrainCloudClient object
BrainCloudWrapper.GetBC().getLeaderboardService.ListAllLeaderboards( ApiSuccess, ApiError);

// New: Same call. Note that whether _bc is an instance of BrainCloudWrapper or BrainCloudClient, this code looks the same. Simpler, eh?
_bc.LeaderboardService.ListAllLeaderboards( ApiSuccess, ApiError );

These improvements mean that some client code has to change – but the changes are pretty simple, and we believe well worth-it (see below).

Existing apps have the following options available to them:

• No changes – stay with brainCloud libraries earlier than 3.6.5
• Minimal changes – move to brainCloud library 3.6.5, but turn the legacy singleton mode on
• Full changes – move to brainCloud library 3.6.5, initialize the brainCloud wrapper to your own global(s), and adjust your calling code accordingly

We highly recommend that new apps use the new paradigm – your code will be simpler for it.

For more information, see our blog post with the full details and rationale.

Portal Changes

We’ve made the following portal changes for this release:

Team

• Navigation
  • We have restructured the Team navigation menu to better group the features. In particular, all of the Admin-management features are now located under the Manage menu.

Design

• Core App Info | Advanced Settings
  • Disable Live Lock – Live Lock helps to protect your live apps by forcing you to unlock them before editing. You can now disable this behaviour if you would like (Note – not recommended for production apps!)
• Integrations | Sendgrid
  • Fixed an issue where test emails were no longer being sent when the [Test] button was pressed.
• Multiplayer | Matchmaking
  • Expire matchmaking – Automatically expire (disable) a user’s eligibility for matchmaking after <x> days without logging in. Helps to ensure that your players are matched with fresh opponents, instead of players who may no longer be active in your app!

Monitoring

• User Monitoring | Logs
  • New Export feature exports requests and responses in their entirety… (before was limited to request and response summaries)

General

• User Settings
  • Language and Timezone settings are now stored to the developers account profile (instead of local web storage). Also addressed an issue with daylight savings time.
• Entity Editors
  • Global Entity Editor, Group Entity Editor and User Entity Editor have all been updated to handle Long values better.

API Changes

The following changes/additions have affected the brainCloud API:

• Client
  • EnableSingletonMode setting – if you wish to use the brainCloud singleton mode, it is still available, but it must be explicitely enabled. You can do so by setting BrainCloudClient.EnableSingletonMode = true in your app.
• Multiplayer
  • <New!> IncrementShield() – allows you to increment the shield setting without reading it first. Especially useful when extending a shield that is already in place.
• Script Service
  • <New!> RunBatchUserScript() – allows you to queue a script to be run against all of your apps’s users! (or select segments)
• Wrapper
  • Singleton behaviour is now deprecated, but can be re-enabled using the EnableSingletonMode setting of the Client.
  • All of the brainCloudClient service accessors (except AuthenticationService) have been added to the wrapper.
  • Unity: Removed static class method Client() (which returned the client singleton) and replaced it an instance-level Client() get / set accessor (which returns the client object associated with this wrapper instance).

Miscellaneous Changes / Fixes

• Updated libraries
  • All libraries have been updated with the refactoring and latest API enhancements. We recommend that all apps upgrade!
• Documentation updates
  • We have updated the docs to reflect the new client calling conventions
• Miscellaneous updates
  • We have updated brainCloud to use version 2.7 of the Facebook Graph API
• Important Fixes
  • BCLD-2756 – Losing verification code on merging Email account into another account
  • BCLD-2746 – PostTournamentScore/WithResults should auto-join player if Auto Join enabled for leaderboard config
  • BCLD-2742 – Rank added to postTournamentScoreWithResults
  • BCLD-2739 – Fix to before and after handling of postTournamentScoreWithResults
  • BCLD-2721 – When attaching an Email identity and app email feature Send Verification Email is checked , we aren’t updating player emailAddress when should be
  • BCLD-2710 – PostTournamentScore(WithResults) – Null pointer exception when posting score to a leaderboard with tournament configured but not active until Next Cycle
  • BCLD-2699 – GlobalEntity Raw Export fails to import when <timeToLive> is 0 (Integer vs. Long)
  • BCLD-2696 – Portal – If you switch apps while editing a web service the page does not update
  • BCLD-2662 – Non Admin Users see the Remove option in the actions menu of the Members page
  • BCLD-2607 – Disable the [Go Live] button once the user clicks it
  • BCLD-2597 – Portal – If data field for an Entity contains an integer that is too high show a proper error dialog
  • BCLD-2594 – Segment country-code not standardized as UPPERCASE
  • BCLD-2593 – BigInteger web defect – GlobalEntity, ChildEntity, Group and GroupEntity editors
  • BCLD-2646 – Fix the banner in Safari
• Plus miscellaneous fixes and performance enhancements…

brainCloud 3.6 is a mid-sized release with a few key improvements. It also includes a lot of refactoring under the hood as we prepare for bigger features that are coming down the pipes.

Upgrade notes: There are no breaking API changes in this release. Do be careful of importing older Global Entity export files into this release, as the default entityIndexedId field has changed (_eid -> _eiid) – just ensure that the correct field is selected during the import. Finally, as always, it is advised the customers update to the latest libraries for maximum performance and stability.

Release Highlights

New Unity Plugin

We have an all-new Unity Plug-in for you.

The new plug-in has been totally re-written, and offers the following cool new features:

• Automatically retrieves your appId and secret – no more cutting and pasting!
• Easily switch between brainCloud app configurations – e.g. develop vs. production, etc.
• Quickly create new application configurations – right from the plug-in!
• Actively aid in debugging your brainCloud app – displays the currently logged in end-user’s profileId, as well as most recent server request and response
• Provides quick access to the new bcConsole client log pane
• Quick access to the brainCloud Portal and documentation pages
• Unity dark theme support!

To install the new plug-in, simply go to our GitHub site and follow the instructions!

[Popular Request] Global Entity Import/Export Enhancements

We have expanded our support for importing and exporting the Global Entities of your apps.

Most importantly, we ha’ve added support for what we call Raw JSON Object format files – which in addition to serializing the custom data portion of your objects, also serialize the meta-data portion of the Global Entity – which includes the object’s entityId, owner, ACL, etc.

This means that a Raw Global Entity export is really an exact representation of your entities – and is much more suitable for backing up your entities, as well as migrating those entities to another app (i.e. moving from development → production).

You will find more details about the Global Entity file formats here.

[Popular Request] User Export Enhancements

We’ve added two popular requests to your User Export functionality:

• Better end-user filtering – you can now select whether to include test users or not in your exports
• User statistics in CSV format exports – we now allow User Statistics to be included in CSV format exports.  (Previously they were only supported for JSON-format exports.)

You are welcome!

Portal Changes

You will notice changes to the following portal screens:

Design

• Gamification | Achievements
  • Improved support for Google Play achievements

Monitoring

• Global Monitoring | Global Entities
  • Added support for additional import/export file formats
  • Includes new Raw JSON Object format, which includes full brainCloud meta-data
  • Improved Import UI to better walk the user through the process
  • Added progress dialog to show activity during larger imports
  • Expanded the maximum # of entities allowed to be imported at a time
  • Updated Bulk Actions menu to better organize the various import, export and deletion options

Reports

• Dashboard
  • Greatly improved presentation and loading behaviour
• Export Users
  • Can now choose the Types of Users to export – end-users, test users, or both.
  • Can now choose to include user statistics in the CSV export

Team

• Team Members 
  • Dialog for inviting a new team member has been improved. You no longer have to fill in the user’s name if they already have a brainCloud account

General

• Banners
  • Greatly improved banner / notice presentation – now behaves across a wider variety of content and screen resolutions.
  • Also we finally found the corrupt banner defect that would occasionally show up on the login screen. Yay!

API Changes

The following changes/additions have affected the brainCloud API:

• GlobalEntity service
  • GetRandomEntitiesMatching() – new API to return a random set of entities matching the specified criteria.

We have also made the following missing methods available via Cloud Code:

• PlayerState service
  • readUserState()
  • deleteUser()
  • resetUser()
  • updateUserName()
  • updateUserPictureUrl()
• PlayerStatistics service
  • incrementUserStats()
  • readAllUserStats()
  • readUserStatsForCategory()
  • resetAllUserStats()
• PlayerStatisticsEvent service
  • triggerStatsEvent()
  • triggerStatsEvents()

Miscellaneous Changes / Fixes

• Updated libraries
  • All libraries have been updated with the latest API enhancements. Go get ’em!
• Documentation updates
  • Upgrading our API Documentation tech to the latest version of Slate – squashing some bugs!
• Important Fixes
  • BCLD-2436 – Scheduled scripts timing out. Fixed issue associated with timeouts of sub-scripts.
  • BCLD-2447 – Product prices in the product list are different from product details
  • BCLD-2451 – User Entities – The total number of records does not update – fixed!
  • BCLD-2453 – Google play support achievement ids now supported in Achievement service
  • BCLD-2475 – added missing renamed cloud code methods (ReadUserState(), etc.)
  • BCLD-2541 – Removed several instances where errors where server errors were being logged multiple times
• Additional changes/fixes
  • Removed obsolete _GAME_LOGINS stat from the Global Stats page
  • Changed the entityIndexedId property included in Simplified Global Entity exports from _eid to _eiid
  • Updated to Facebook Graph API v 2.6 (technically in patch 3.56 prior to this release, but included here for completeness)
• Plus miscellaneous fixes and performance enhancements…

This is a minor update – primarily to upgrade brainCloud’s Facebook support to Graph API v2.4.
Of course we couldn’t resist slipping a few extras in as well.

Release Highlights

Facebook 2.4 API Support

Facebook is forcing a transition of all apps from Graph API v2.3 to v2.4 on July 10th. The release updates all of brainCloud’s services to the new Graph v2.4 minimum API level.

Global Entity Import/Export Improvements

We’ve made exporting and importing of Global Entities even simpler! Now exports automatically include the entity indexed id (_eid) in the exported data, and the system recognizes that field automatically during imports. This saves you from having to specifically select the field to index by during import, and allows for datasets where the indexed value is not duplicated in the custom data section.

Leaderboard Entry Editing

You can now edit the Score and Extra Data fields of leaderboard entries. Useful for support, debugging and nerfing cheaters!

Error Logs Display

We’ve made improvements to how log entries are displayed to make higher severity log entries pop more than lesser entries.

Portal Changes

We’ve made the following portal changes:

Design

• Cloud Code | API Explorer
  • Now allows you to execute API calls and run scripts even if you have disabled your app (via the Design | Core App Info | Advanced Settings page)
  • Usage: Allows devs to temporarily disable their apps and run scripts for maintenance purposes
• Cloud Code | Scripts
  • Scripts can now be run even when the App has been disabled (see above)

Monitoring

• Global Monitoring | Global Entities
  • Export – now explicitely exports the entityIndexedId as _eid
  • Import – now looks for _eid field, and if found, automatically maps it to entityIndexedId for import
  • Editor – details page now shows the Created At and Updated At time+date fields for entities
• Global Monitoring | Leaderboards
  • Score – click on a player’s score to edit it
  • Extra Data – click on the Extra Data “eye” to view and now optionally edit the JSON-format data
• Global Monitoring | Recent Errors
  • Improved formating of log entries to ensure that higher severity items “pop” more
  • Removed the “total pages” pagination – the portal was sometimes timing out when iterating through all entries to perform the count (which isn’t that necessary anyway)

API Changes

There are no API changes in this release.

Miscellaneous Changes / Fixes

• Updated libraries
  • The libraries have not been updated specifically for 3.5.5.
• Documentation updates
  • n/a
• Important Fixes
  • Updated Facebook modules to use Facebook Graph API v2.4+
  • Improved logging of errors for Android, Windows and Steam purchases
  • Improved pre-condition checking before unnecessarily registering products with Facebook
  • Improved logging of “input too large” exceptions
• Plus miscellaneous fixes and performance enhancements…

Release Highlights

Logging Overhaul!

We are revamping our logging facilities. We are not quite complete, but we have some great improvements to share – we hope you like them!

• [Improved!] Recent Errors page – we have totally reworked our error log to improve its usability. We’ve removed unnecessary info and condensed the important details on the list screen, leaving more room for the error message itself. And we have a new combined Details screen replaces the separate Context and Stack details screens from the old log.
• [New!] Error Analytics page – a quick one-page summary of the errors your app is encountering, with one-click access to a filtered view of the error log with just those errors highlighted. Go to Reporting | Error Analytics to view.
• [New!] Unreadable Requests log – a new log for messages that brainCloud was unable to process due to JSON-formatting errors. These errors occur if large multi-packet requests timeout, or if there are errors in constructing the message in the client app. Go to Global Monitoring | Unrecognized Requests to view.
• [New!] Audit Log [beta] – brainCloud now tracks and logs the changes to your app’s metadata – what was changes, and by whom. Note that this facility is currently in beta [we are still completing the instrumentation of some operations].  Go to Team | Audit Log to view.

Plus we’ve greatly expanded the size of the shared log storage, so more history will be available before the logs rotate away!

Entity Editor Enhancements!

We have also continued improving our Entity Editors – specifically the Global Entity Editor and User Entity Editor. The improvements for this release include:

• Filter / Search View – filter the entity view using our JSON query syntax. Makes it easy to search across thousands of entities to find the one that you are looking for. To start filtering, first choose an entity type, and then click the new [Refine] button that appears. Click here for details on the filter syntax.
• Bulk Export– you can now export both Global Entities and User Entities to JSON files. Note that the file formats between the two are somewhat different:
  • User Entity Export (raw) – limited to the User Entities of a single user. The system serializes all the data of the user entities – not just the custom data payload of the entities themselves. This output format is mostly intended for debugging purposes.
  • Global Entity Export (simplified) – the Global Entity export format focuses on exporting the payload portion of the global entities only. This format matches up with the import format – and allows for easy round-trip editing of Global Entities in an external tool.
• Bulk Import [Global Entities only]– you can now more easily import your Global Entities. We now accept a more robust JSON format, that allows for multiple entity types to be included in the same import file.
  • and export Global Entities. The JSON used has been “simplified” for easy compatibility with external tools – like Google Sheets!
• Bulk Delete [Global Entities only] – need to quickly clear out all entities of a type? Just filter by the entity type, and then choose the Delete option from the [Bulk Actions] menu.
• Data Helpers – when editing filters and/or entity contents, the brainCloud enter will attempt to help you complete the names of fields (based on the contents of other entities of the same type).

High Priority Google Push!

Google has recently added support for specifying the priority of push notifications. Under the new system, regular priority messages won’t be delivered or displayed on a sleeping device – so for certain types of apps, it is essential to use their new High Priority notifications feature.

brainCloud now supports FCM, Google’s next-generation push service, in addition to the older GCM service we have always supported.  FCM gives us access to the new Priority messaging feature, and any future features that Google adds.

In addition, we have created a new Raw Push Notifications API. This API gives the developer full access to the notifications payload that is sent to the platform push services. Think of it as DirectX for Push Notifications.

For more information, see the Push Notifications section on API Changes.

Important Note – Auto Deletion of Playback Streams

• As of Release 3.5, brainCloud will take steps to ensure that old playback streams are automatically deleted.
• It was previously the responsibility of the app developer to do so – but there are significant limitations to that approach – so we have built a new system to help
• From 3.5 onwards, playback streams will automatically be deleted after 30 days. App developers are still free to delete them earlier if they would like
• To ensure minimal impact to existing apps, brainCloud will initially start deleting streams older than 180 days. We will reduce the expiry by 30 days each week until
• We don’t envision this being an issue for any of our existing apps – but if it is, please reach out to us!

Portal Changes

We continue to iterate upon and improve the Design Portal and the tools that it provides. This update brings:

Overall

• Improved table presentation – alternating row shading for greater visibility
• Some changes to the menu icons used throughout the portal
• Added a Team Info & Billing option to the Quick menu

Team Section

• [New!] Audit Log
  • The new audit log tracks changes to your apps

Design Section

• Core App Info
  • Advanced Settings – Compatibility Options
    • [New] Include redundant legacy app Ids in some API results flag. See API section for more details.
    • [New] Use legacy GCM for Google Push Notifications – enable this if for some reason you want to stay using Google’s GCM, instead of the new FCM service for push notifications.
• Authentication
  • Email Authentication
    • brainCloud now supports sending Password Reset Emails even if you haven’t linked in a SendGrid account. This screen has been updated to allow editing of the text of the message that will be sent.
• Cloud Code
  • API Explorer
    • Improved Authenticate – Authenticate operation has been enhanced to automatically choose a supported releasePlatform and sufficient appVersion for successful login (these can still be over-ridden).
    • Keyboard Shortcut – Press Ctrl+Enter to run the selected API when you have completed editing the parameters.
    • Jump to User – Click on the Profile Id on the page to jump to that user’s profile in User Monitoring.
  • Scripts Editor
    • Keyboard Shortcut – press Ctrl+S (Windows) or ⌘-S (Mac) to quickly save your script
    • Previous Versions – now shows the data and time that previous versions of the script were saved
    • Improved Authenticate – the Quick Authenticate button will now automatically select an appropriate platform and app version to ensure a successful login
  • API Hooks
    • Authentication Post-Hook – By popular request, you can now attach a cloud code script to successful Authentication requests!
• Integrations
  • Manage Integrations
    • We have removed the Parse Integration section since Parse is no more.
• Multiplayer
  • Matchmaking
    • Concurrent Attacks – There is a new option to allow players to be attacked by multiple players concurrently – requested by the most heartless designers! 🙂

Monitoring Section

• Global Monitoring
  • Global Entities
    • Advanced Filtering – use JSON to specify complex queries for filtering your objects. Syntax details here.
    • Improved Import process – supports more generic JSON formats, including formats with multiple entityTypes in the same JSON file. Note – still compatible with the Parse import format.
    • Bulk Actions– new actions for operating on all of your entities, or all entities of a particular type
      • Delete – delete all entities of the specified type. Note that you
      • Export – export all entities of the specified scope. The export format is simplified to match the import format, and more easily work with external tools.
    • Owner Field – we’ve added the Owner field to the list object, so that system objects (which aren’t owned by an individual user) are easier to identify
  • Recent Errors
    • New Look-and-Feel – we’ve totally revamped the errors screen for greater usability
    • Simplified Error Types – you now just choose between Errors, Warnings and Info messages to view.
    • Quick Filters – We’ve added Filter options to the Action menu on each log entry. Quickly choose to filter the log to see similar errors (i.e. errors involving the same API call) or relating to the same user.
    • More Sources – we are also now showing you messages from more sources. Errors and warning from Client API calls are displayed with a smartphone idon, while errors from the API Explorer show a Compass icon, etc. Hover over any of the source icons for the text name of the error source.
    • Error Details – we have a simpler, more informative Error Details screen – complete with a [Copy All] button conveniently captures the error details (including message, context and stack) into a pretty-printed JSON snippet.
  • [NEW!] Unreadable Requests
    • Purpose– Sometimes brainCloud is process a request sent to it. This is normally because the request is:
      • Incomplete – we didn’t receive the full request. This can happen with larger multi-part messages on the internet.
      • Badly formed – the request is complete, but our servers cannot parse it as proper JSON.
      • Bad signature – the message signature does not match the message content. This indicates that the message may have been tampered with.
    • Utility – Gathering these messages in their own log makes it easier to diagnose what is causing these errors – and hopefully more quickly address the problem.
• User Monitoring
  • User Entities
    • Advanced Filtering – use JSON to specify complex queries for filtering your objects. Syntax details here.
    • Export – export the user entities with full details. Intended for use by developers in debugging.

Reporting

• API Usage
  • Unreadable requests – a count of the unreadable requests received by your app. For details, go to the Global Monitoring | Unreadable Requests page
  • Unprocessed requests – requests that were otherwise valid, but were not processed because they failed a pre-condition check (i.e. session not valid, etc.)
• [New!] API Errors
  • Purpose – shows a summary listing of the errors that your app is encountering, by API call.
  • Error Details – to get more details on the errors reported, click on the Call Name portion of the entry. You will jump to the Recent Errors page, with the log automatically filtered to the service + operation of the selected call

API Changes

New API Calls

• Authenticate
  • [New!] Authentication Post-Hook!  You can now attach a cloud code script to be run upon successful authentication. Especially useful for initializing a user’s account upon initial registration. Pro-tip: Check for “newUser”: true in the authentication response.   
• Bridge
  • [New!] getCurrentTimeZoneOffset() – useful for cloud code scripts that need to do local time calculations. Note that this method is only available via cloud code, and must be called from the Bridge Utility object (i.e. bridge.utils().getCurrentTimeZoneOffset(“America/Montreal”) )
• Client
  • [New!] RestoreRecentSession() – allows the client app to attempt to restore a saved session. Useful if you think the app may have only been temporarily unloaded, and want to try to avoid doing a whole new authentication. Note that we will be more directly supporting this via the Wrapper in brainCloud 3.6 – so you may want to wait for that version of the feature.
    Update: We have discovered an implementation issue with this feature, and are thus pulling it from this release. It will be replaced with a proper version via our Wrapper in brainCloud 3.6. 
• Global Entity
  • [New!] DeleteSystemEntity() method –  allows for easy deletion of system entities (i.e. global entities without owners). Note that for security reasons this API method is available from cloud-code only.
• Mail
  • [New!] SendAdvancedEmailByAddress() – sends a message to the specified email address. Convenient for when your app needs to send a message to someone that is not already a user of your app (i.e. app invites, etc).
• Push Notifications
  • [New!] Google FCM-based Push Notifications.
    • brainCloud now supports FCM, Google’s next-generation push service. New Android push features, like push priority, are only supported via the new FCM service. The good news is that except for the new features, the two services are fully compatible. All new applications will use FCM by default. To enable FCM for a pre-existing app, be sure to uncheck the [x] Use legacy GCM for Google Push Notifications option under Design | Core App Info | Advanced Settings.
  • [New!] Raw Notifications
    • brainCloud now supports what we are calling raw notifications – where you can specify the exact notification payload to be sent to the various notification providers that we support.
    • The following methods have been added to S2S Push Service – SendRawBatch(), SendRawToGroup(), SendRawToSegment(), and ScheduleRawNotifications()
    • The following methods have been added to the Client API – SendRawPushNotification(), SendRawPushNotificationBatch(), and SendRawPushNotificationToGroup().
  • [New!] Schedule Push Notifications from Client API
    • Previously you had to write a custom cloud code script (or use our S2S API directly) to schedule push notifications
    • The following new methods are available from the Client API – ScheduleNormalizedPushNotificationUTC, ScheduleRawPushNotificationUTC, ScheduleRichPushNotificationUTC, ScheduleNormalizedPushNotificationMinutes, ScheduleRawPushNotificationMinutes, ScheduleRichPushNotificationMinutes

Updated API Calls

• Currency
  • We have returned the client-side currency management calls – AwardCurrency(), ConsumeCurrency(), ResetCurrency() – to the client libraries!
  • Background – as you may or may not recall, we had recently introduced the ability to restrict the Currency Management APIs, so that they can only be called server-side (via cloud code)
  • We recommend that all new apps adapt this approach going forward. Whether client-based currency management calls are allowed is controlled via a compatibility flag
  • As part of this work, we had also mistakenly marked the APIs as deprecated. Which of course caused them to be removed 90 days later – as part of 3.4!
  • That was an error. This strategy is completely voluntary – so as of 3.5 the API methods are back. [Our recommendations remain the same though!]
• Global Entity
  • ReadEntity() – we have made minor changes to the JSON data returned. We are no longer returning the redundant appId field in the response.
    Note that you can undo this change using the [x] Include redundant legacy app Ids in some API results compatibility flag. This flag is by default enabled for existing apps.
• Playback Stream
  • [New!] GetRecentStreamsForInitiatingPlayer(), GetRecentStreamsForTargetPlayer()  – get a recent stream for initiating or targeted player of a multiplayer action, and can set a max limit of the stream to query. These calls allow you to specify the maximum number of streams to return, and ensure that the caller is one of the participants of the stream.
  • Auto Deletion – As of Release 3.5, apps will no longer be required to delete old playback streams. The system will automatically delete playback streams that are older than 30 days. Note that we will be phasing in this new deletion service –  the system will start auto-deleting streams older than 180 days, and we will gradually bring the expiry age down over the next few months.  If you think this will adversely affect your app, please reach out to us ASAP!
• Miscellaneous
  • Facebook profile pic URLs – brainCloud will now default to returning the base Facebook profile pic URL (i.e. looks something like “https://graph.facebook.com/{facebookId}/picture”, instead of the redirected CDN-version of the URL that we had been returning. Why? Because it turns out those CDN URLs can eventually expire – d’oh!  Note – using the new URL requires your client to be able to handle http redirection – if you can’t, check the [x] Funnel Custom and User File retrieval through app servers (slower) compatibility flag on the Design | Core App Info | Compatibility Settings page

Terminology Alignment

We have cleaned up game specific terms around our general API calls.

• Purpose: We are reserving gaming terms (like game and player, for the game-specific APIs – and using more general terms – user, app and profile – for the more neutral APIs). This helps brainCloud to be understandable to multiple audiences, which still highlighting gaming features.
• Approach: Calls using old terms have been marked as deprecated in the updated client libraries. Each call has a simple equivalent – switching is easy. The older libraries still work – so all your apps remain compatible. Please switch to the new calls at your earliest convenience.
• Unreal blueprints and response reason codes with old terms have been duplicated
• Finally, the textual portion of some error messages have been adjusted accordingly. All reason code values are the same – – though where appropriate, we have provided duplicate, more appropriately named constants to identify them.

Here is a listing of the methods that have changed:

• Friend Service
  • FindPlayerByUniversalId() -> FindUserByUniversalId()
• [User] Entity Service
  • GetSharedEntityForPlayerId() – > GetSharedEntityForProfileId()
  • GetSharedEntitiesForPlayerId() -> GetSharedEntitiesForProfileId()
  • GetSharedEntitiesListForPlayerId() -> GetSharedEntitiesListForProfileId()
• Player State
  • DeletePlayer() -> DeleteUser()
  • ReadPlayerState() -> ReadUserState()
  • ResetPlayer() -> ResetUser()
  • UpdatePlayerName() -> UpdateUserName()
  • UpdatePlayerPictureUrl() – > UpdateUserPictureUrl()
• Player [User] Statistics
  • IncrementPlayerStats() -> IncrementUserStats()
  • ReadAllPlayerStats() -> ReadAllUserStats()
  • ReadPlayerStatsSubset() -> ReadUserStatsSubset()
  • ReadPlayerStatsForCategory() -> ReadUserStatsForCategory()
  • ResetAllPlayerStats() -> ResetAllUserStats()
• Player Statistics Event
  • TriggerPlayerStatisticsEvent() -> TriggerUserStatsEvent()
  • TriggerPlayerStatisticsEvents() -> TriggerUserStatsEvents() 

Miscellaneous Changes / Fixes

• Updated libraries
  • All libraries have been updated with the latest API enhancements. Go get ’em!
• Documentation updates
  • Updated documentation of mail service
  • Improved API doc examples
• Plus miscellaneous fixes and performance enhancements…