Launch Tip #1: Version Enforcement

Launch Tip #1: Version Enforcement

This post is the first of our new series on best practices to observe before launching your app.

It’s an exciting feeling… Features are complete. Beta feedback incorporated. Final bits of polish applied. You are ready to launch.

Or are you? Are you sure that you have… Tested for every usage scenario? Every race condition? On each of thousands of device variations? Under unpredictable network conditions? Accounted for changing performance characteristics as your user base ramps?

Luckily you are using brainCloud – so you know your servers will handle the loads. But what about your client app? Your dev team is prepared to react and fix issues quickly – but how will you ensure that important updates make it to your users quickly?

Sure – the app stores support automatic software updates – but even so, it can take 3 weeks before the majority of your user base is using the new version of your app. That’s far too long if your app is crashing, corrupting data, and/or generally frustrating your users. In those 3 weeks your app’s ratings will take a huge hit.

This is why it is essential to implement Version Enforcement before you go live.


The good news is that brainCloud makes it easy.



Version Enforcement

brainCloud has built-in support for enforcing minimum client versions.  During authentication, in addition to transmitting information about the user that is logging in, the brainCloud client library sends two key pieces of information:
  • platform – the type of device that the user is logging in from
  • gameVersion – the version of the client game or app
These parameters aren’t just informational – brainCloud’s Version Enforcement feature allows you to ensure that only users of a specified version and above can log into your application. This forces out-of-date users to upgrade their clients before proceeding.
Version Enforcement is configured via the brainCloud Portal, and works in collaboration with integration code that you add to your app.



Above – the Design | Core App Info | Platforms screen

Note –  you can specify this minimum version on a per-platform basis, allowing you to accommodate staggered release schedules, different app approval processes, etc.



Integrating Version Enforcement

Integrating Version Enforcement into your app is very simple.

Follow these steps:

  1. Set the app version in your client app. In most of the brainCloud client libraries, this is done via the BrainCloudClient.Initialize() function. In Unity, you can use the brainCloud Settings dialog.bc_version_unityIn either case, the version should be a string of format of “X.X” or “X.X.X” – for example, “1.0.0”.
  2. Go to Design | Core App Info | Platforms, and temporarily set the minimum app version to something higher than your current app version.
  3. Enhance the Authentication error handling of your app to catch the out-of-date error response (see the Version Enhancement section of the Authentication API page for details) – and display an appropriate message to the user. Ideally you should redirect the user to your apps store page so that he/she can trigger the update immediately. The brainCloud portal allows you to datafill the upgrade URL along with the minimum version.

  4. Test to ensure that it works!

That’s it. Once this is in place, you will rest easier knowing that if (when) your users find problems in the field, that you’ll be able to push fixes to them in no time!

Release 2.17.0


Release Highlights

Key features in this release:

  • Apple TV Support! We’ve updated our libraries to support the new Apple TV. We can’t wait to see what you build!
  • Unreal Blueprint Support! It’s been a long time coming, but we’re pleased to finally announce the availability of our Unreal plug-in, with Blueprint, C++, and [basic] Online Subsystem support.
  • Redemption Codes  Planning to distribute individual codes to unlock characters / cards / etc. in your game? brainCloud’s new redemption code system is exactly what you need. More info on the feature and it’s API here.
  • Long-running Cloud Code – we’ve added support for long-running Cloud Code scripts, and adapted our Cloud Code billing strategy to better support this use case.  More details below.

Those are the biggies, but there are a bunch of other changes and improvements in this release. Read on.


Portal Changes

Changes to the portal:

  • Improved Timezone support – you can now specify the timezone used for viewing date+time data in the portal.  Note that the timezone will initially default to UTC – but it will remember what you set it to. Use the control in the top-right-hand corner of the portal to change the displayed timezone at any time.
  • Redemption Code Screens – you’ll find new screens for the Redemption Code feature under Design | Marketplace, Global Monitoring and User Monitoring.
  • Apple TV platform support – you’ll find Apple TV entries in Design | Core App Info | Platforms, as well as iTunes pricing component of Design | Marketplace | Products
  • Cloud Code Timeouts – you can now set custom timeouts for your cloud code scripts from the Design | Cloud Code | Edit Scripts screen.
  • Updated API Usage page – the Reporting | API Usage page has been updated to support the new cloud code billing formulas


API Changes / Additions

Changes and additions to the API:

  • Redemption Code API – added methods for Redeeming codes and retrieving the list of codes that have been redeemed by a user. The key client api methods are RedeemCode() and GetRedeemedCodes().
  • Push Notifications to Segments – you can now programmatically (via the Server-to-Server API) send push notifications to all of the members a Segment.
  • Authentication Timeouts – a new client method has been added to override the authentication timeout.
  • Retrieve Multiple Social Leaderboards – building a game with a Candy Crush-style map? We’ve got a new API call that retrieves the top friend entries from up to 20 leaderboards that you specify. Great for putting profile pics of the lead scores onto your map! Check out GetMultiSocialLeaderboard().

