Highlights

• New feature: experiments (also called A/B tests) have graduated out of preview! Use them to build variants (alternative values for your game configs) and set up controlled studies to measure their efficacy in your live game. See Working with Experiments to get started!
• New feature: offer groups are a major upgrade to our existing in-game offers system. You can now organize individual offers into groups that can further be designated to different placements around your game along with advanced targeting and scheduling options. Have a look at Getting Started with In-Game Offers for a deep dive into the new system!
• New feature: BigQuery support for server-side analytics events enables writing analytics events into a BigQuery table. These events are written in a Firebase-like format to make analyzing the data a familiar experience. Additionally, an infra module is provided that automatically provisions the BigQuery Datasets and Tables, and configures the server to use them. See Streaming Analytics Events to External Storage for details.
• Major improvement: new SDK packaging more clearly separates the Metaplay files from game-specific files, making Metaplay upgrades easier and safer. Integration to new projects is also significantly streamlined. A minimal HelloWorld sample is now also included in the SDK. See Adding the SDK to a Unity Project on how to integrate Metaplay into a project.

Breaking Changes

• The following changes to the directory layout have been made to improve the separation of Metaplay SDK source files from the game-specific ones:
  • The Metaplay SDK files are now located in MetaplaySDK/ folder in the project root. For some projects, the Metaplay client SDK files remain under Assets/ and will be moved in an upcoming release.
  • The Server/Game.Server has been renamed to Server/Server.
  • The old Game.Server/Game/Server and Game.Server/Metaplay/Server directories for separating Metaplay and game-specific sources have been collapsed. They were obsoleted by the move of Metaplay sources to the MetaplaySDK/ directory.
  • Action potentially required. In case you have scripts or tools relying on the old directory structure, it needs to be updated to use the new layout.
• All the Player Incidents will get deleted with the release. This is done to ensure that migration steps performed on the table don't require a long maintenance window.
  • No action required.
• Game config references that are contained within game config data must now be wrapped in the new MetaRef<> type. See section Config Item**References Contained in **Game Config Data in Working with Game Config Data.
  • No action required. All existing config code has been changed to use MetaRef<>, but future code will need to account for this change.
• In-game offers are now more tightly integrated with the SDK and provide richer functionality, in form of the offer groups feature described in Getting Started with In-Game Offers.
  • Action potentially required. If you have a previous offer feature built on top of Metaplay, you should migrate them to the new system.

Notable LiveOps Dashboard Changes

• The game config detail page has been re-written so that you can view all the variants of a game config at once.

• The experiment detail page now uses the same game config variant card to easily display all the variant data for an experiment.

• Fixes to player incident reporting: loading states are now shown correctly, fetching incidents by type is now faster, and server-originated timestamps are used to avoid future timestamps in reports.
• New system for fetching and caching data from the server makes the dashboard snappier in everyday use.
• Events and offers now have more information on their respective list views to make navigation easier.
• More consistent UI layouts across all LiveOps pages to make them easier and faster to use.

Notable Under-the-Hood Changes

• Upgraded to .NET 5.0.9 (SDK 5.0.400).
• Upgraded dependencies, mainly: EFCore 5.0.9, Pomelo 5.0.2, and Akka 1.4.25.
• Upgraded to Unity 2020.3.17f1 for sample projects.
• Fixed a bug in the player incident tracker, which could cause the application to hard crash on some devices when a report was generated in a background thread.
• The new MetaRef<TInfo> makes references to game config data more explicit, safer and allows cyclical references within game config data. See section Config Item**References Contained in **Game Config Data in Working with Game Config Data for details.
• Segment size estimation has been separated into its own persisted service actor to reduce database load and increase robustness. The estimation operation also now uses a single sample of players to estimate against all segments instead of sampling the player base separately per segment, to better allow scaling up the number of segments.
• When reading DateTimes from the database, they are now returned with DateTimeKind.Utc (previously was DateTimeKind.Unspecified). Writing is always assumed to use UTC as well.
• The [AnalyticsEvent] attribute now accepts new arguments: includeInEventLog and sendToAnalytics which allow disabling the event to not go into the entity's event log or to external analytics storage.
• Built-in IAP analytics events now contain more information about the purchase and the phase of the purchase flow. New events track when IAP flow starts on the client, if it is aborted early on the client, and when the validation starts and completes.
• Upgraded AWS EKS version to 1.19. This upgrade can be handled with a regular Terraform apply cycle, but the update itself will require the updating of the EKS control plane, which may take around 10-20 minutes to carry out. Please plan infrastructure updates accordingly.

