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…

We’ve got a doozy of a release for you heading into the Summer Holidays!

Release Highlights

WebHooks!

brainCloud now supports WebHooks! Which means it’s easier than ever to have your brainCloud app respond to events triggered from outside apps and services.

WebHooks are app-defined HTTP-callbacks that are triggered by events on another web service, and can be configured to invoke scripts in your app. The capabilities are similar to our Server-to-Server (S2S) interface, with the advantage that it is a more standardized mechanism, so tons of services already support it.

Examples of useful services that employ WebHooks include: Photon, Twilio, MailChimp, HipChat, Slack, Zapier, etc.

Setting up a WebHook integration is pretty simple:

• Write a new Cloud Code method that accepts our WebHook Parameter Syntax. The parameters you receive will be defined by the External Service that is calling you.
• Configure the WebHook using the Design Portal. You’ll give the hook a name, determine how you are securing it, and link it to your Cloud Code method. You use the Design | Cloud Code | WebHooks screen to configure your WebHooks.
• Register your WebHook URL in the external service. Finally, go to the external service and configure your WebHook, specifying the WebHook endpoint from the Design Portal, and any additional parameters that you require to be sent to your method.

Note – as with every external integration, we have to protect our servers from misuse. We have provided several mechanisms (server ip-validation and secret validation) to help your app confirm the identity of the service invoking the webhook. You should also ensure that your cloud script validates the validity of the incoming request. 

API Counts: Note that incoming webhook invocations count as 1 API count for the webhook itself, and 1 API count for the cloud code script being invoked.

[Note – we’ll be putting together a WebHooks tutorial in the next couple of days to better illustrate how they work.]

Faster File Downloads

We have re-factored our file-handling services to enable significantly faster downloads. The executive summary is that now when the client attempts to download a file via the URLs that are returned from GetFileList(), GetUpdatedFiles(), and ListUserFiles() – it will automatically be redirected to a cached version of the file located on a Content Distribution Network (CDN) node that is closer to them geographically.

The hitch is that Unity doesn’t natively support redirection (currently), so this doesn’t transparently work for our Unity apps. But don’t worry, there are two simple solutions:

#1 – Directly request the CDN-cached version of the File Url via the new GetCDNURL() methods (there are separate similarly-named methods for custom files vs. user files)

#2 – Use the UniWeb ($25) plug-in, which *does* support redirection, to retrieve the files instead of the built-in Unity libraries

#3 – Turn it off. Support for this behaviour can be turned off using the elegantly named “Funnel Custom and User File retrieval through app servers (slower)” compatibility option. You’ll find the option under Design | Core App Info | Advanced Settings, in the Compatibility Settings section.

Note – for maximum compatibility, the compatility flag defaults to enabled (that is, slower, legacy-mode behavior) for all existing apps. If your app would benefit from this speed increase, be sure to go disable the legacy setting!

Improved Entity Updates

We have revised our Create() and Update() Entity APIs to be much more efficient – and have revised the Increment() APIs to bring them into greater alignment with the others.

The biggest change is that the Create() and Update() methods no longer return the full entity data upon success. Returning the fully rendered object originally *seemed* like a good idea – and certainly looks good in the API Explorer for small objects. But if you are an storing larger objects, returning all that data in the API response just eats up the data connection (and isn’t useful to the app, since it already knows the data that it sent!).

Not that although the Create() and Update() methods for Entities* (i.e. User Entities, Global Entities, Groups and Group Entities) no longer return the full object upon success, they do still return the object skeleton (or summary), which includes the entityId, entityType, version, etc. The diagram below should better illustrate the change.

As always, we’ve added a new Compatibility Flag (“Default to returning full Entity contents for create and update operations”) to preserve the old behaviour if your app requires it. This flag defaults to ON for existing apps, and OFF for new apps moving forward.

Secondly, we’ve revised the new IncrementData() APIs to bring them into better alignment with the Create() and Update() methods. For example, like the methods above, IncrementUserEntityData(), will now return the full object skeleton upon success — with one addition – it will also return the updated balance of any fields that were incremented.

This new protocol was implemented by removing the old returnData parameter, which was a less optimal attempt to give the user control over what data is returned. The old method still works for apps using the 2.24 version of the libraries, but devs updating to 2.25+ will need to adjust their method calls accordingly.

Portal Changes

We’ve made the following portal changes:

• Design | Cloud Code | WebHooks
  • New screens for defining WebHooks. See the feature section above for details.
• Design | Marketplace | Products
  • We have enhanced the workflows so that you no longer have to manually press the [Facebook Register Products] button after making changes to the Facebook pricing information for products – it is now done automatically. We have left the button to support advanced scenarios where manually re-registering still makes sense.
