Skip to main content
All CollectionsPortal-X Pages
Understanding the Compatibility Settings for your app
Understanding the Compatibility Settings for your app

Compatibility Flags

Jason Liang avatar
Written by Jason Liang
Updated over a week ago

brainCloud is constantly improving. We work very hard to ensure that your apps still work even as the platform evolves.

To achieve this, we sometimes introduce compatibility settings that preserve legacy behaviors for older apps. These settings are configured on the Design > Core App Info > Advanced Settings, Compatibility Settings page of the portal.

As new compatibility settings are added, they:

  • Default to enabled for existing apps to ensure compatibility

  • Default to disabled for new apps, so that they aren’t subject to legacy system limitations

It is best for overall behavior and performance if the compatibility settings are not enabled. Therefore, it is recommended that app developers periodically review these settings to ensure that only the required compatibility settings are enabled.

Note - these settings are now being presented in reverse-chronological order - i.e. newest to oldest.

[5.3] Do not enforce valid Country code

  • Prior to 5.3, brainCloud was not enforcing the country code values that would be accepted by the server

  • As of 5.3, the new behavior is to reject updates that do not adhere to the accepted list of country codes.

  • Leaving this flag enabled continues to allow any value to be set

[5.3] Do not preserve previous data when Post Score data argument is null

  • In 5.3, if the data argument is null when updating a score - the existing data value will be preserved. Prior to 5.3 the data value would have been reset to null.

  • Leaving the flag enabled preserved the legacy behavior

