UGS Analytics

Got a "Heads up!" warning and you ended up here? Scroll all the way down for your solution.

⚠️ [NOTE] ⚠️

• This page describes the new Unity Gaming Services (UGS) Analytics, which has succeeded the legacy Unity Analytics (UA) in June 2021.
  • If you have made a new project after June 22nd, 2021, you are in the right place; please read on.
  • If you have associated Unity Analytics before that, you may still be able to use the legacy UA, but note that Unity will eventually shut down the legacy system and it is recommended that you migrate to UGS Analytics.
    • For information about how to send legacy Unity Analytics events on Scene changes, refer to this page.

---

⚠️ This feature is currently in BETA! ⚠️

The version that supports this behavior is 1.2.3, and it is a pre-release. Please proceed with caution when using this version as unexpected bugs may pop up.

---

Starting from Version 1.2.3, UniSwitcher supports the new Unity Gaming Services (UGS) Analytics.
With a little bit of coding, you can start recording the "Scene visited" events whenever a Scene transition occurs!

First thing first

This page assumes that you have already fully set up your UGS Analytics. Please refer to the official documentation about how to do that.
Plus, consider the opt-out solution for the users for GDPR/CCPA compliance.

What you need to do

There are several things you need to do in order to send "Scene visited" events to your analytics data.

1️⃣ Register a new Event type in your game dashboard

Go to your project in the UGS dashboard. Navigate to Analytics > Event Manager, and "Add New" event type and property to be used for your "Scene visited" events.

• The property type must be String.

These names will be used later in your BaseScene class, so remember them.

2️⃣ Add new members to the BaseScene extension (1/2)

With the Analytics package, the BaseScene class will get two additional virtual members.

public abstract class BaseScene: IScene {
    public virtual string ScreenVisitEventName => null;
    public virtual string ScreenVisitEventPropertyName => null;
}

You need to override these members in your BaseScene class so that it returns the names you set up at the dashboard.

public class MyScene: BaseScene {
    // Replace "screenVisit" and "screenName" according to your setup.
    public override string ScreenVisitEventName => "screenVisit";
    public override string ScreenVisitEventPropertyName => "screenName";
}

3️⃣ Add new members to the BaseScene extension (2/2)

You also need to implement a new interface, IReportable. This interface introduces one member to your BaseScene class.

public interface IReportable
{
    bool DoNotReport();
}

This method is meant to return true when you don't want to send a 'Scene visited' event even when a transition occurs.

Wait, why...?

Remember, UGS Analytics is only free for a certain amount of events, and after that, you will be charged for events sent. Thus, it is important to prevent unnecessary 'Scene visited' events that may not add much to your analysis for being sent.

How to implement

Here is one way: prepare another method that iterates over scenes that you don't want to report. Here, we assume that you have a static member PauseDialog for your pause dialog scene.
Your DoNotReport implementation should check if the scene is equal to any of those. (*Equality method is implemented, so it is safe to use == directly.)

public class MyScene: BaseScene, IReportable {
    private static IEnumerable<MyScene> NonReportingScenes()
    {
        yield return PauseDialog;
    }
    public bool DoNotReport() {
        // Return true if you do NOT want to send events.
        var self = this;
        return NonReportingScenes().Any(scene => self == scene);
    }
}

4️⃣ Test your 'Scene visited' event

You should now be able to send the 'Scene visited' event. Enter Play Mode and perform Scene transitions. If you did not receive any warnings that start with "Heads up!" in the Console, you have successfully sent the event.
Check if your event is correctly recognized in the UGS dashboard. The events can take 10 minutes to show up.

If you have received a "Heads up!" warning, check if you have followed the previous instructions correctly. The warning message also contains some information about what may be missing.

---

❓ I received a "Heads up!" warning from this plugin, and was sent to this page. What is this?

This plugin can send Analytics events to Unity Gaming Services when Scene transitions occur. You received this message because UniSwitcher detected the "Analytics" package in your Unity project.

⬇️ Choose the headings that best describe your situation, and follow the instructions to get rid of this message. ⬇️

1️⃣ I did not mean to use such analysis; There is currently no plan to integrate analysis events.

In this case, it is best that you remove the "Analytics" package (com.unity.services.analytics) entirely from your Unity project.
Use Package Manager to remove it.

2️⃣ I use UGS Analytics to track other events, but I don't need to record "Scene visited" events.

In this case, you can suppress the "Heads up!" message by overriding this member in your BaseScene class.

public class MyScene: BaseScene {
    // Set this member to true to suppress the message entirely.
    public override bool SuppressEvent => true;
}

3️⃣ I use UGS Analytics to track other events, and I'd like to track "Scene visited" events.

Please follow the instruction above on this page.