Upgrade from Legacy Analytics to Unity Gaming Services Analytics 

Background

In October 2021, we launched Unity Gaming Services - an end-to-end platform with flexible solutions to help you build, manage, and grow your game. With the launch of Unity Gaming Services, we rebuilt our standalone Legacy Analytics tool to be integrated within the platform.

Our new Analytics solution is a data visualization and dashboard tool that helps you understand and analyze all of your game data in one place. It works as a standalone tool (similar to the Legacy version) or you can use it with other Unity Gaming Services offerings for added functionality. It has all of the functionality in Legacy Analytics with improvements and new features.

Today, our new Analytics offering is free while in beta. Eventually, it’ll have free tiers with a pay-as-you-scale pricing model - learn more about Analytics pricing here.

Impact to me as a Legacy Analytics User

To invest more resources into our upgraded Analytics platform, Unity will stop investing in Legacy Analytics and sunset the product by the end of 2022. It’s advised that new projects are created within the new Unity Gaming Services Analytics platform. We also recommend using this guide to transition existing projects to the new platform.

Transitioning a live game to a new Analytics solution can be difficult, so we’ve designed a migration pipeline to run Analytics and Legacy Analytics in parallel. The core events data (from July 2021 onwards) from your Legacy Analytics integration will automatically import into the new Analytics solution. Metrics such as DAU, MAU, session length, revenue, and others can be populated in the new Analytics solution for a trial of the product ahead of implementing the SDK.

For data continuity between both legacy and new Analytics platforms we recommend using the userID that is provided by the SDK. This userID is shared between the two Analytics platforms and our data migration pipeline will use it to avoid the duplication of events. When an event is received for a userID through UGS Analytics SDK into UGS Analytics, that user will be blacklisted from the migration pipeline. That means that if there are events still going into Legacy Analytics, they'll be processed and shown as normal on the Legacy Analytics dashboards, but they won't be passed through this migration pipeline into UGS Analytics.

Please note that this does not cover any custom events that you have defined; these will need to be redefined both in your game code and the dashboard. See the guide below for more information.

Note: No duplication or double counting will occur; standard events being triggered by the Analytics package will take precedence over imported data for each individual player.

Follow the steps below to upgrade your existing projects to use Analytics. If you do not have custom events defined in your project skip step 2 and 3.

Note: Custom events are only supported once the package is installed in your game.

Step 1: Install the Analytics package

The Analytics package is on the Unity Dashboard, where you can download a code snippet to add to the Editor package manifest file. This will expose all of the latest Gaming Services packages.

Note: You’ll need to sign up to the beta to obtain access to the packages.

Steps:

  1. Go to the Unity Dashboard.

  2. Go to Project Settings.

  3. Click Settings > SDK Download.

  4. Select Analytics from the list of available packages. This also automatically selects any package dependencies.

  5. Click Generate Code Snippet.

  6. Select Analytics from the list of available packages. This also automatically selects any package dependencies.

Refer to SDK initial setup for more details.

Note: Your local project build needs to be linked to a Unity Project ID - see here.

Once you initialize the SDK it’ll automatically send the newPlayer event the first time the SDK is run, the gameStarted and clientDevice event each time the game runs, and the gameRunning event every minute. See Standard Events.

Events will show up in the Event Browser in the dashboard approximately 15 minutes after being fired. Metrics and events in all other Analytics features can take up to two hours to appear - when fired for the first time they’ll be refreshed every hour. For more debugging information see here.

If your project doesn’t already have custom events defined in the game code, your integration is done.

Step 2: Create custom events

Custom events that have been created in the Legacy solution are not automatically brought over to Analytics due to the free-form nature of the events and will require some steps to be redefined in the new system.

Note: Events and their respective parameters need to be created within the Event Manager in the dashboard as they’ll otherwise be considered as invalid.

