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()

We’re pleased to present brainCloud 3.2 – arguably our biggest releases ever!

Note – as always, we have worked very hard to ensure that this update does not break your apps. Scroll to the bottom of this page for a summary of the bigger changes, any recommended actions, and how to confirm the stability of your apps.

Feature Highlights

Global Tournaments

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 centers around leaderboards. In fact, in their simplest form, Global Tournaments can be thought of simply as prize rules added to a leaderboard.

The power of brainCloud’s tournament system comes from how flexible they are, coupled with how much they do for you. Features include:

• Free or Paid – brainCloud collects the entry free for you
• Flexible Prizes – award any combination of currencies, xp, stats and achievements – brainCloud handles it all
• Tournament Cycles – set your tournament to daily, weekly, monthly or an arbitrary number of days
• Tournament Phases – optionally have an exclusive registration vs. play phase – and set up downtime between tournaments
• Notifications – both Push and Email-based notifications – automatically sent by brainCloud throughout the tournament cycle
• Portal Support – configure tournament templates and attach them to leaderboards. And then view tournament results straight from the Leaderboard monitoring screens
• New Tournaments API – for fine control of displaying tournament information, handling player enrollment, recording player scores, and claiming awarded prizes

And of course you can use brainCloud Global Tournament features as building blocks for more advanced tournament variations – for example tournaments brackets.

Warning – adding a Tournament Template to an existing Leaderboard changes the API required to interact with it (for example, you can no longer post a score to a leaderboard before joining it). For this reason, we do NOT recommend adding tournaments to existing leaderboards in live games. 

For more information, check out our new Tournament API.

Peer Services [Beta]

Another big feature of this release is brainCloud’s new Peer Services system. This framework allows the services of one app (the Peer Service) to be used by other apps (Peer Clients). Peer Services can even be public, so that its services can be leveraged by other teams!

This provides a whole new level of code/service re-use in brainCloud, including allowing new service integrations to be added to brainCloud directly by third party developers. This has the potential to really open up the brainCloud ecosystem, to the benefit of the entire brainCloud community.

Initially we see this being used in two primary scenarios:

• Sponsored Integrations – this mechanism allows brainCloud partners to easily build integrations on our platform, and offer them for your use.
• Private Services – development teams that are building lots of apps can more easily group common functionality into a separate app who’s services are leveraged across the others.

Very soon we hope to add support for Community Services as well – where developers in the brainCloud community can offer up peer service components to be used freely by others. We need to do a bit more work on our API tracking for that to work effectively, since in that scenario we would want the API counts for the services usage of brainCloud to be accounted for by the peer clients, not by developer who created the free peer app.

Note – we’ll be introducing our first sponsored Peer Service very soon – stay tuned!

Cloud Code Enhancements

Finally, we’ve made some significant enhancements to our cloud code system to make writing scripts easier. Changes include:

• No more Script Types – We have eliminated the confusing concept of “script types”. Now, a script is a script is a script
• [New] Script Permissions – scripts are now individually configured to be callable from the Client API, the Server-to-Server (S2S) Interface, and/or Peer Clients. All scripts are callable from other scripts.
• Three bridges, one consistant interface – depending upon how your script is called, you will get one of three bridges. Client Bridge (for calls from the client api and/or API hooks), Server Bridge (for scheduled scripts and those from S2S api) and Peer Bridge (special case for calls to peer scripts from peer clients). The APIs for these bridges has been normalized, so you no longer have to call special S2S versions of the proxy methods from the Server bridge. (i.e. getScriptServiceProxy() now works from all of them – though getS2SScriptServiceProxy() still works from the Server Bridge for compatibility).
• Normalized Proxies – If you use methods in the proxy that are not implemented in the particular mode (Client/Server), the script will throw a not-implemented exception.
• Global Properties access – new getGlobalProperty() method allows you to easily use global properties in scripts. No more magic values copied across scripts – simply define the value in Design | Custom Config | Global Properties for use.
• New Documentation menu – the Cloud Code Editor now contains its own version of the Docs menu for easy reference.
• Save Deleted Scripts – we now continue to save a scripts version history even if you delete the script. So if you accidentally delete a script, just create a new one with the same name – and then restore the old version of the script from history!

Compatibility – All of these changes are backwards-compatible, so your scripts should keep working as per usual. An exception might be if your script was using exception-handling to test for previously unsupported bridge methods – since unsupported methods are now present, your script(s) may require some quick adjustments.

Portal Changes

In addition to the changes you would expect to support Tournaments and Peer s expected changes to support Tournaments and Peer Services

Design Section

