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();
_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 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 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…

This is a small release that focuses on some common customer requests. There is hopefully something for everyone!

Release Highlights

[Enhanced] Global Entity Editor

We have finally upgraded our Global Entity Editor to allow you to directly create entities (i.e. without reverting to code or the API Explorer).

It works as you would expect – just click on the [+] button on the Global Monitoring | Global Entities page, and fill out the form to create your object.

For quick object created – try clicking the [ { Retrieve Example } ] button. This will prefill the custom data section of the object with JSON retrieved from a similarly typed entity.

Tournament fixes and enhancements

First of all, we have fixed some issues that could occur when importing or applying rotation changes to tournaments that are already in progress. As part of this, we have made some adjustments to the

As part of this, we have made some adjustments to the Phases page of the Leaderboard Config dialog – making it a lot clearer as to whether your changes will affect the currently active tournament cycle, or will only take effect for the next tournament cycle.

Finally, now that that is all straightened away – we have re-enabled support for Monthly and Yearly tournament cycles.

Cloud Code Security Fix

In 3.2 we refactored script permissions to allow more precision in controlling whether a script is callable via the Client API, the Server-to-Server API, or from a Peer Service.

It turns out that a defect was introduced during that change that in some cases would allow a script to be called from the Client API, even if it didn’t have the appropriate permission.

This defect has been addressed.

Portal Changes

We have made the following improvements to the Portal:

Design

• Integrations | Manage Integrations
  • Removed Parse Integration since Parse no longer exists. You can still import Parse data exports via the Global Monitoring | Global Entities screen though.
• Leaderboard | Leaderboard Configs
  • Monthly and Yearly rotation types available for tournaments again
  • The Phases tab now defaults to show how the phase changes affect the next tournament cycle
  • To change the currently active tournament, choose “Active Cycle” from the combo-box, and then click the red [Apply to Live Tournament! (Danger)!] button.

Monitoring

• Global Monitoring | Global Entities
  • Revised the Global Entities list screen to be more useful
    • Create entities by clicking on the [+] button
    • Quickly duplicate entities by choosing Clone from the new Action menu
    • Click on an entity owner to jump to that user in User Monitoring
  • Enhanced Global Entity Editor dialog
    • Quickly choose an entity type from a list of used types
    • Retrieve example JSON by clicking on the [ { Retrieve Example } ] button 

API Changes / Fixes

The following changes/additions have affected the brainCloud API:

• Async Match
  • [Fixed] FindMatches() and ReadMatch() APIs now return the user’s latest profile pic URLs instead of the pic that was captured at the time the match was created.
• Authentication
  • [Fixed] ResetEmailPassword() in the JavaScript and AS3 libraries no longer require an authenticated session to work. D’uh!
• General
  • APIs that can return rewards-related results (i.e. Authentication, GetPlayerState, IncrementXP, etc.) are no longer returning a redundant XP reward section.
    Note – a new compatibility flag has been introduced to preserve the old functionality. The flag, [x] Send obsolete reward field content in XP level up rewards results, defaults to enabled for existing apps. 

Miscellaneous Changes / Fixes

• Important Fixes
  • See the Cloud Code Security Fix description in Release Highlights
  • Now deleting cancelled cloud code jobs properly (and automatically!)
  • Improved reliability for the [Login as User] button on the User Monitoring | User Summary page
• Updated libraries
  • The AS3 and Flash libraries have been updated to incorporate the ResetEmailPassword() fix.
  • Otherwise, the client libraries have not been affected by this release.
• Plus miscellaneous fixes and performance enhancements

A small but mighty release 🙂

Release Highlights

Leaderboard Rewards

In 3.2 we added Global Tournaments – which build upon brainCloud leaderboards to add support for opt-in tournament play. Our tournament feature is extremely flexible – with support for paid tournaments, variable tournament durations, configurable tournament phases, push notifications, and more.

But what if you would like to simply add the reward capabilities from Tournaments to your game’s existing leaderboards – without all the code + presentation changes that go along with it?

We have good news. We are happy to present two new tournament features that work together to fulfill this mandate:

• Auto Join – allows players to join a tournament simply by posting a score to the associated leaderboard. Note that Auto Join only works for free tournaments, of course.
• Auto Claim – automatically awards the player their prizes when a tournament completes.

Deployment Improvements

We have made several improvements to our Push Button Deployment process – which allows you to easily push the configuration of your app (including scripts and global files) from your development app to your production app.

Improvements to this process include:

• Better support for large volumes of custom files
• More reliable versioning of the custom files
• New option to Exclude Integration Settings during a deployment

As always, the Deployment tool is available in the portal under Design | Core App Info | Admin Tools.

Notice Banners