[5.2] Do not enforce current player for AsyncMatch SubmitTurn

  • Prior to 5.2, brainCloud was not properly enforcing that only the current player can call SubmitTurn() on an async match. This has been corrected.

  • Note that this flag does not affect any of the other AsyncMatch methods - which also enforces that only the current player can update the match.

  • Apps that need to update a match via the non-current player (for example - in timeout scenarios) are encouraged to impersonate the other player using a cloud code script via this technique ( as opposed to enabling this compatibility flag.

  • Leaving this flag enabled compromises match security.

[5.2] Support legacy case-sensitive redemption codes ('personal' scan codes)

  • Prior to 5.2, brainCloud was performing case-sensitive lookups for redemption codes. The system was changed to store codes in UPPERCASE and perform case-insensitive lookups. This compatibility flag is for older apps with existing redemption codes - to ensure the older codes are still found by the API.

  • Leaving this flag enabled slows down redemption code lookups.

[5.1] Allow AwardUserItem to be called from client (not recommended)

  • Prior to 5.1, brainCloud mistakenly allowed AwardUserItem() to be called from the client. We even mistakenly added it to the libs! That call is now restricted to being called from the server - unless this compatibility flag is enabled.

  • Leaving this flag enabled compromises the item security of your app.

[5.0] Allow unspecified event type for legacy send event

  • Prior to 5.0, the eventType parameter fo SendEvent() was highly recommended by not required. This parameter is now required by default.

  • Leaving this flag enabled allows null eventTypes - but will slow down the event processing of your app.

[4.15] Do not add default response media type accept header for responses (can interfere with request signatures if apps are not aware).

  • In 4.15 brainCloud added a default accept header to all HTTPClient calls to improve compatibility with external systems. This change could cause issues if a 3rd party system wasn't expecting the header for some reason.

  • Leaving this flag enabled removes the header unless specifically added by the developer to the HTTPClient calls.

[4.10] Include shared objects in Owned Custom Entity GetEntityPage queries (warning: can be slow). Can be overwritten by specifying 'ownedOnly' in query context 'options'.

  • The default GetEntityPage() behaviour was changed in a special 4.10 patch after several customer encountered severe performance issues with the call. It had to do with how the call was handling the check for ACL permissions (by default).

  • The call was changed to exclude searching for shared objects (i.e. owned entities with ACL set to accessible by other users) in favor with a stricter, faster search for objects owned by the current user ownly.

  • More information here

  • Apps should not enable this flag. If an app needs to search across shared entities, they should instead specifically include ownedOnly: false in the query context options

[4.10] Preserve legacy GroupEntity / Group ACL defect behavior

  • Release 4.10 fixed some issues with Group and GroupEntity ACL behaviour. In particular, some GroupEntity operations were being gated via the Group ACL instead of the Group Entity ACL

[4.9] Use legacy script path handling

  • Release 4.9 updated brainCloud’s handling of paths for the bridge.callScript() method to make it more consistent with industry standards (and our own bridge.include() method.

[4.8] Include legacy lobby owner field in API output

  • In 4.8 the data structures and IDs commonly used between Lobby Services and Relay Services were changed to be more consistent. The biggest impact of this was the replacement of the owner field in the Lobby data with the proper ownerCxId field.

  • Enabling this flag adds the legacy owner field back into lobby data messages

[4.7] Allow custom paths for Item catalog images in API

  • In 4.7, the Item Catalog service has been refactored to enable better image-file handling.

  • As part of those improvements, the service (by default) no longer allows for custom image paths (i.e. non-brainCloud anchored paths) to be set in the image field.

  • Apps wanting to use custom image URLs can use the custom JSON section or resource data sections for this information

[4.7] Use legacy Player Id

  • Several API methods, including UserService SysGetPage/Offset() calls, were fixed to properly return "profileId" instead of "playerId".

[4.4] Return legacy-format Multi Social Leaderboard results

  • The behavior of GetMultiSocialLeaderboard() was changed in 4.4 so that it no longer returns friends that haven’t played on any of the leaderboards requested

[4.3.5] Return milestones field instead of tasks field for older client Quest APIs

  • The schema for the embedded tasks within a Quest changed in Release 4.3.5.

  • Enable this flag to preserve the old behavior.

[3.9] Enable legacy Purchase Collection support

  • Storage of purchase transactions was changed significantly in Release 3.9

  • Enabling this option stores transactions in both the new and the old (legacy) format.

[3.5] Use legacy GCM for Google Push Notifications

  • This option is obsolete and should never be enabled.

[3.5] Include redundant legacy app Ids in some API results

  • Release 3.5 cleaned up the JSON response for some API calls.

[3.3] Send obsolete reward field content in XP level up rewards results

  • Release 3.3 fixed the json outputted during reward handling for XP level-ups – the returned json no longer includes the redundant “reward” section

[3.3] Do not reprocess currencies for non-consumable IAP products in receipts

  • In 4.13 the processing of non-consumable IAP products was changed - so that the awards would be processed even if the transaction had been previously processed by the user.

  • Enabling this options disables this behaviour. See the release notes for 4.13 for more information.

[3.2.5] Include entityId+ in UpdateSingleton API output

  • A significant optimization to UpdateSingleton() API performance was made in 3.2.5.

  • As part of that optimization, the entityId, acl, createdAt and updatedAt fields are no longer returned in the response for the call.

  • Enabling this option overrides the change, but also removes the optimization - resulting in significantly slower UpdateSingleton() API calls

[3.2] Generate Legacy Event IDs

  • Before release 3.2, the brainCloud Event System used numeric event IDs: eventId. These IDs had some significant limitations, including being slow to generate. The system has now been refactored to use a new and improved GUID-based ID: evId.

  • Enabling this compatibility flag tells the system to continue to create (at some performance penalty) the old eventId for Events. This is required if your app is still using the older API methods. It is recommended that all apps move to the newer APIs, and the new evId, at their earliest convenience.

  • Leaving this flag enabled slows down event processing.

[3.2] Enable Tournament Auto Claim check at login

  • Enable this option to get the payout rewards info included in the response of when the player re-login. Defaults to disabled because most apps will want to manually retrieve the reward information and present the earnings to the player directly.

[3.2] Allow Currency Calls from Client

  • In brainCloud 3.2, as a security + anti-fraud measure, we removed [by default] the ability for client apps to directly manage virtual currency balances. The affected methods, AwardCurrency(), ConsumeCurrency() and ResetCurrency() are still callable from server-side Cloud Code, which is much more secure.

  • Enabling this compatibility flag overrides this new restriction, and allows these calls to continue to be called from the client libraries.

[2.25] Funnel Custom and User File retrieval through app servers (slower)

  • Enabling this setting disables the Content Distribution Network (CDN) optimizations that were introduced in brainCloud 2.25. The main reason you might want to do this is because your client doesn’t properly handle the HTTP-based Redirects that are part of CDN processing. [your app asks us for a particular file, and we redirect the request to the appropriate CDN server. Older versions of Unity in particular do not support redirects – so this *should* be enabled for existing Unity-based apps.]

  • Workaround: Apps without redirect support should use the GetCDNUrl() method to retrieve the CDN version of a file’s URL for faster downloads (instead of enabling this setting).

  • For best results, the file retrieval compatibility flag should be left unchecked.

[2.25] Default to returning full Entity contents for create and update operations

  • Before Release 2.25, brainCloud always returned the full contents of an entity object after Create() and Update() operations. This seemed to make sense at the time, but as some customers expanded to writing objects of 100K or more, it became painfully obvious that this was a waste of bandwidth.

  • Enabling this compatibility flag will needlessly slow down client responses and increase the data usage of your app (affecting your customers)

[2.25] Enable legacy Currency handling (balance not enforced for consumption)

  • In brainCloud 2.25 we fixed a defect where the server was not correctly enforcing currency balances under all scenarios in currency consumption. This has since been addressed, but the compatibility flag exists in case some apps were depending upon the prior behavior.

[2.22] Return legacy-format Social Leaderboard results

  • brainCloud added support for manually managed friends in Release 2.22 – the implementation of which forced some changes to the JSON data returned from the social leaderboard APIs. This flag should only be enabled if your app pre-dates 2.22 and depends upon the details of the old format.

[2.22] Return User Entities during Authenticate and ReadPlayerState methods

  • Before Release 2.22, brainCloud was used to return all of a user’s User Entities in response to Authenticate() and ReadPlayerState() methods. This was pretty convenient for quickly launching and logging into apps – but didn’t scale when some apps started storing thousands of entities per user!

  • brainCloud no longer does this by default.

[2.14] Enable checking of Incoming Events with each API message

  • brainCloud includes an Events system that can be used to send messages (events) to individual users. This is useful for sending chat messages, awards, gifts, challenges, and the like. Earlier builds of brainCloud would automatically check for any incoming events for a user during the processing of every API call. This processing has a server toll, and as most apps aren’t using events, unnecessarily slowed down processing for everyday apps. Apps can instead use the GetEvents() method to poll for new events.

  • Update brainCloud RTT provides superior real-time notification for most classes of events. Apps requiring real-time notification should use RTT instead of enabling this flag.

  • Enabling the flag will slow down all API processing for the app.

[2.11] Use legacy Cloud Code result format

  • In brainCloud 2.10 we adjusted the JSON returns from Cloud Code scripts to align them better with the returns from regular API calls. This setting allows older scripts to still run.

Did this answer your question?