• Core App Info | Advanced Settings
  • New compatibility feature settings
    • “Allow Currency Calls from Client” – allows your apps to still directly manage currencies from the client (less secure). Enabled by default for existing apps.
    • “Generate Legacy Event Ids” – we’ve changed how event ids work this release. If your app already uses our event system, and you aren’t yet updating to the new API, you’ll want to keep this enabled.
  • For more information on compatibility-related changes, see the API section
• Core App Info | Peer Publish [NEW!]
  • Used to publish your app as a Peer Service.
• Cloud Code | Scripts
  • New permissions!
    • We’ve refactored script permissions – and added a new one. Now all scripts can be set to be callable via any combination of Client API, S2S API, Peer API (callable from a peer client), or none at all (in which case the script is only callable from another script).
    • These permissions are settable in the Script Editor, and viewable in the Scripts list
    • Compatibility: To ensure that we don’t break existing apps, all scripts by default have the S2S permission set to “enabled”. You should review and disable this permission for any scripts that don’t need it.
  • Editor Docsmenu
    • A new Docs menu provides quick access to the cloud code API Reference, Tutorials, Knowledge Base and even a Javascript Syntax Search Engine (it’s new – and we’re going to help to update it)
• Cloud Code | API Hooks
  • Now allows you to specify hooks to be run when an API call fails (the default hook only triggers upon success).
• Cloud Code | S2S Explorer
  • Now only lists scripts that have the S2S permission set to true
• Integrations | Peer Services [NEW!]
  • Used to connect your app to a Peer Service.
• Leaderboards | Leaderboard Configs
  • Enhanced to support Tournaments. You create a tournament by attaching a tournament template to a Leaderboard.
  • We also added a new Days rotation – that lets you rotate your leaderboard every <x> days
• Leaderboards | Tournament Templates [NEW!]
  • New screen for creating tournament templates
• Marketplace | Products
  • Enhanced to allow you to define products that include Peer Currencies.
• Marketplace | Virtual Currencies
  • Added support for Peer Currencies

Monitoring Section

• Global Monitoring | Leaderboards
  • The Leaderboards monitoring screens have been enhanced to support tournaments. These features are only shown for leaderboards that have one or more Tournament Templates attached to them:
    • Tournament Schedule – click on the Trophy near the top of the screen
    • Tournament Column – shows which tournament a player is enrolled in. Clicking shows additional information about what prize that player may / has won, and if it has been claimed.
• Global Monitoring | Job Queue
  • Enhanced to support Tournament Jobs for processing tournament results and sending tournament notifications
• Global Monitoring | Global Monitoring | Recent Logs
  • We’ve modified the UI behaviour of this screen somewhat. Instead of the screen automatically refreshing as you change filter settings (which caused problems when the log was long and lagging) – you now can change multiple settings, and refresh the list at once via the [Refresh] button
  • The response logs are now being truncated if they are too large. The new maximum log response that will be stored for viewing is 10Kb.
• User Monitoring | User Summary
  • Peer relationships show up in the relationships section
• User Monitoring | Virtual Currency
  • This screen now shows parent currencies and peer currencies when applicable.
• User Monitoring | Logs
  • The response logs are now being truncated if they are too large. The new maximum log response that will be stored for viewing is 10Kb.

 Reporting Section

• API Usage
  • Added a new Bulk Operations count. brainCloud will utilize this category for API calls where a single count doesn’t effectively account for the load on our servers. For example, for Tournament Processing, we charge one bulk API count per player in the tournament (charged during award processing).

Team Section

• Home
  • We’ve added a link to our new Knowledge Base to the docs section of the page. 

Programming/API Changes

The following changes/additions have affected the brainCloud API:

• Client (behaviour change)
  • As you may or may not know, the brainCloud client libraries automatically package multiple server requests [sent within a short period of time] into bundles to be processed at the server. This both reduces network traffic and minimizes server utilization. Up until brainCloud 3.2, the client libraries were statically configured to allow up to 50 messages in a bundle [a crazy high number in hind-sight!]
  • In general this approach works very well – and to be fair – the average bundle size is probably 2-3 messages for the average app.
  • However – we’ve had a few instances where client applications get into endless loops – where the same message is being stuffed into the bundles over-and-over. In those cases, sending 50 messages at a time – especially if those messages are something heavy like leaderboard requests – can generate an unsettling amount of server load!!! 🙂
  • As of 3.2 and moving forward, this limit is now controlled by the server, and enforced by the 3.2 client libraries. We will initially be setting the limit to 10, but we may notch it down a bit more if
  • Compatibility – this change has no impact on your app until you move the to 3.2 client libraries, which we *do* highly recommend.