We have updated our portal to allow us to display banners with information about upcoming events (release updates, scheduled maintenance, etc.). We will of course use these banners in conjunction with our email notices and the brainCloud Service Status page.

Portal Changes

The following screens have been changed:

Design section

• Core App Info | Application Ids
  • The [x] Show Game Design Features toggle is back! (It was lost, but now it is found.)
• Core App Info | Advanced Settings
  • There are 3 new compatibility options – these first two default to “on” for existing apps, “off” for new apps
    • Do not reprocess currencies for non-consumable IAP products in receipts
    • Send obsolete reward field content in XP level up rewards results
  • But this flag only relates to Auto Claim, and thus is off for all apps by default
    • Enable Tournament Auto Claim check at login
• Cloud Code | API Explorer
  • We’ve added the ability to easily discover and invoke scripts from Peer and Parent services
  • Now you’ll see an individual Service entry for each Peer or Parent service associated with your app
• Custom Config | Files
  • Added a new column to display the version of the file. We’ve also improved our handling of new file versions, to make updating files (with automatic propagation to the CDN) more reliable
• Leaderboards | Leaderboard Configs
  • Added the new Auto Claim and Auto Join feature settings to the Tournament tab page

API Changes

The following changes/additions have affected the brainCloud API:

• GlobalEntity
  • Added a new Cloud-code only UpdateSystemEntity() method to allow updating of the contents of a system entity, regardless of its ACL permissions. This is especially useful for system entities that .  [Reminder – SystemEntities are simply GlobalEntities that do not have an owner. The advantage being that they are not automatically deleted if the owner’s profile is deleted.]
  • Also added an UpdateSystemEntityACL() method that likewise, allows the developer to over-ride the ACL of a SystemEntity. This code is also Cloud-code only for security reasons.

Miscellaneous Changes / Fixes

• Updated libraries
  • There are no new client APIs in this release – and thus, no new libs to download!
• Documentation updates
  • We have added error handling examples to the C# sections of the Authentication documentation
• Important Fixes and optimizations
  • We have improved the performance of the UpdateAttributes() operation of the PlayerState service
  • We have fixed a race condition that under certain circumstances could award double currencies for Facebook purchases
  • We have fixed the json outputted during reward handling for XP level-ups – the returned json no longer includes the redundant “reward” section. Note – the [x] Send obsolete reward field content in XP level up rewards results compatibility flag preserves the old behaviour in case your app requires it.
• Plus miscellaneous fixes and performance enhancements…

What’s smaller than a Release, but bigger than a Patch?

Release 3.2.5 includes some key new optimizations, fixes and even a few minor features.

Note – This is a minor update to brainCloud 3.2 – be sure to check its release notes for the full update on all the great 3.2 features.

Optimizations

Faster User Entities

We have significantly optimized the UpdateSingleton() API call by eliminating a superfluous read operation from most usage scenarios. To achieve this, we had to remove some unnecessary fields from the API’s JSON return.

As per our custom we by default preserve compatibility. To fully gain the advantages of this optimization, confirm that your app isn’t making use of the entityId, acl, createdAt and updatedAt fields that were previously returned – and then go to the Design | Core App Info | Advanced Settings page, Compatibility Settings section – and uncheck the [ ] Include entityId+ in UpdateSingleton Api output option. 

Fast Log Processing

The continued growth of our platform causes us to continually re-look at our architecture and framework to ensure that we get the best performance. In this last growth spurt, the logging system came under scrutiny as the source of some slowdowns. We’ve made some incremental changes to improve this – improved batching of writes, and capping the amount of request data logged for some API calls. We have plans to do more in the future.

Faster Segment-based Push Notifications

Our User Segments feature is very useful for targeting push notifications – and some of you are taking great advantage of that, sending notifications to millions of customers daily. That said, not every user enables push notifications – and our segments weren’t recognizing that before.

To address this, we’ve added a new Push Enabled Segment Criteria.  If you configure this criteria for a segment, it will ensure that all members actually have push notification tokens registered. That way brainCloud isn’t wasting time chugging through a million records, when only 300,000 of your users have enabled push.

Note – to take advantage of this performance optimization, go to Design | Segmentation | Segments page, select a segment, and add the Push Enabled critera to it.

Minor Features

Unsubscribe from Tournaments

Your users can now unsubscribe from tournament mailings. Required legally for many locales. Just include include the code -unSubUrl- in your SendGrid email template, and it will be replaced with a custom unsubscribe URL for that user.

Client Kill Switch

This is more of a feature for us than you :).

Recently we’ve had a uptick in apps that endlessly retry an operation if an error occurs. This is considered bad client behaviour. The brainCloud libraries themselves automatically retry on a timeout and/or communications failure (they will retry 3 times before returning an error to you). If, however, we receive a 4xx or 5xx error from the server, we return it to the app – because that means that the server is unable to perform the request as formed (possibly bad parameters, bad server data, etc.)