• Monitoring | User Monitoring 
  • The new User Files screen allows you to view the files uploaded to an individual user account.
  • We have moved the in-app purchases that were displayed as part of the Virtual Currency screen to their own Transactions screen.
• Reporting
  • The  Sessions graph on the Analytics page now displays values according to local time.
  • We’ve added a new Incoming WebHooks count to the API Usage page.
• Miscellaneous
  • Faster App Deletion – Deleting an app now immediately marks it for deletion, to be completed by a background task during non-peak hours.
  • Password confirmations  – We have added more safety checks, where brainCloud will prompt you  re-enter your password for destructive operations (deleting an app, etc). We’ll be further enhancing these safety mechanisms in future updates. 

API Changes

The following changes/additions have affected the brainCloud API:

• Authenticate() and ReadPlayerState() methods
  • countryCode is now being returned
  • New isTester flag is being returned for users. This corresponds ot the [x] Is Tester checkbox that is selectable from Monitoring | User Monitoring | User Summary.  This is very handy if you want to trigger special logging, debug screens, etc to be available to testers but not regular users of your app.
• Client
  • New method (EndOfMessageBundleMarker()) for forcing the end of a message bundle. Useful for ensuring that large brainCloud requests are isolated into seaparate message bundles, and for ensuring that certain key calls (like LogOut()) get to return before continuing message processing.
• Cloud Code APIs
  • New CancelScheduledScript() method to cancel a scheduled cloud code job
• Currency APIs
  • Now properly enforces balance server-side for all ConsumeCurrency() operations. There’s a compatibility switch that defaults to ON for existing apps, but we recommend that all devs go to Design | Core App Info | Advanced Settings, and turn the “Enable legacy Currency handling (balance not enforced for Consume)” to OFF for their app (with appropriate testing, of course).
• Entity Create / Update APIs
  • As described in the Release Hilights section, API’s have been revised so that we do not return the full data content during Create() and Update() operations. There is a new compatibility flag to maintain the legacy behaviour (by default turned ON for existing apps).
  • The Increment() API methods have been revised to return results that are consistant with the rest of the Entity Create()/Update() methods. Revised methods include IncrementUserEntityData(), IncrementSharedUserEntityData(), IncrementGlobalEntityData(), IncrementGroupData() and IncrementGroupEntityData().
• Friend API
  • New GetSummaryDataForProfileId() method – returns the name, email, pictureUrl, and summary data for the specified user.
• Group APIs
  • New AutoJoinGroup() method allows you to automatically join a group that meets the provided criteria. Useful for quickly creating arbitrary grops of users.
  • The ReadGroupData() method has been added to client libraries (was missed last release – oops!)
• Identity APIs
  • New RefreshIdentity() method allows you to update identity tokens that are not the primary login identity

We have also removed / deprecated the following methods:

• Increment methods
  • We have removed the versions of the Entity Increment methods that accepted the returnData parameter.

Miscellaneous Changes / Fixes

• IPv6 Support
  • We have updated the C++ / Objective-C libraries to support IPv6.
  • We have re-confirmed that all other libraries properly support IPv6.
• Documentation
  • Completely revised and updated Cloud Code documentation section!
• Updated libraries
  • All of the supported libraries have been updated to support the latest APIs
• Plus miscellaneous fixes and performance enhancements.
• Miscellaneous page improvements – we’ve been iterating through our pages to add a bit more consistency and presentation polish.

We’ve got a smaller release for you this time. We’ve got a few bigger features cooking in the fires –  but in the meantime we thought we’d push out a few of the polish items and customer requests that we have queued.

Release Highlights

Authy OneTouch

We have enhanced our Two-Factor Authentication implementation to take advantage of Authy OneTouch for those users who are using the Authy App. It’s super convenient – no codes to enter! Just click [Approve] to confirm your login.

Customer API Requests

We’ve also released a few API enhancements at the request of some key customers. There are updates to Groups, Identities and the Cloud Code bridge. We hope you like them!

Portal Changes

We’ve made the following portal changes:

• Login
  • During Two-Factor Authentication you’ll notice the red One Touch meter. It tells you that we’ve detected that you have the Authy app, and have sent a request that you can simply [Approve] without having to enter the authentication code.
    Note: The login screen will stop monitoring for One Touch approval after 5 minutes, after which you can still enter the verification code.
• Power | Edit User
  • To ease the burden of 2FA, our login process optionally allows you to flag a device as trusted, so you won’t need to re-verify for 30 days. But what if you mistakenly hit that option when logging in from a public computer? Witness the new [Clear Trusted Devices] option on the Two-Factor tab of the Edit User dialog. Ta-dah! 🙂
  • Team Administrators can now unlink Two-factor Authentication from other user’s accounts (allows self-fixing of TFA-issues should they arise)