• Cloud Code
  • We have done some reworking of our cloud code system to make it easier to write scripts that can be called any way that you would like – from the client, from another server (s2s), from a peer app, or from another script
  • Removed the concept of Script Types – there are no longer client and server script types. A script is a script is a script. And any script can be called from any other script. (Note – scripts do still work within different environments – see the bridges section)
  • Replaced with Permissions– all scripts now have a collection of distinct, independent permissions
    • Client – scripts with client permission can be called from client libraries
    • S2S – scripts with the s2s permission can be called from the Server-to-Server (S2S) API
    • Peer – scripts withe peer permission can be called from peer client apps
  • Compatibility – to ensure compatibility with existing apps, all apps that were configured as “client scripts” before are now set with Client permission enabled. In addition, the S2S script defaults to true for all existing scripts. For maximum security, you should review your scripts and disable the S2S permission for any scripts that don’t require it.
• Cloud Code Bridge(s)
  • About Bridges – when you run a script, at runtime it gets associated with one of three (3) bridges. Scripts called from the client API get a Client Bridge – which is associated with a user session (and has access to their profile, etc). Scripts called from S2S, or from scheduled jobs and webhooks, get the Server Bridge (which doesn’t have an associated user session). And scripts run in a peer app get the new Peer Bridge, which can access both a client session and potentially a peer session (if the peer app has profiles).
  • Bridge Refactoring – we have refactored our bridges a bit to make the interfaces between them the same. So now, if you try to access a method like getProfileId() that only makes sense in the client context, instead of getting a method-not-found error you’ll receive null instead.
  • New Convenience Methods– we’ve added some new methods to make writing scripts simpler. Some of the more useful methods include (methods with * indicate client context only):
    • callScript() – a simpler method for calling another script from within a script
    • getAppId() – a method to get the appId of your app (useful in certain situations)
    • getClientAppId() – useful in peer scripts to get the app id of the calling app
    • getGlobalProperty() – used to retrieve one of the global properties that you’ve defined in Design | Custom Config | Global Properties. No more hard-coding magic values in scripts!
    • getEmail()* – get the email of the user
    • getName()* – get the name of the user
    • getProfileId()* – get the profileId of the user
    • isClientBridge() – returns true if the bridge is a client bridge
    • isPeerBridge() – returns true if the bridge is a peer bridge
    • isServerBridge() – returns true if the bridge is a server bridge
• Event
  • Working on our the new Tournaments feature gave us an excuse to make some much-needed improvements to our Event System
  • We have made things faster and more reliable – but in doing so we have changed how we handle event ids
  • The new APIs use in evId instead of the old eventId. This id is mostly used when deleting events. All other data about an event remains the same.
  • There are new versions of DeleteIncomingEvent() and UpdateIncomingEventData().
  • The old eventId will still be generated (for compatibility purposes) if the “[x] Generate Legacy Event Ids” flag is set on the Design | Core App Info | Advanced Settings page. That option is enabled by default. The old methods are deprecated, but are still available on the client, and work as long as the compatibility option is enabled.
• Friend
  • GetProfileInfoForExternalAuthId() – Allows you to look up users via a custom authentication type
  • GetProfileInfoForCredential() – A new version of the now-deprecated GetFriendProfileInfoForExternalId() – a bit better named, and returns an error if the profile cannot be located.
  • FindPlayerByUniversalId() – now returns the users universal id (in field externalId) with the results
• Global Entity
  • Background: Global Entities, by default, each have an owner – the user that created them. If the owner of an global entity is deleted, the entity will be deleted as well. This is not desirable in all cases – so we’ve created some methods to adjust the ownership of global entities.
    • MakeSystemEntity() – changes a global entity to “unowned” – and thus it won’t be deleted when a user is deleted.
    • UpdateEntityOwnerAndACL() – changes the owner of a global entity to another user.
• Identity
  • Background – we’ve added some methods to work with Peer Services.
    • AttachPeerProfile() – attach a peer profile to this account (optionally creating it if it doesn’t already exist)
    • DetachPeer() – detach the specified peer profile
    • GetPeerProfiles() – returns the peer profile associated with the specified peer code