In these cases, if you retry the operation as before, there is a 99.999% chance you will get the same error! Implementing an endless retry in your code is akin to DDOS-ing our servers! And it costs you API calls to boot!

So – we’ve implemented a way to stop you! Now, if your client app sends in the same erroneous requests ten times in a row, the client will stop actually sending the requests, and return an immediate error to your client app. This *might* cause an endless loop in your app – so once again – don’t do this! [Note – most mobile OSes will kill the app as soon as the loop is discovered]

Slow Errors

Still on the topic of endless error loops (see above), brainCloud will now intentionally delay sending error responses back to the client. It’s not a huge delay (1/2 a second) – but that can make a significant difference in the rate that a client can automatically retry – and thus the impact on our servers. This delay is applied per bundle, only if all the messages in a bundle have errors.

Note – this delay is tuneable per app. If it is negatively impacting your app, reach out to us and we can adjust it. 

Miscellaneous Fixes

We’ve also include the following fixes:

• Merging with Peer Profiles – we’ve fixed some issues associated with merging of profiles that are associated with Peer Profiles
• Reading Leaderboard Configs – the read routines are now much-more robust
• Incoming Events – we’ve removed the unnecessary gameId field from all incoming event calls. Note – for compatibility reasons, the change only takes effect if the [ ] Generate Legacy Event Ids compatibility flag is unset.
• Tournament Phases – the display and configuration of Tournament Phases on the Leaderboard Config dialog and Leaderboard Monitoring pages has been improved.
• Facebook Purchases – we fixed an issue associated with the latest changes to Facebook’s Purchase APIs.
• Push Notification Tokens – are now properly removed when players are deleted.
• Cloud Code Jobs – scheduled jobs are now editable again via the Monitoring | Global Monitoring | Job Queue page.

Introduction

brainCloud’s new Global Tournaments feature is an entirely new system designed to amplify player engagement in your games.

Global Tournaments are suitable for any game where competition centres around leaderboards. In fact, in their simplest version, Global Tournaments can be thought of simply as prize rules associated with a leaderboard.

But as you will see, there is a whole lot more to them.

Goals

When designing Global Tournaments, we had a specific set of goals in mind.

brainCloud’s Global Tournaments should:

• Be easy to add to apps
• Be flexible in terms of tournament schedule, phases, rules, payouts, etc.
• Integrate with brainCloud’s existing reward systems
• Automate key aspects of player engagement
• Be manageable so that entry fees, prize amounts, etc. can change over time as you iterate
• Act as building blocks for building more complex tournament types (i.e. tiered tournaments, etc.)
• Work within the existing brainCloud pricing tiers

Features

Global Tournaments support the following key features:

• Duration – support for daily, weekly, and arbitrary length tournaments (up to 14 days)
• Phases – support for optional announcement, enrollment, competition, buffer and award phases
• Flexible Prizes – Award participants any combination of virtual currency, xp, player stats, achievements and custom data
• Entry fees – Free vs. Paid Tournaments
• Push Notifications – automatically send configurable push notifications at key points during the tournament
• Email Integration – send custom email notifications as well

Design

Concepts

This diagram describes the main entities involved in creating a Tournament:

• Leaderboards are defined in the brainCloud system by entities we call Leaderboard Configs
• To create a tournament, you attach a Tournament Template to a Leaderboard Config
• The Tournament Template defines the rules of a tournament – entry fees, prize rules, notification templates, etc.
• The Leaderboard Config defines how scoring works (highest score, cumulative score, etc), the rotation schedule, and also the pacing of the tournament phases.
• Each rotation of the leaderboard is a Leaderboard Version. All scores are stored by version in Leaderboard Entry objects.

Special rules:

• The same tournament template may be used by multiple leaderboards. This of course creates a separate tournament per leaderboard.
• A leaderboard may also attach multiple tournament templates. This is useful for cases where you want to have both free and paid versions of a tournament, that act upon the same set of scores. (rationale: better liquidity, smaller payouts)

Tournament interactions / api

The following are the key tournament interactions to understand:

• Get Tournament Status – returns the status of the specified tournament, and whether the player is currently enrolled in it. If the player is not enrolled, returns details of all the tournament configs associated with the leaderboard
• Join Tournament – all tournaments must be joined before you can submit scores to them. Joining a tournament involves specifying the leaderboard that anchors the tournament, and the tCode of the tournament [template] that you are joining. An entry fee will automatically be deducted from the player’s currency balance if required.
• Post Tournament Score – posts an score to the tournament leaderboard. Note that you must pass in the epoch time that the game round started in, to ensure that the score is eligible. Note that there are several versions of this operation (see the API for details).
• View Current Reward – returns the player’s standing in the currently active tournament, and the reward they can expect to receive if they keep this rank.
• View Reward – returns the players reward for a completed tournament, and whether it has already been claimed. Will return an error if the player is not enrolled in the tournament.
• Check For Events – query the brainCloud events queue to see if any Tournament Completion events have arrived
• Claim Tournament Reward – claims the rewards for a completed tournament, incrementing appropriate player balances (currencies, etc.).