• General
  • Minor updates (for clarification and consistancy) to icons used throughout the portal.

API Changes

The following changes/additions have affected the brainCloud API:

• Cloud Code Bridge
  • New GetProfileId() method returns the profile id of the current user. Saves having to call to the PlayerState proxy for the information.
  • New GetName() method returns the name of the current user
  • New GetEmail() method returns the email address of the current user
• Groups API
  • Updated GetMyGroups() method to additionally return groups that you have been invited to and have requested to join.
• Identity API
  • New GetIdentities() method returns a list of the non-anonymous identities associate with the current profile. This method is useful to learn if the user has already associated a Facebook account with their profile, for example.
  • New GetExpiredIdentities() method returns a list of identitities with the current profile whose authentication tokens  that have expired (and should be refreshed)

We have also deprecated the following methods:

• Authentication Service
  • Deprecated GenerateGUID() and GenerateNewAnonymousId() – replaced with GenerateAnonymousId() method, which works in a more consistant manner.

Miscellaneous Changes / Fixes

• Updated libraries
  • All libraries have been updated with the latest API enhancements. Go get ’em!
• Documentation updates
  • Added Versioning overview to the Appendix summary of the API REF docs
  • Updated AsyncMatch documentation
  • Updated Leaderboard documentation
  • Better pre-hook cloud code examples
• Source updates
  • Removed JSON return data from the client source code, since that data is now included (and more likely to be up-to-date) in the API REF documentation
• Important Fixes
  • During login, if the user’s timezone has changed, the user’s timezone as recorded in segments is updated as well
  • Fix to Facebook purchase handling which could sometimes cause virtual currencies to be awarded twice in some circumstances
  • Added Facebook real-time payment transactions to the request logs
• Plus miscellaneous fixes and performance enhancements…

Release Highlights

This release delivers six new features:

• Groups! (i.e. Clans!) – allow your users to clan-up for greater socialization and competition!
• 2FA for Teams! An extra level of security for your development accounts.
• Scheduled Push Notifications! Deliver that message at exactly the right time no matter what timezone your users are in.
• Universal Windows Support – we have a new C++ library for Universal Windows Platform (UWP) apps.
• Xamarin Support – we have new iOS and Android libraries for Xamarin!
• watchOS Support – built native apps on watchOS using brainCloud!

Plus the usual assortment of API and library improvements. Note that all client libraries have been updated to the latest, except Javascript, which will be updated and released mid-next-week (week of Friday, May 18th).

Read on for all the details.

Release Highlights

Groups (i.e. Clans)

Although you’ve always been able to write your own clan system in brainCloud using Global Entities and Cloud Code, we thought it was about time that we lent a hand – reducing the coding burden, and adding great tools support at the same time.

This feature provides an API that allows users to dynamically create, join and manage Groups.

Groups have the following characteristics:

• Groups are a combination of a collection of users, plus some shared data about those users
• Groups in brainCloud are organized by Group Type. The developer defines a Group Type, setting certain rules such as the maximum # of members, and the action to take if a Group’s owner is deleted.
• There are three built-in roles – owner, admin and member
  • Groups are owned by a single user – but can have additional admins
  • Only the owner of a group may delete it. Owners may leave a group only if they re-assign ownership to another user.
  • Group membership can be open or closed. Open groups can be freely joined by anyone. Closed groups require an owner or admin to invite or approve join requests.
  • Groups can associate additional attribute data with members – which can allow for additional developer-defined role types (i.e. think ranks in Clash of Clans – Leader, Co-Leader, Elder, Member, etc)
  • A user can be a member of more than one Group. (Limits can be imposed by the developer, of course).
• Group data is a JSON object associated with the group. Access to the data is controlled by the group ACL.
• Groups can also own a set of entities (i.e. Group Entities) for more complex data needs. Group Entities can be owned by the group as a whole, or by individual members within a group.
• Group membership can be used for leaderboard retrieval

For more information re: brainCloud group support, refer to the Group API Reference Page .

Two-factor Authentication (for Team Members)

brainCloud’s Two-Factor Authentication (2FA) support allows you to tie your phone to your developer account for extra security and peace-of-mind.

We’ve chosen to use Twilio’s Authy technology for our 2FA implementation – it works similarly to Google Authenticator, but gives more options in terms of authentication (text, voice, or app) and offers better management of verification devices.

Hooking up 2FA to your account couldn’t be simpler:

• Choose Edit Profile from the top-right Power menu of the brainCloud Portal
• Go to the new Two-factor tab
• Click on the green [Click to Enable 2FA] button and follow the prompts!

For more information, refer to the Enabling 2FA page in our documentation.

Scheduled Push Notifications