• Leaderboard
  • We’ve extended GetGlobalLeaderboardView() and GetGlobalLeaderboardPage() to return the player’s profilePic if available. After all, why should social leaderboards have all the fun?
  • CreateLeaderboard() – has been extended to support the new <days> rotation
  • [New!] GetPlayerScore() – returns the players score from the leaderboard. Note does not return the players rank.
  • [New!] GetPlayerScoresFromLeaderboards() – returns the score for the current player from a set of leaderboards
  • [New!] RemovePlayerScore() method – replaces ResetScore(), which we are deprecating
  • 3.2 Client libraries are now updated to use leaderboard service id instead of socialLeaderboard. If for some reason your callbacks are triggering off of the socialLeaderboard service id, you’ll need to make adjustments.
  • New restriction: We are now limiting the maximum number of leaderboard entries that can be requested in a single page using GetGlobalLeaderboardPage(). If your request exceeds the limit we just adjust it within the limits (beginning from the lower index). The new immediate limit will be 100 entries, but we plan to further reduce that to 50 entries beginning February 15th. This constant is tweakable per app so contact us if you need us to temporarily adjust that for you.
  • API Change – Leaderboard Size: We are removing the <getLeaderboardSize> field from GetGlobalLeaderboardPage(). Unfortunately, it is an expensive operation that many clients set to true, but often were not using (and certainly doesn’t need to be individually retrieved per page). We’ve replaced this operation with separate calls, GetGlobalLeaderboardEntryCount() and GetGlobalLeaderboardEntryCountByVersion(). Compatibility: The old API will continue to work for earlier client libraries. The change is effective starting in client library 3.2 and greater.
• Product
  • Security Improvements – we’ve made some enhancements to the currency management methods of the Product API
  • By default, the AwardCurrency(), ConsumeCurrency() and ResetCurrency() methods are no longer callable from the client. They are, however, callable from cloud code scripts – which is of course a lot more secure.
  • Note that this security enforcement is controlled by a new compatibility option, “[x] Allow Currency Calls from Client” which defaults to “on” for existing apps.
  • Note – we’ve also made the AwardParentCurrency() and ConsumeParentCurrency() methods cloud code only – those weren’t in use yet so we have removed them from the client directly.
  • GetCurrency() now additionally returns parent and peer currencies for convenience
• Script
  • The script service has been enhanced to support Peer Services
    • RunPeerScript() – used to run a peer script
    • RunPeerScriptAsync() – used to run a parent script asynchronously (without waiting for a response)
• S2S Script Proxy
  • We’ve added the ScheduleCloudScript() method to the proxy, so that you no longer need to create a user session to schedule a script
• Tournament Service [NEW!]
  • Although Tournaments leverage our Leaderboard infrastructure, they add a whole new API for most operations (except for viewing leaderboard results).
  • A quick summary of the new methods:
    • GetTournamentStatus() – gets the player’s status in the specified tournament leaderboard. Essentially tells you whether the player is enrolled or not, along with information about the tournament.
    • JoinTournament() – join a tournament on the specified leaderboard
    • LeaveTournament() – leave a tournament
    • PostTournamentScore() – post a score to the tournament. Note that you must have previously joined it.
    • PostTournamentScoreWithResults() – post a score to the tournament, and notify any displaced players if a bump them down a notch in the rankings. Note – this is a more expensive API call that has to perform a few leaderboard sorts to accomplish its features. Because of that, we charge 1 Bulk API call in addition when called. But we return the updated leaderboard results though – saving you one API call in return – so it all evens out! 🙂
    • ViewCurrentReward() – used to retrieve what a player might earn if they maintain this rank in the tournament. Note that this value is approximate, and doesn’t take ties into account. So the player will get that reward or better!
    • ViewReward() – used to retrieve what a player actually one in a completed tournament.
    • ClaimTournamentReward() – claim the player’s winnings! Automatically adjusts the player’s balances, and returns the prize data that the player won.
  • For more information, see the Tournament section of the API Reference.

Miscellaneous Changes / Fixes

• Updated libraries
  • General updates
    • Now dynamically enforce the maximum # of messages per bundle. New limit is 10 messages per bundle.
    • Authenticate message forced to be first
  • C++ library overhauled to better handle the myriad of platforms that we support!
  • Unity Client – now fully compatible with WebGL (no need to enable the development flag!)
  • Action Script – major updates to the ActionScript library to bring them up in line with the other libraries
• Demos
  • brainCloud Bombers improvements – mucho updates, including support for Unity WebGL!
• Documentation updates
  • Updated Unity Tutorial Video
• Important Fixes
  • Global Properties – We are now limiting global properties to 500. This is mostly to ensure that folks don’t use the facility for something that is better represented by Global Entities and/or Config Files.
  • Deleting Scripts – when deleting a script, we no longer delete all archived versions of the script. That means that should you want to restore it, you can simply create a new script with the same name, and then browse it’s history!
  • Leaderboard Imports – fixed a scenario where importing a game config could cause the leaderboard rotation history to be overwritten.
  • API Hooks for Errors – you can now configure an API hook to be called if a specific API call encounters an error. Previously API Post-hooks would only be called upon success
• Plus miscellaneous fixes and performance enhancements…

Compatibility Summary

We at brainCloud work very hard to ensure that our updates are backwards compatible with our existing community of apps.

That said, it is recommended that that you review your apps for any unexpected issues. The following steps are recommended:

1. Read the release notes to get an understanding of what is changed
2. Log into the Portal and check your apps logs for new errors (chose Quick | Recent Logs from the menu)
3. Log into your app to do a quick sanity test

If you see any problems, please let us know right away. Click the chat button and we’ll be online to help you ASAP!

API Calls

• Leaderboard restrictions – the new maximum number of leaderboard entries allowed per request could have an impact on your app. If you are currently requesting > 100 leaderboard entries per call, the response will be truncated to just the first 100 entries.
• Tournament API – note that attaching a Tournament Template to a Leaderboard changes the API required to interact with that leaderboard. Do not attach Tournaments to leaderboards that are currently live in production.
• Events – the Event API has changed, but the compatibility flag is enabled by default – so existing applications should not be affected.
• Product – The client-based currency management functions are deprecated, but still available from the Client Libraries.

Cloud Code Scripts

• All existing scripts by default have the new “S2S callable” permission set to true. For optimal security, you should review your scripts and disable that permission for any scripts that do not require it.
• The refactored bridge interfaces should be completely compatible with your old scripts – except, if maybe you were using the method-not-found exceptions in your scripts to determine how your script is being run – in which case a quick modification will be in order.

New 3.2 Client Library

• Now enforcing server-controlled maximum bundle size – which is initially set to 10 messages (from the previously hard-coded 50)
• Leaderboard size – the API for retrieving Global Leaderboard pages and views has changed, as you can no longer specify that you would like the leaderboard size returned as well. There are separate methods for that now.
• Leaderboard response handling – the client libs have now been all converted to use the LEADERBOARD service name instead of SOCIALLEADERBOARD for all success and error handling. When updating to the new libraries, you may need to adjust your success and/or error handling routines accordingly
• Leaderboard callbacks – all callbacks are now operating off of the leaderboard service id instead of socialLeaderboard

Billing Notes

• Tournaments – tournaments are available in all billing plans, and the basic charges work as you’d expect (an API count per API call, push notification, email, etc.). There are two additions – at the end of the tournament, the system accrues 1 Bulk API count per participant. And there is 1 Bulk API call added for calls to PostTournamentScoreWithResults() to cover the additional processing.
• Events – Apps with “Enabled checking for Incomfing Events with each API Message” will accrue a 1/2 bulk count per api call.  This new pricing will come into effect on February 15th, 2017.
• Sponsored Peer Apps – calls to Sponsored Peer Apps, including all processing that the Peer App performs, and even the invocations of the Peer’s cloud code scripts from the client app, are free to the peer client. (The Sponsored Peer App covers those costs).
• Community Peer Apps – community apps are the opposite. The Peer Client covers all usage costs, including calls made within the peer to service the requests from the Client App.

Rich email support - use it wisely!

Release Highlights

Here is a list of all that is cool in brainCloud 3.1…

SendGrid integration

brainCloud has moved away from our legacy, bare-bones email support (which was Amazon SES-based) to an improved infrastructure that will provide some great new features today and in the future. We have been planning this for some time – largely because we want to deliver a solution that allowed for richer, more customizable communications for our community.

After discussing with several of our key customers, we have chosen SendGrid for our replacement email delivery system due to its rich feature set and reasonable, straight-forward pricing model.

Customers already using our legacy email service will continue to be supported for the foreseeable future – but new apps under development will need to integrate with SendGrid for email delivery. We believe the capabilities of this new approach make the decision easy.

There are many advantages to this new system:

• Configurable from and reply-to addresses (so your emails come from you, not us)
• Full email statistics reporting (via the Sendgrid dashboard)
• Custom templates (see below)
• API-based Transactional Email (see below)

The great news is that SendGrid’s pricing starts at free (up to 12,000 emails per month) – and ramps up very reasonably from there ($9.99 for 40,000 emails, $19.99 for 100,000 emails, etc.). Check out the full SendGrid Pricing details here (be sure to scroll down to find the free option!).

For step-by-step instructions on integrating brainCloud with your SendGrid account, click here!

Note, we plan to add additional email integrations / features in the future – so feel free to contact us with your feedback and suggestions.

Rich Email Templates

With SendGrid support comes support for custom email templates – so you are no longer limited to the pre-formatted brainCloud emails that get sent for verifying a user’s email address, resetting passwords, etc.

SendGrid includes the following template features:

• Drag & Drop Editor – quickly create or modify the template design via SendGrid’s drag-and-drop editor. Add images and buttons – and customize fonts, colors and other formatting
• Import HTML – designers can easily import and modify email template code using an HTML editor.
• Custom content – use substitution tags to customize email content
• Template library – manage all of your teamplates in one place, and manage multiple versions of a template – useful for updating branding, holiday messaging, etc.