Create each custom event in the Event Manager to match the events being recorded:

  1. Go to the Event Manager in the Unity Dashboard under Analytics Beta.

  2. Create custom event - ensure the name matches.

  3. Create and assign parameters - ensure all parameters are defined to avoid the event being classed as invalid.

Note: Custom events created in your game code that are not defined in the Event Manager will be considered invalid and won’t track data. These will show up in the Event Browser

Step 3: Change Event logging method

Update your game code to record custom events using the “Events.CustomData” command detailed here.

Before

Copy
public class GameLoginMonoBehaviour : MonoBehaviour
{
    public void OnGameOver()
    {
        int totalPotions = 5;
        int totalCoins = 100;
#if ENABLE_CLOUD_SERVICES_ANALYTICS
        Analytics.CustomEvent("gameOver", new Dictionary<string, object>
        {
            { "potions", totalPotions },
            { "coins", totalCoins }
        });
#endif
    }
}

After:

Copy
// Create parameter custom event (Same as Legacy Analytics)
public class GameLoginMonoBehaviour : MonoBehaviour
{
    public void OnGameOver()
    {
        int totalPotions = 5;
        int totalCoins = 100;
// The 'gameOver' event will get queued up and sent with the
// regular 60 second upload
        Events.CustomData("gameOver", new Dictionary<string, object>
        {
            { "potions", totalPotions },
            { "coins", totalCoins }
        }); 

// Optional - You can call Events.Flush() to send the event
// immediately else it will be cached and sent with the next 
// scheduled upload within the next 60 seconds
Events.Flush();
    }
}

Custom events can be verified in the Event Browser or analyzed in the new Data Explorer. If you need to test a lot of events multiple times, you can create a test environment so your live environment only keeps data from your players. Read more about environments here.

FAQs

Will there be inconsistencies when comparing Legacy Analytics and Analytics data?

While we have made our best efforts to keep data consistent between Legacy Analytics and Analytics (Beta), we’ve taken the opportunity to address customer feedback, so there may be some slight inconsistencies when directly comparing the two systems. There are a number of reasons for this:

  • Analytics (Beta) processes event data every one/two hours compared to Legacy Analytics which processes event data every eight hours.

  • Stricter event structure has been introduced so your data is consistent, flows in gameplay, and metrics are as accurate as possible.

  • Event data is processed in raw form so you can query, filter, and group your game data in Data Explorer.

  • Event data from Legacy Analytics is available from July 2021 onwards. Players who installed your game prior to that date will be treated as new players and this may result in a peak in retention metrics.

  • Some metrics are being calculated differently in Analytics. For example, session length is determined by calculating the time difference between events in a session compared to tracking the session length on the client’s device. See the KPI and metric explanations available in the dashboards and metric dropdown in Data Explorer.

Will custom events sent to the legacy backend be lost?

At present any standard events, recorded since July 2021 with the legacy Analytics system, will be visible in the old and new Analytics tools; you'll have continuity as you swap out the old integration for the new SDK. However, we don't currently have that continuity for custom events. Today, custom events recorded with Legacy Analytics will only be visible in the Legacy Analytics dashboard and custom events recorded with the new SDK will only be visible in the new Analytics tools.

What is the impact of switching Legacy Analytics off?

Switching off Legacy Analytics means that the legacy backend will no longer receive any events. This also means that the automated standard event import to the new Analytics will stop and only events sent via the SDK or REST API will be collected and be available for analysis in the dashboard. Previously collected data will remain available in the dashboard.

How will the upgrade affect my user IDs?

User IDs from the Legacy Analytics will be used by default by the Analytics SDK where available. You also have the option to set up a custom player ID in Analytics. Read more about this here.

Does Analytics have a raw data export tool?

Analytics introduced a new feature called Data Access which provides access to your Analytics data through Snowflake (a data warehouse). You can leverage the power of Snowflake to view your data through a third-party visualization tool such as Tableau and download your data. To request access to this feature contact support.