With release 3.6.5, brainCloud is breaking away from the singletons that were previously a key aspect of our client libraries.

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

Background

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

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

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

The library is actually organized into two major components:

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

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

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

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

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

The cons (as we now see them) are:

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

The fix

And so, we are fixing this.

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

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

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

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

It can look like this:

_bc.LeaderboardService.ListAllLeaderboards( ApiSuccess, ApiError);

The Changes

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

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

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

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

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

And that’s about it.

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

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

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

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

Legacy Singleton Mode

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

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

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

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

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

.

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

Conclusion

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

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

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

Cheers!

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 actually 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:

• Obviously, 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()

Parse and who can you trust?

On Thursday, Facebook dropped a bomb. They announced that they were shutting down Parse, the Mobile Backend-as-a-Service (MBaaS) platform that they acquired in 2013.

Parse is one of brainCloud’s competitors, and arguably the biggest and most established player in the BaaS industry. Even so, brainCloud doesn’t run up against them that much because we have a richer, more specialized featureset that works better for our customer base.

In the wake of this event, it is inevitable that people are asking “What happened?” and “How can we trust any BaaS to build our business upon”. To that end, I thought I’d put together a few thoughts.

Why was Parse shut down?

The internet is a-buzz with comments that the business must have been failing.

I don’t buy that. The business case for the Backend-as-a-Service market is very strong, and Parse had a good product for the space they were aimed at. By all accounts, they had plenty of customers and an overall strong business. So why close it?

The answer is that Parse no longer aligned with the goals of it’s parent company, Facebook.

At the time that Parse was acquired, Facebook was floundering. They had recently IPO’d, but hadn’t figured out their mobile and advertising strategy. The stock was down, revenues were down – and they made a series of acquisitions hoping to strengthen and diversify their portfolio. Parse, well positioned as a platform for enabling mobile apps, seemed like a smart play to help them build up their mobile presence. And I’d say it was.

But now, almost three years later, things have changed. Facebook has totally turned it’s ship around. It is now a juggernaught in mobile, has advertising sales through the roof, and is more focused than ever on building out its core product. In managing everything it is doing, Facebook needs to continually ask itself: “Is <x> strategic to our overall success?”

And I think that’s where Parse failed the test. Parse’s business was probably $50-$100M per year. Healthy, for sure – heck, we’d take it! But that’s just a drop in the bucket to Facebook (less than 1% of revenue!), which will net close to $20B this year. And yet, I’ll bet that division had some of Facebook’s best engineers!

And that’s what it comes down to – Facebook said as much in their blog post. They are going to “focus their resources elsewhere.” I don’t think this is the normal generic excuse that a company makes when they announce bad news – in this case, I believe that it is very literally what they are doing.

Who can you trust?

In the wake of the Parse shut-down, a lot of people will be wondering how they can put their trust in any Backend-as-a-Service. After all, a ton of people probably chose Parse specifically because it was run by Facebook – a huge, incredibly successful organization, that was guaranteed to be around for years to come.

Here is my suggestion on the evaluation criteria to consider:

1. Feature Set – always start with the features – there is no point in going for a solution that doesn’t meet your needs.
2. Organization – consider the organization that develops it. Are they a long-standing, established business, that has earned a solid reputation in the marketplace?
3. Funding – how is the company/product funded? Beware of purely VC-funded companies. A lot of BaaS vendors are early stage VC-funded – this makes for splashy million dollar announcements and marketing materials, but the funding comes with strings attached, in terms of “You must succeed by <x> or you will be shut down.”
4. Business Model – does the business model make sense? Is it easy to understand how the business would make money for the organization? If not, be wary – a “too good to be true”business model is often a sign of a last-ditch “hail mary” throw for success.
5. Alignment – Does the product align with the strategic goals of the parent organization. No matter how good the product, Facebook has just proven that you are in danger if a clear alignment isn’t there.

Given this critera, how does brainCloud rate?

1. Feature Set – we pride ourselves on our features, and the rapid pace at which they are evolving. With brainCloud (especially in comparison to a lower-level offering like Parse), you spend less time building features and more time using them. And we match each new feature with a visual tool for configuring and managing it.brainCloud goes over-and-above the classic BaaS capabilities with support for Gamification (xp, milestones, quests, achievements, leaderboards, etc.), Segmented Push Notifications, Scheduled Cloud Code, Auto Promotions, Mobile Multiplayer, Shared User Accounts, External Authentication, Server-to-Server APIs, a dynamic DataStream Architecture, and much much more.
2. Organization – brainCloud is built by bitHeads, a 20-year old technology software developer based in Ottawa, Canada, in conjunction with playBrains, our game development subsidiary. bitHeads has earned a reputation as one of the top software development companies in Canada, and through the years has built award-winning products for Microsoft, Sony, Blackberry, Canada Post, Samsung, E*Trade, Nortel, Mitel, and hundreds of others.
3. Funding – brainCloud is privately funded by bitHeads, its parent organization, with some assistance from various Canadian government programs. We are privately controlled, and thus no ultimatums.We started building brainCloud over four years ago, well before the term BaaS or MBaaS was a thing. We saw the value and opportunity in this market back then, and are determined to build the best product for it.
4. Business Model – we don’t give brainCloud away, but we do work to keep the cost of the service as low as possible. brainCloud is free for development (maximum 100 dau), but you pay starting at $30 / month once you go live. This minimal charge ensures that every brainCloud customer is pulling their weight and paying their share of the costs for the service. This allows us to offer lower prices than our competitors, while at the same time ensuring that bitHeads can operate brainCloud indefinitely.Contrast that with the models of some of our competitors, and ask yourselves how they can possibly be successful in the mid-to-long term? They have to charge their paid users more, and are basically betting that they will have enough high-volume customers to pay for the inevitably huge number of low-volume customers (that they subsidize for free). And some models are even crazier! These are the sorts of bets that you make when you are desperate for your next round of VC funding, or looking to be bought.
5. Alignment – brainCloud arose because bitHeads was constantly building custom backend solutions for our customers. And we were building them over-and-over again, with largely the same features. For online casinos. Retail networks. Telecommunications. Mobile/Social games. For twenty years.Four years ago, we finally said, wait – what if we did this once, and productized it, so that we (nor anyone else) has to keep re-inventing the wheel? And thus brainCloud was born. It started as a small, separate team working within the company to build the core server system. We released the first apps on the platform almost three years ago – before we had a design portal with which to design and manage things (configuration was CSV and JSON back then).Today the team consists of twenty-ish people within the larger bitHeads/playBrains organization, together with the support teams to make that work. All services teams at bitHeads are aligned to delivering products and services around brainCloud. The custom apps and games that we build today are built upon brainCloud – it’s our competitive advantage. And we continue to productize and evolve the platform based on the feedback of our great community of developers.There’s no fear of alignment here – bitHeads is brainCloud.

And there you have it – my take on Parse, and how bitHeads and brainCloud rate as a Backend-as-a-Server that you can trust. To our brainCloud customers today, thanks a bunch – rest assured, we are in this for the long haul.

And if this is your first exposure to brainCloud, please sign up and take a look for free. If you take a good look at our features and tools, we think you’ll realize the power of the system we’ve developed, and the passion of the folks building it.

Oh – and if you are looking to move from Parse, please check out this survey. Filling it out will help us to prioritize the tools and support processes that we’re developing to assist Parse migration.

Happy coding folks!

Paul.

(PS – And for all you Parse-based folks looking to move, feel free to reach out. Our services teams would be happy to help you move over to our platform!)

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

• platform – the type of device that the user is logging in from
• gameVersion – the version of the client game or 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.In 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!