Transactional Emails

In addition to using SendGrid for email authentication, brainCloud now supports a new Mail Service API that allow you to send custom transactional emails directly to your users. So it is easy to send emails directly to users based on they’re interactions with your app.

Updated Google Authentication

We’ve updated our Google Authentication support to align with the latest Google libraries. As part of this feature, the Google integration portion of the Design | Core App Info | Application IDs screen has been updated to gather more Google configuration parameters.

Updates to Free Account Limits

As most of you know, brainCloud support up to 100 Daily Active Users while your app is In Development. After that, your apps logins are rejected until the next day (which begins at 0:00 UTC) – when the DAU resets back to zero. There is another limit associated with the “In Development” plan – and that is a maximum of 1000 lifetime user accounts. Up until now that’s been more of a gentleman’s agreement – in that we weren’t actually enforcing it. As of Release 3.1, this limit is being enforced.

So, what if you’ve been in development for a while and have inadvertantly exceeded your 1000 accounts? The simplest fix is to delete some/all of your user/test accounts using the Data Deletion options at the bottom of the Design | Core App Info | Admin Tools page.

Portal Changes

We’ve made the following portal changes:

• Design | Core App Info | Application IDs
  • We’ve added new fields to the Google tab of the Configure Platforms section. These new fields, Google App Id, Google Client Id, Google Client Secret and Google Authorization Redirect URI are important when adding Google Authentication to your app (using Google’s latest libraries)
• Design | Authentication | Email Authentication
  • We’ve reworked this feature to work with Sendgrid. Once you’ve configured your SendGrid account, choose the (x) Use rich email service templates to switch to using custom templates that you define in SendGrid.
• Design | Integrations | Manage Integrations
  • Our new SendGrid integration has been added. Just sign-up for a free SendGrid account, and then enter your API key and such here, and you’re all set to go.
• Monitoring | Global Monitoring | Recent Logs
  • Added a new “Sys Info” category
• Reporting | Analytics
  • We’ve tweaked the platforms presentation to ensure that all platforms can be displayed properly
• General
  • The Login, Select Company, Registration and Forgot Password screens have been updated to the new look-and-feel
  • Internet Explorer and Edge browsers are now blocked from using the portal. We used to give warnings but still allow the user through – but we’ve had some pretty confusing support requests associated with those browsers – and feel its best for all parties just to not allow them.
  • 2FA confirms – we’ve added Authy OneTouch integration for some of our key confirmations (like when confirming whether an app should be deleted).
  • Bouncing cloud – we have a new “working” gif to distract you when brainCloud is processing your requests!
  • Cloud-code only api methods are now indicated by a new “secure” badge

API Changes

The following changes/additions have affected the brainCloud API:

• BrainCloudWrapper
  • Reconnect() – a new method that makes it easy to re-establish a session to brainCloud, using the cached anonymousId and profileId of the most recent connection
• Authentication
  • New authentication error code – UNKNOWN_AUTH_ERROR (40217) – for when Authentication() fails, but it is not the fault of the passed in credentials (rather, it’s an unexpected server error). The expected response would be to simply retry.
• Groups
  • The ListGroupsPage() method now returns the memberCount of the groups that are returned.
• Leaderboards
  • ListAllLeaderboards() – returns a list of all of the leaderboards for an app.
  • Management APIs– note that these methods are only callable from cloud code.
    • CreateLeaderboard() – creates a new leaderboard.
    • EditLeaderboard() – updates an existing leaderboard definition.
    • DeleteLeaderboard() – deletes an existing leaderboard configuration, together with all versions and entries.
• Log Service
  • The LogServiceProxy has been added to S2S – so you can now send log messages from both client-context cloud code and S2S-based cloud code
• New Mail Service
  • SendBasicEmail() – a quick and easy API for sending email messages to your users
  • SendAdvancedEmail() – an advanced API that allows your app to take advantage of the richness of the email provider when sending email messages to your users

Miscellaneous Changes / Fixes

• Updated libraries
  • All libraries have been updated with the latest API enhancements. Go get ’em!
• Documentation updates
  • We’ve updated the docs to better describe the mechanisms for client apps to download files
• Important Fixes
  • Fixed: Parent scripts can now properly call other parent scripts
  • Fixed: Added updated User Entity methods that accept the entity version parameter (as expected and documented)
  • Fixed: Added GetGlobalGameStatisticsServiceProxy() to the cloud code bridge
• Performance improvements
  • Improved performance for global leaderboard calls, especially if your app has multiple leaderboards
  • Background Segment processing optimizations
  • Performance improvements to the design portal for apps with large numbers of users (in particular, we were retrieving the list of recent added users much too often (unnecessarily))