Through the magic of scheduled cloud code and our push notification API, it’s always been possible to schedule push notifications to happen at a precise time. But – what if you want to send notifications to a segment of users, and ensure that those notifications get sent at a standardized local time – say 9am, for each of the users, regardless of their timezone? That was much, much harder.

Until now. Our new Schedule Push Notification interface allows you to specify a local time to send all notifications at. brainCloud will then automatically create the appropriate set of scheduled push notification jobs – one for each timezone involved – and then automatically send the notifications at the appropriate time for each group of users.

It’s extremely powerful, and very simple to use. Check out the new S2S API calls here.

Universal Windows Platform Support

We’ve created a new C++ library with support for Universal Windows Platform apps. And we’re making the library available via nuget as well. Stay tuned for more details.

Xamarin Support

With it’s recent acquisition by Microsoft and integration into Visual Studio, we’re finding tons of interest in Xamarin support for brainCloud. We’re pleased to announce the availability of the brainCloud Xamarin.ios and Xamarin.android libraries!

watchOS Support

Apple has announced that moving forward, all new and updated watchOS apps must be native. We are here to help, so we’ve built a new version of the brainCloud library that runs natively on watchOS 2. You’re welcome!

Portal Changes

The first thing you will notice is that we have re-ordered the tabs of the Design section of the portal to be mostly alphabetical (we still kept the Core App Info section at the top). We’ve added (and continued to add) so many features to brainCloud, going alphabetical seems like the only way to keep things easily findable.

In addition, we’ve made the following portal changes:

• Power | Edit User
  • Moved the Password section to a separate tab for clarity.
  • Added a new Two-Factor tab for enabling Two-Factor Authentication (2FA).
• Admin | Team Members
  • Added a 2FA column so that you can confirm which team members have enabled Two-Factor Authentication for additional security.
• Design | Cloud Code | Scripts
  • The scripts screen is now sortable according to the date+time that the scripts were last updated.
• Design | Groups
  • The new Group Types screen to allow you to define that types of groups that your application will support. Configuration information includes the maximum # of users allowed per group (default is 50 – contact us if you need higher), and what the system should do if the owner of a group is deleted.
• Monitoring | Global Monitoring | Jobs
  • Added support for viewing Scheduled Push Notification jobs.
• Monitoring | Group Monitoring
  • Added new Group Monitoring section to allow you to view and manage an application’s global user groups
  • The Groups screen presents a list of all groups, filterable by type of group. You can view the details of a Group by clicking on it – you can even edit the Group’s json-data.
  • The Group Entities screen displays a list of entities associated with groups. The list is filterable by entity type and/or group id.
    Pro-tip – to clickly see a group’s entities, look up the group in Group Monitoring first, and then choose “View Group Entities” from the action menu.
• Monitoring | User Monitoring | Groups
  • Shows the groups that a user is a member of, together with details about the group and the user’s membership.

API Changes

The following additions / changes have been made to the brainCloud API:

• Global Entities
  • New IncrementGlobalEntityData() method allows you to increment discrete numeric values in a global entity. Great for incrementing atomic stats-like values without pushing a full update to the entire JSON object.
• New Group API
  • There are too many new API methods to list here. For the full description of the new Group and Group Entity APIs, see the Groups section of the API Reference documentation.
• Leaderboard API
  • New GetGroupSocialLeaderboard() method retrieves a leaderboard filtered to the members of the specified group
• Push Notifications
  • New SendNormalizedPushNotificationToGroup() and SendTemplatedPushNotificationToGroup() methods sends push notifications to the members of a group
  • New S2S Scheduled Push Notifiation methods ( ScheduleNormalizedPushNotifications() and ScheduleRichPushNotifications() ) allow you to send push notifications to users according to their timezone
• User Entities
  • New IncrementUserEntityData() method allows you to increment discrete numeric values in a user entity. Just as useful as the GlobalEntity, Group and GroupEntity versions of the same method!
  • New GetSharedEntitiesListForPlayerId() method retrieves a list of shared entities for the specified player based on the specified where clause

Miscellaneous Changes / Fixes

• New/updated libraries
  • New Universal Windows Platform (UWP) C++ libs
  • New iOS and Android Xamarin libs
  • New watchOS libs
  • Upgraded version of OpenSSL in C++ libs
• Fixes and changes
  • Pre-hook cloud-code methods can no longer directly call the API that invoked them (prevents recursion loops!)
• Documentation Updates
  • Migrated reason codes over to new API Ref docs
  • Improved performance of new API Ref docs — Table-of-Contents now cached
  • API doc links in API explorer moved to new API Ref
  • Tutorials upgraded to link to new API Reference
  • New error handling tutorial
• Miscellaneous defect fixes
• Miscellaneous performance improvements