Version Compatibility

Infrastructure and Helm chart compatibilities for this release:

• Minimum version requirements
  • Requires infra-modules version v0.1.3 or later for infrastructure
  • Requires metaplay-gameserver Helm chart version 0.2.0 or later for deployment
• Suggested versions
  • Recommended infra-modules version v0.1.6 or later for infrastructure
  • Recommended metaplay-gameserver Helm chart version 0.2.3 or later for deployment

Change Log

Added

• SDK: Admin API now includes '/api/echo' endpoint to aid in debugging API connection issues.
• SDK: Added development-only Admin API entrypoint '/api/testEntityAskFailure' for testing EntityAsk error propagation.
• SDK: Added support for writing server-side analytics events into a BigQuery table.
• SDK: Added support for custom context data to IAP analytics events.
• SDK: Added analytics events for IAP flow start on client, IAP flow abort on client, validation start on server, validation completion on server.
• SDK: Throwing an EntityAskError from OnNewSubscriber handler rejects the subscription and the error is thrown on SubscribeToAsync call site.
• SDK: Ability to configure whether individual analytics events should go into the owning entity's event log and/or external analytics event sink.
• SDK: Added an SDK-side MetaOffers feature, which improves on the Shop Offers example feature.
• SDK: Additional server-side logging of connection information, such as local port and total bytes received during a connection.
• SDK: Add SDK-side default implementations of various client-side integration components, such as MetaplayClient and PlayerClientContext.
• SDK: Added information about the TLS layer in network related Player Incident Reports.
• SDK: Improved client and server-side detection and incident reporting of a connectivity issue where session communication is unhealthy despite connection handshakes succeeding.
• SDK: Dashboard-related HTTP requests are now logged on the server, including their duration, to better monitor their performance.
• SDK: Add Unity Package Manager compatible package.json entry in the Client folder for ability to import Metaplay SDK from local directory.
• Reference project: Support Auth0 as authentication provider for the Unity Editor GameConfig workflow.
• Dashboard: meta-time split into separate meta-time and meta-duration components.
• Dashboard: Added an API subscription and caching feature to simplify and speed-up access to server-side data.
• Dashboard: meta-list-card now has a permission-property to show a message when permissions are missing.
• Dashboard: Added new, easier to read view for game configs. The same view also highlights variant differences for experiments.
• Dashboard: Add link to Grafana Logs on the main page (with sensible query string pre-filled).
• Dashboard: Integration hook for being able to customize reward types per context.

Changed