• Miscellaneous fixes
  • All logged in platforms now show up on the User Monitoring | User Summary page (some were missing previously)
  • brainCloud system emails now use rich html — we’re taking advantage of SendGrid too!
• Plus miscellaneous fixes and performance enhancements…

Release Highlights

New Portal UI

By far, the biggest change in this release is our updated navigation and look-and-feel for the brainCloud Design Portal. The four biggest changes are:

• Modern Look-and-feel – a flatter, more contemporary look
• Simpler Navigation – we have revamped our top-level navigation to make it simpler
• Docs Menu – one-click access to our documentation, from any screen
• Quick Menu – quick access to the most-used portal screens

And we’re not finished yet. There will be more improvements coming in future releases – we hope you like what you see!

Enhanced Queries

We have significantly expanded upon the query syntax supported by the entity lookup routines.

So now you can do queries like:

“Give me all Book GlobalEnties that are either:

• written by Isaac Asimov or Timothy Zahn, or…
• are of category Science Fiction, have “robot” in the title, and cost less than $5.00″

{
    "entityType": "book",
    "$or": [
        {"data.author": {"$in": ["Isaac Asimov", "Timothy Zahn"]}},
        {"$and": [
            {"data.category" : "Science Fiction"},
            {"data.title": { "$regex": "robot", "$options": "i"}},
            {"data.price": { "$lte": 500}}
                ]}
    ]
}

Miscellaneous API Enhancements

We’ve implemented a bunch of customer-requested API enhancements – check the API Changes section to see if your favorite request made the list!

Portal Changes

Although the overall look and top-level naviation of the Portal has changed significantly, the great majority of features are right where you left them. There is nothing new to learn!

• Portal Navigation
  • We’ve replaced the old [Design | Monitor | Reporting] and [Gear] widgets with a simpler, more elegant top-level menu
  • The new Team menu is just the old Admin menu (which was triggered by clicking the Gear widget in the old UI). Same features – but much easier to find!
  • We’ve added a Docs drop-down so that brainCloud documentation is always just a click away
  • We’ve added a new Quick menu for commonly accessed screens, like the API Explorer, User Monitoring, and Analytics.
  • The User menu in the top-right corner now displays your Gravatar picture if you have one.
• User | Edit Profile
  • New Settings tab allows the user to set their preferred timezone and portal language. Note that these values are currently still stored in the developer’s browser cookies – they will be moving soon!
• Design | Core App Info | Platforms
  • We’ve removed the Client Libs section of this page – it was confusing and redundant with the Team | Client Libs page
• Monitoring | User Monitoring
  • The portal now remembers the last user that you were viewing and will automatically return to that user if you navigate away and then back. This is especially useful in conjunction with the new Quick | User Monitoring shortcut!
• General
  • Improved the “Delete Script” pop-up to more clearly indicate which script is being deleted!
  • brainCloud Portal now supports click-thru links – it will automatically prompt the developer to log in if they aren’t already. Handy for documentation, tutorials and bookmarks.

API Changes

The following changes/additions have affected the brainCloud API:

• Client
  • [NEW!] OverrideCountryCode() and OverrideLanguageCode() – allow apps to override the country code and language that are automatically detected by the client libs and sent to brainCloud during authentication. This is useful especially for Unity apps on PC and Mac, because Unity does not properly detect these values. These methods should be called before authenticating so that they are sent to the server.
• Friend
  • [IMPROVED!] Added pictureUrl to the returns for FindPlayerByUniversalId(), FindPlayerByName() and ListFriends()
  • [NEW!] FindUsersByExactName() – allows searching for users via an exact match (case insensitive). Will return as many users that match, up to the maximum.
  • [NEW!] FindUsersBySubstrName() – similar to the old FindPlayerByName() method, but still returns some search results even if the full results exceed the maximum.
• Leaderboard
  • [NEW!] GetPlayersSocialLeaderboard() – note the plural “players” in the name. Allows the app to retrieve the scores for the specified set of players. Useful in certain tournament situations.
• Logging
  • [NEW!] LogInfo(), LogWarning() and LogError() – new methods to allow you to easily log the results of cloud code routines
• Push
  • [NEW!] SendNormalizedPushNotification() – ability to send normalized push notifications to individual users
  • [NEW!] SendNormalizedPushNotificationBatch() – ability to send a normalized push notification to the specified set of users
• Queries
  • We have updated the accepted query syntax for all user, global and group entity lookups
  • These methods now accept queries that include (among others): $and, $or, $not, $nor, $in, $nin, $gt, $gte, $lt, $lte, $ne, $nin, and even $regex
  • The following methods have been updated:
    • User Entities:  GetList(), GetListCount(), GetSharedEntitiesListForPlayerId(), GetPage()
    • Global Entities: GetList(), GetListCount(), GetPage()
    • Groups/Group Entities: AutoJoinGroup(), ListGroupsPage(), ReadGroupEntitiesPage()