We’ve also made two more important changes to the Client Libraries:

Error Handling Changes

We’ve made some enhancements to how the brainCloud Server and Client libraries work together to communicate error information.  Specifically, we’ve enhanced the <statusMessage> parameter for the error callback method to contain not only the textual message associated with the error, but actually the entire json result of the error.

This allows us to return more detailed error information, whose structure may vary on an operation by operation basis.  For example, if authentication fails because the client app’s version is obsolete, the returned error information can include a link to the app in the appstore to use to perform the software upgrade.

If by any chance your client app was parsing the <statusMessage> – most apps weren’t, because it wasn’t very useful – you can still get the old data by referencing “statusMessage.statusMessage”.  Or, you can turn this new behaviour off using the BrainCloudClient.SetOldStyleStatusMessageErrorCallback() method.


Unified Rewards Processing

In addition, we’ve unified our rewards processing to invoke a standard Rewards Handler whenever rewards (achievements, xp, milestones and quests) are awarded from one of the many APIs that do so (i.e. authenticate, increment stats, stats event, etc.).  You can now hook into that single handler to splash Achievement Unlocked onto the screen, Quest Completed!, etc…  instead of duplicating that functionality across multiple handlers.

As part of this change, brainCloud no longer automatically triggers the associated local platform Achievement.  This platform-specific code was causing porting issues as we continue to expand the list of devices that we support. By centralizing the error handling it becomes very simple for the client apps to integrate what is in most cases a single line of code to trigger the local achievement.

To register for the new Rewards Callback, call RegisterRewardCallback() in your local library.

[Important note – the standard success and failure callbacks for the API calls still trigger. The rewards callback will trigger afterwards. Usage of the rewards callback is entirely optional.]


Miscellaneous Changes / Fixes:

Additional improvements to this release:

  • Fixed match expiry not working in certain situations
  • Added missing reason codes to clients
  • Improved timeout checking on errors in C++ client
  • Improved handling of iTunes subscriptions
  • Minor fix to version comparisons during authentication
  • Universal authentication no longer accepts blank passwords!
  • Removed entity sub-type from Player Monitor | Entities screen
  • Improvements to french translations in our portal!
  • Added Portal Warning for Microsoft Edge browser – stick with Chrome, Firefox or Safari for now
  • Improved the links to API docs in the Explorer
  • Miscellaneous documentation improvements


Cloud Code Timeouts

When we first added Cloud Code support, we envisioned folks using it primarily for optimizing their client-server calls, and/or implementing sensitive logic on the server. For that sort of usage, our standard 10-second watchdog timer made sense.

But then we added support for Scheduled Cloud Code jobs – and you guys blew the doors off our Cloud Code usage scenarios! All of a sudden folks could schedule daily, hourly, etc. scripts – and some of these scripts were making hundreds and even thousands of API calls when they run.

It didn’t take long before folks started to hit the 10-second watchdog timer, which kills your script if its still running when the timer expires. The watchdog is there to ensure that our server doesn’t get hit by javascript coding errors (think “infinite loops!”). Needless to say, it’s an important part of ensuring that our servers remain safe and reliable when executing custom scripts.

In the short-term we had to raise that 10-second timeout globally across the system to keep some of our leading clients apps running properly.  We’re pleased to have our long-term solution in place now – which allows developers to set a custom timeout value for their individual scripts.  All new scripts will default to 10-seconds – but you can individually raise the timeout as high as 60 seconds.  Note – if required, it’s possible to raise it even higher. Just message our team to have them raise your limit.

Setting cloud code timeouts
Setting cloud code timeouts


Billing Changes

We’ve also tweaked how we count API calls to better reflect these new Cloud Code usage scenarios.

As you know, the power of cloud code is that combining a collection of API calls together into a single cloud code script performs better than making the calls individually from the client – and also taxes our servers less – so it’s win:win. The new formulas for counting API calls under Cloud Code take this into account, and provide a fair balance of cost to the developer (you) and covering brainCloud server utilization (phew!).

The updated rules are as follows:

  • Calling a cloud code script counts as 1 API call (same as today)
  • The first three API calls from within an invoked cloud code script are free
  • Any remaining calls from within cloud scripts are discounted to 1/2 an API call

If your app makes moderate use of cloud scripts, using them to string together common server requests (e.g. making a combined call to post a score, update player stats, and update a user entity describing the player’s progress) – this pricing update likely doesn’t affect you at all.  This includes the great majority of our customers today.

This new strategy allows our customers the flexibility of running much more ambitious Cloud Code scripts – at a greatly reduced cost per API call invoked.

If you have any questions or concerns, don’t hesitate to contact us through the support messaging system.