Upgrade from Legacy to UGS Analytics

Background

Unity Gaming Services launched in October 2021 - an end-to-end platform with flexible solutions to help you build, manage, and grow your game.

Analytics is a data visualization and dashboard tool that helps you understand and analyze all of your game data. You can use it as a standalone tool (similar to Legacy) or with other UGS products for more functionality. Use Analytics to analyze your games from development to production.

Unity Analytics is free to get started with a generous free tier with pay-as-you-scale afterwards, where you only pay for what you use - see our Analytics pricing.

Learn more about UGS Analytics by taking our Unity Learn course on UGS Analytics.

Get started here.

Impact to me as a Legacy Analytics User

To invest more resources into our UGS Analytics platform, Unity is not investing in Legacy Analytics and has shut down vc access to the dashboard as of June, 2023. New projects are created within the new Unity Gaming Services Analytics platform and we recommend using this guide to migrate existing projects over.

We have made our best efforts to make the transition process as easy as possible for our existing customers by previously providing a data pipeline to ensure that your metrics and KPIs remain stable during the transition. Previously, we provided a data pipeline to ensure the stability of your metrics and KPIs during this process. However, starting from January 31, 2024, this pipeline will cease to deliver new data from the legacy analytics platform to the Unity Cloud Dashboard.

Unity Analytics will maintain 13 months' worth of historical data in accordance with our data retention policy for your reference. To continue analyzing your player data effectively, it's crucial that you integrate the Analytics SDK into your project. We strongly recommend doing this as soon as possible, allowing ample time for your player base to adopt the latest game version. This proactive step will ensure the preservation of as much player data as possible when the legacy data pipeline is phased out. Refer to billing for information on MAU pricing.

Refer to the step-by-step guide below for guidance on installing the Analytics SDK. For more information about the transition, read our FAQ.

Get started with UGS

In the Unity Editor, you need to link your local project build to a Unity Project ID.

  1. Go to Edit > Project Settings > Services.
  2. Log in with your existing credentials.
  3. Select your project from the drop-down list and select Link project ID.

Step 2: Install the UGS Analytics SDK

To install the latest UGS Analytics SDK for Unity, use the latest version of the Unity Editor and follow these steps:

  1. In the Unity Editor, open Window > Package Manager.
  2. In the Package Manager, select the Unity Registry list view.
  3. Search for “Analytics” (not “Analytics Library”) in the list of packages.
  4. Select the package, then select Install.

See the Package Manager documentation.

Refer to SDK initial setup for more details.

When you initialize the UGS Analytics SDK, it automatically sends the newPlayer event the first time the UGS Analytics SDK is run, the gameStarted and clientDevice event each time the game runs, and the gameRunning event every minute. See Standard Events.

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

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

Step 3: Create custom events

Create each Custom Event in the Event Manager to match recorded events:

  1. Go to the Event Manager in the Unity Cloud Dashboard under Analytics.
  2. Create your Custom Event and ensure the name matches.
  3. Create and assign parameters and ensure all parameters are defined to avoid the event being classed as invalid.

Note: Custom Events created in your game code that aren't defined in the Event Manager are considered invalid and won’t track data. These show in the Event Browser.

Step 4: Change Event logging method

Update your game code to record custom events using the "AnalyticsService.Instance.CustomData” method detailed here.

Before

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:

// 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
        AnalyticsService.Instance.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 are 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.