Miscellaneous Changes / Fixes

• Updated libraries
  • All libraries have been updated with the latest API enhancements. Go get ’em!
• Documentation updates
  • Friend service – we’ve updated the docs to more clearly indicate with methods require that the user be “friends” with the other user to function. (Spoiler: It is very few of them.)
  • Cloud Code – added service + operation for all cloud code method documentation
  • Obsolete docs – we’ve almost completely removed our old API docs – our new API Reference is the master now.
• Important Fixes
  • Fixed an issue where the global error handler was not sending the correct callback object when using the BrainCloudWrapper
  • Fixed a defect where the javascript library could send a bad rotation date to the server (with certain dates)
  • Server changes to better standardize language and country codes
• Plus miscellaneous fixes and performance enhancements…

2.26 is a smaller release that delivers some handy, customer-requested features. Take a look – there is something to love for everyone!

Release Highlights

WebHook Authentication

Some of you are looking to use our new WebHooks feature for integration with systems like Photon, that can benefit from leveraging brainCloud authentication.

To enable this, we have added a new Cloud Code Bridge method: GetSessionForSessionIdAndProfileId(). Using this API you can retrieve the current session for an active user, confirm that it is valid, and even take action within that user’s context.

Disabled Reason

We’ve added the ability to custom configure information to be sent to your client apps should you choose to temporarily disable your app. The info is in the form of a snippet of custom JSON data that will be returned along with the Authentication() rejection.

For more details, consult the Authentication section of our API Reference.

User Online Status

We’ve added a new method that you can use to query and report the online status of other users in the system. The method is called GetUsersOnlineStatus() and works with an array of profile ids. Just the sort of thing you would want to gather the online status of a set of Group / Clan members!

Clone Scripts

We’ve noticed that some devs, when creating a major revision to a Cloud Code script, like to begin by “cloning” it first – but we didn’t give you an easy way to do that – until now!

Simply choose “Duplicate” from the new Scripts action menu, and voila!, you are on your way!

Portal Changes

We’ve made the following portal changes:

• Design | Core App Info | App Ids
  • Google Services section – we now indicate whether a p12 certificate has been already uploaded.
• Design | Core App Info | Advanced Settings
  • There’s a new button, [Edit Disabled Reason], up by the [x] App Enabled box, that allows you to edit the JSON object that will be returned when your app is disabled.
• Design | Cloud Code | Scripts
  • The Script List functions have been organized into a new action menu, and includes the new Duplicate feature!
• Design | Custom Config | Files
  • The MD5 for a file is now displayed if you hover over its filename.
  • Troubleshooting: If for some reason the MD5 is not present, click [Refresh File List] to retrieve it.
• Monitoring | User Monitoring
  • All User Monitoring screens now bring up the New Users list if a user has not already been selected
• Admin | Home
  • There’s a new “gear” button in the Apps section that you can use to jump to the Apps screen
• General
  • We’ve fixed an error in the portal that mangled international characters if you tried to apply them to a user’s name, push notification message, etc.

API Changes

The following changes/additions have affected the brainCloud API:

• Cloud Code Bridge
  • The new GetSessionForSessionIdAndProfileId() method retrieves the specified active session object, if it is associated with the provided profileId. This can be used to validate that the user associated with the profileId has indeed successfully authenticated with brainCloud.
• Friend
  • The new GetUsersOnlineStatus() method can be used to retrieve the online status of the provided list of users.
• Global Statistics and User [Player] Statistics
  • New ProcessStatistics() methods have been added to both the GlobalStatistics and PlayerStatistics services that leverage the internal brainCloud Statistics Grammar, allowing for the batch processing of complicated stats operations to be carried out by the server.
• Identity
  • The various Identity methods ( Attach*(), Detach*(), Merge*(), etc. ) are now available from cloud code.

Miscellaneous Changes / Fixes

• Important Fixes
  • CDN robustness – we’ve improved our algorithms to better handle updating the cached files in the CDN when new Custom Files are uploaded to the portal.
  • Identifier syntax – The web portal now ensures that Global Properties and Cloud Code Script names adhere to the brainCloud identifier conventions of only letters, numbers and/or underscores
• Updated libraries
  • All libraries have been updated with the latest API enhancements. Go get ’em!
• Documentation updates
  • We continue to iterate and improve our new API reference
  • There is a new tutorial for Building the brainCloud Plugin for older versions of Unreal
• Plus miscellaneous fixes and performance enhancements…