• SDK: Experiments workflow streamlined and improved.
• SDK: Upgrade to Akka.NET v1.4.25: includes significant performance boost to Akka.Remote messaging.
• SDK: Don't allow null items or keys in GameConfigLibraries. Accidental nulls cause problems that are tricky to debug, so it's safer to not allow them.
• SDK: Removed Newtonsoft.Json.dll from Unity assets in favor of declaring the dependency as a Unity package.
• SDK: PlayerEventInAppPurchased schema bumped to version 2. Added new fields for store, product and context information.
• SDK: Segment size estimation now uses a single sample of players to evaluate instead of sampling the player pool separately for each segment.
• SDK: Segment size estimator is now a separate singleton actor. Asking for current segment estimate happens via EntityAsk-messages.
• SDK: Use more informative labels for expensive database queries to make it easier to pinpoint which systems are causing anomalies.
• SDK: In server logs, leave private-range IPv4 addresses (such as 10.X.Y.Z) unredacted for client connections.
• SDK: Add boolean argument allowMissingTranslations to GameConfigHelper.SplitLanguageSheets() to not throw errors on missing localizations.
• SDK: Game Config spreadsheet parser: throw an error when multiple columns have the same name.
• SDK: Game Config spreadsheet parser: throw an error when a column has no name yet is not fully empty.
• SDK: Added public setters for IPlayerModelBase GameConfig, IGuildModelBase GameConfig and IModel LogicVersion.
• SDK: Config data references contained within config data must now be wrapped in the new MetaRef<> type, which allows also forward references between config items.
• SDK: Use coarser histogram buckets for database latency metrics to keep number of metrics more manageable.
• SDK: Moved Metaplay SDK source files for backend components to the MetaplaySDK folder.
• Dashboard: Increased broadcast components reusability by allowing changing the item name ("broadcast" by default) via properties.
• Dashboard: Core tests refactored to utilise data-cy properties for finding elements.
• Dashboard: New notification and broadcast list page layouts for more consistent usability.
• Dashboard: Game config detail view's configuration list now looks more consistent and is a bit easier to use.
• Dashboard: Incident reports are now displayed more prominently in the player details page.
• Dashboard: Incident reports have an additional description about NullReferenceExceptions.
• Dashboard: The filtering and sorting utilities of various cards are now easier to open with a bigger click area.
• Dashboard: Cypress test runner updated to 8.6.0.
• Dashboard: Nicer error message when there is no game server connectivity.
• Dashboard: Major iteration on experiment pages to show more relevant information at-a-glace and easily control the various experiment states.
• Dashboard: Major iteration on the meta-raw-data component for better usability and rougly 300x performance improvement.
• Dashboard: The Dashboard NPM project has been moved to MetaplaySDK/Backend/Dashboard. Game-specific integration files remain in Server/Dashboard.
• AdminApi: Audit logs search endpoint split into simple and advanced versions, requiring different permissions.
• AdminApi: Always specify listen host/interface via runtime option AuthenticationOptions.ListenHost and ListenPort (launchsettings.json is ignored).
• Reference project: Reset database schema migration history.
• Reference project: Upgraded to Unity 2020.3.17f1.
• Reference project: Removed the Shop Offers example feature in favor of the new MetaOffers.

Fixed

• SDK: Client incident reporting system now recovers from corrupted incident report database.
• SDK: Better error message for OrderedDictionary<> constructing from IEnumerable<> when there are multiple items with the same key.
• SDK: The generated serializer now gets recompiled when a field is changed to a property or vice versa. Previously, a runtime error might happen when using the serializer after such a change.
• SDK: HttpUtil now avoids large temporary allocations when executing large JSON requests.
• SDK: When writing analytics events to an external S3 bucket, an extra leading slash is no longer generated.
• SDK: In SessionActorBase, tolerate other actors' CastMessage-sent messages arriving outside a session.
• SDK: Fix notification campaign getting stuck when a single player's notification token count exceeds the send batch limit (100 tokens).
• SDK: Always assume DateTimes are read/written to database as UTC. Previously DateTimes were returned with DateTimeKind.Unspecified.
• SDK: Specify MaxLength for PlayerIncidents.Fingeprint, so it can be used in MySQL indexes.
• SDK: Add new database index for PlayerIncidents that makes querying incident reports by type much faster.
• SDK: Unhandled expections from Actions executed for Player Consistency Checks are no longer fatal and instead log a warning.
• SDK: Don't require ASP.NET developer certs to be generated by only listening on the HTTP interface. HTTPS is terminated in the load balancer.
• SDK: In AdminApi endpoints for GameConfigs, when json-serializing config patches, use the config entries' C# member names instead of the names given in the [GameConfigEntry] attribute. This fixes dashboard's visualization of experiments in cases where the two names differ.
• SDK: MetaActivableState.IsInReview: If a config change has moved the schedule into the past beyond the latest activation, don't erroneously treat it as in-review. This fixes a AdminApi/dashboard error for players with such activations.
• Reference project: Fix some NREs when shutting down the game.
• Dashboard: Fixed meta-raw-data previews showing unhelpful data for non-object data types.
• Dashboard: Fixed "Select Individual Players" targeting form text box being too narrow on most screen sizes.
• Dashboard: Incident loading state is now properly visualized instead of indicating that there are no incidents.
• Dashboard: Show incident report upload time instead to get a reliable clock for them (instead of device clock-based time of occurrence).
• Dashboard: Fixed right borders not always hiding on narrow screens when the parent container reorders from horizontal to vertical list.
• Dashboard: Fixed an issue when very long IAP receipt ID's would sometimes truncate instead of wrap on a new line.
• Dashboard: Fix 'View Logs' link in player login history.