For more information on these interactions, see the Tournament API.

Phases and States

Tournament States are used to organize the larger tournament lifecycle. They determine when tournaments are active, processing award calculations, and available for award clams.

Tournament Phases help to micro-manage when players can join tournaments, post scores, etc. throughout the Active tournament state.

The following diagram summarizes the relationship between brainCloud tournament states and phases:

Note that brainCloud doesn’t explicitly tell you the phase it is in – instead, it gives you information as to when registration starts and ends, when play starts and ends, etc.

Events and Notifications

A key goal of brainCloud’s Global Tournaments system is to automate the tournaments interactions with players. As such, the system:

• Automatically rotates and cycles through tournament states and phases as per the schedule defined
• Send events to players when the tournament has completed
• Optionally sends push notifications and/or emails
  • When a new tournament opens for registration (enrollment) – sent to previous tournament participants
  • When a new tournament opens for play (competition) – sent to previous and currently registered participants
  • When a tournament’s competition phase is close to ending – sent to current participants
  • When another player beats their tournament score, bumping them down a rank – sent to current participants within 10 ranks of the player who posted the score
  • When a tournament completes and they’re awards are ready to be claimed – sent to current participants. The system also sends an Event to the player’s event queue.

Note that you shouldn’t blindly configure all notifications – especially the email-based notifications. Some recommendations:

• Do not configure both Tournament Registration start and Tournament Play start if your tournament doesn’t have an exclusive registration period, or your players will get two back-to-back notifications, and be annoyed.
• Be careful about configuring Email-based notifications – we’ve included the trigger points, but for most cases we would recommend that you mostly use them to announce that a tournament is complete and that the player should come collect their prize. It’s also a handy opportunity to include info on other game offers, bonuses items to increase scores, etc.
• Be aware that brainCloud does not yet support automated unsubscribes (coming soon)

Special: Scoring notifications

There are two types of designers. Designers who think that scoring notifications are cool, and those that think they could get annoying very quickly. And they are both right.

To add the engagement of scoring notifications, hopefully without overwhelming the player, we’ve added the following rules:

• We’ll only send a player one scoring notification per 24-hour period

The are two additional rules that affect this:

• If you post a new score, we reset the notification clock. This means that engaged players will receive more than one notification in a 24 hour period, because they’re actually responding to them.
• We won’t send the player a score update until at least 30 minutes after their last posted score (i.e. you don’t want to receive a push notification immediately after exiting the game)

Bonus Features: Auto Join and Auto Reward

Global Tournaments offer an incredible way to increase engagement and monetization with your players – but what if you are just looking for a quick way to automatically add rewards to your weekly leaderboards – without code changes?

Look no further – brainCloud has two new features that allow you to automate the key portions of the tournament processing:

• Auto Join – Enables players to automatically join the tournament associated with a leaderboard, simply by posting a score to it (via the standard leaderboard PostScore method). Note that this only works for leaderboards that have one-and-only-one tournament associated with them – and that tournament must be free.
• Auto Claim – Causes tournament rewards to be automatically claimed by players during login. Note that the [x] Enable Tournament Auto Claim check at login compatibility flag must also be enabled on the Design | Core App Info | Advanced page of the portal

Note – although we provide the Auto Join and Auto Claim features for convenience, in most cases we would definitely recommend that you implement the full tournament API. A key benefit to tournaments is engaging with your players – getting them excited about what they can win and adding that extra flourish as they claim their prizes. Auto Join and Auto Claim hide all that – minimizing the opportunity for extra player engagement.

Features Availability and Billing Notes

Global Tournaments are available across all brainCloud subscription plans.

The basic API billing rules are in effect – 1 API count per API call, 1 API count per Push Notification, 1 API count per Email Sent

In addition, the following counts are added to offset the overheads of automated tournaments:

• Awards Calculation – At the end of the tournament, 1 Bulk API Count per participant is charged to cover the CPU load of processing results and sending events to the players
• PostTournamentScoreWithResults() – adds 1 Bulk API count to cover the overhead of comparing the players previous and current tournament results, and determining whether to send notifications to displaced players. As compensation, however, returns the updated tournament results (essentially GetGlobalLeaderboardView()), hopefully saving the app an API call in return.
• Auto Claim – if the Auto-Claim feature is enabled, 0.5 Bulk API Counts are added to each Authentication()