
## What is event tracking?

Sometimes how your players play your game can be a bit of a black box. Unless your players are being vocal about exactly what they're doing on, for example, Discord, you probably don't know how they're interacting with the various parts of your game.

This is where event tracking comes in - you can declaratively choose what to track and when it gets tracked. You could track when a player levels up or when a player completes a level. You can even send extra metadata about that event such as what level they have progressed to.

## Event tracking through Talo

With just one line of code, you can track any event in your game using Talo. The Talo dashboard lets you then see and compare events as well as drill-down into a specific player's events to debug tricky situations. See the [Talo events overview page](https://trytalo.com/events) for more details on how it all works.

You can use Talo in any modern Unity game by simply importing the SDK through the Unity package manager.

![Choose the add package from git url option in the Package Manager](/events/overview.png)

## Setup

Once you've loaded or created a project, go to the package manager (by navigating to `Window > Package Manager`). Click the plus symbol and select "Add package from git url". When prompted, enter the url: `https://github.com/TaloDev/unity-package.git`.

![Choose the add package from git url option in the Package Manager](/blog/event-tracking-unity/package-manager.png)

We've now added the Talo package to our Unity project. Doing this through git allows you to keep Talo up to date without needing to redownload the zip file and importing it.

Next, if you don't already have a `Resources` folder, create one inside the `Assets` folder. This folder allows you to load assets at run-time through code. Inside this folder, right-click and select `Create > Talo > Settings Asset`.

![Create a settings asset inside the Resources folder](/blog/event-tracking-unity/settings-asset.png)

If you click into this Asset, you'll find a number of configuration options. The two important ones are `API url` (which you can change if you're choosing to self-host Talo) and `Access key` which identifies your game. You'll need to create an access key through the Talo dashboard.

### Generating an access key

Visit the [Talo dashboard](https://dashboard.trytalo.com), login or create an account (and confirm your email address). Once logged in, create a new game (if you need to) and visit the Access Keys page.

Choose the scopes available to your access key (you'll need the `read:players`, `write:players` and `write:events` scopes) and create your access key. Copy your newly-generated access key into the `Access key` field on the Settings Asset.

## Identifying the player

We need to know which player is sending events. Let's create a script to do that automatically for us. Start off by creating a new GameObject in your scene and call it something like `Identity Controller`.

Attach a script to the new GameObject, again I'm calling mine `IdentityController`:

```csharp
using UnityEngine;
using TaloGameServices;
using System;

public class IdentityController : MonoBehaviour
{
    private async void Awake()
    {
        var id = PlayerPrefs.GetString("talo-id", Guid.NewGuid().ToString());
        await Talo.Players.Identify("custom", id);
        PlayerPrefs.SetString("talo-id", id);
    }
}
```

We're using Unity's [PlayerPrefs](https://docs.unity3d.com/ScriptReference/PlayerPrefs.html) to load and save a random ID and associate it with that player. PlayerPrefs provides a fallback option in case there's no matching key (`talo-id` in this example). This will happen the first time the player loads the game but going forward we'll use their assigned ID.

To identify a player we need to provide an identity service (this can be Steam, Epic, etc) - in this case we're using `custom` to simply denote the randomised ID.

## Sending event data

Tracking events is incredible easy. All it takes is one line of code:

```csharp
Talo.Events.Track("Cast spell");
```

Since we've identified the player we know this data belongs to them, so all we need to do is pass through the name of the event we want to track.

In the real world you'll usually want to track extra properties with your events. For example, let's track what spells players are casting:

```csharp
using TaloGameServices;

public class PlayerController : MonoBehaviour
{
    public int primarySpellID;
    public int spellLevel;

    private void Update()
    {
        if (Input.GetMouseButtonDown(0))
        {
            CastSpell();
        }
    }

    private void CastSpell()
    {
        // TODO: logic for casting the spell

        Talo.Events.Track(
            "Cast spell",
            ("Spell ID", $"{primarySpellID}"),
            ("Spell level", $"{spellLevel}")
        );
    }
}
```

As you can see, to capture extra event properties we can simply pass in as many string tuples as we like to the `Track()` function.

## Avoiding event tracking pitfalls

The main issues you'll have with event tracking will both stem from not being consistent:

1. Make sure you name your events consistently (for example `(Verb) (object)` - e.g. `Cast spell`)
2. Avoid dynamic event names - for example `Cast [spell name] spell`. Instead, keep your events generic and send a consistent property with the name of the spell.

Additionally, make sure you're only tracking meaningful events so that you don't get overwhelmed when searching through all your game's events. Avoid events that could get sent too often, for example a `Damage taken` event if your game has weapons that rapidly trigger damage effects.

## Conclusion

Event tracking lets you get rid of the guess-work. By tracking important actions when they happen, you're able to gauge how well a mechanic is being used and even track the overall progress of your players. See how often potions get used, items get bought and how many level-ups there are per day, month or year.

Talo lets you seamlessly start tracking events with just one line of code. Using the Talo dashboard you can visualise these events and even see which players are sending them.


Want to know what your players are doing in your game? Use Talo to easily track player events.

Tracking player events and actions in your Unity game


## What is unit testing + why should I do it?

The best way of thinking about unit tests is that they should be designed to test small pieces of your systems in isolation. In Unity, this might be a single script or a helper function.

Unit tests tend to be faster to write since you're focused on one specific piece rather than how individual pieces fit together.

While there's always a time and place for larger end-to-end tests, typically when building a game you'll want to prioritise creating quick tests for complicated logic - most of the time just to sanity-check it.

## What is the Unity Test Framework?

The Unity Test Framework is a convenient test runner built into Unity and based off the popular [NUnit framework](https://nunit.org). Unity Test Framework abstracts away the complicated logic required to build and load your game before tests, allowing you to create Play-mode tests and Edit-mode tests. In this post we'll be focusing on Play-mode tests.

It is available [as a package](https://docs.unity3d.com/Packages/com.unity.test-framework@1.3/manual/index.html) that you can install through the Unity Package Manager.

In this post we'll go over how to use the Unity Test Framework to write good tests. You'll need to setup the test runner and assemblies as [described in the Unity docs](https://docs.unity3d.com/Packages/com.unity.test-framework@1.3/manual/getting-started.html) to get started.

## Your first test

For this post, we'll be looking at [real-world tests](https://github.com/TaloDev/unity/tree/develop/Packages/com.trytalo.talo/Tests/Runtime) we created for Talo to illustrate some of these examples. When you create your first test, you'll have a simple script that looks like this:

```csharp
public class MyFirstTest
{
    // A UnityTest behaves like a coroutine in Play Mode. In Edit Mode you can use
    // `yield return null;` to skip a frame.
    [UnityTest]
    public IEnumerator MyFirstTestWithEnumeratorPasses()
    {
        // Use the Assert class to test conditions.
        // Use yield to skip a frame.
        yield return null;
    }
}
```

As you can see, Unity uses [Coroutines](https://docs.unity3d.com/ScriptReference/Coroutine.html) to run tests. Coroutines are great because they allow you to pause execution and wait for actions to happen before resuming.

The `[UnityTest]` attribute decorates the function to allow us to use these coroutines to skip frames or enter Play-mode.

Lets create a test for the `GetProp` function from the following script:

```csharp
public class LiveConfig
{
    private Prop[] props;

    public LiveConfig(Prop[] props)
    {
        this.props = props;
    }

    public T GetProp<T>(string key, T fallback = default(T))
    {
        try
        {
            Prop prop = props.First((prop) => prop.key == key);
            return ((T)Convert.ChangeType(prop.value, typeof(T)));
        }
        catch (Exception)
        {
            return fallback;
        }
    }
}
```

This function simply uses LINQ to search an array of key/value pairs (`Props`) and find the first one with a matching key. It then converts the value of that `Prop` to match the generic type. If we don't find a `Prop` with that key, we should return the fallback instead.

### Testing the GetProp function

Appropriately, our first test should make sure that the function returns the expected result. Here's what that test would look like:

```csharp
[UnityTest]
public IEnumerator GetProp_WithALiveConfigThatHasValues_ReturnsCorrectValue()
{
    var config = new LiveConfig(new[] { new Prop(("gameName", "Crawle")), new Prop(("halloweenEventEnabled", "True")) });

    Assert.AreEqual("Crawle", config.GetProp("gameName", "No name"));

    yield return null;
}
```

The first thing to note is the structure of the function name. NUnit tests typically have a standardised name made of up of 1) the name of the function you're testing, 2) the condition you're testing and 3) the expected outcome.

We're testing that when the `GetProp` function correctly finds the `Prop` with the key we're searching for when the `LiveConfig` has an array of `Props`. We're doing this because the LINQ `First` function throws when searching an empty array.

By using the `Assert` class, we can compare any number of different outcomes. In this case we're doing a simple equality check. Always remember to `yield return null` at the end of your test, to mark the coroutine as complete.

Luckily for us this function is really small and therefore easy to test. We wrote a few more tests to handle the cases for empty arrays, missing keys, etc. You can find all of those in our [GitHub repo](https://github.com/TaloDev/unity/blob/develop/Packages/com.trytalo.talo/Tests/Runtime/LiveConfig/GetPropTest.cs).

## Handling pre-test setup

In the complicated world of game development it's pretty difficult to write totally isolated code. You'll usually have a number of dependencies that need to be in place before you can properly test what you need to test.

NUnit solves this problem by introducing the `[OneTimeSetUp]` attribute that runs the method it decorates before your tests.

The code below highlights a common scenario where you need some sort of "Manager script" to be ready before executing in the scripts that it manages:

```csharp
public class UpdateSaveTest
{
    private TaloManager tm;

    [OneTimeSetUp]
    public void SetUp()
    {
        tm = new GameObject().AddComponent<TaloManager>();
        tm.settings = ScriptableObject.CreateInstance<TaloSettings>();
    }

    [UnityTest]
    public IEnumerator UpdateSave_InOfflineMode_UpdatesTheSaveName()
    {
        var api = new SavesAPI(tm);
        Talo._saves = api;

        api._allSaves.Add(new GameSave() { id = -1, name = "Offline Save" });
        api.WriteOfflineSavesContent(new OfflineSavesContent(api._allSaves.ToArray()));

        _ = api.UpdateSave(-1, "New Name");

        Assert.AreEqual(1, api.GetOfflineSavesContent().saves.Length);
        Assert.AreEqual("New Name", api.GetOfflineSavesContent().saves[0].name);

        yield return null;
    }
}
```

If you've used Talo (and if you haven't - [you should definitely check it out](https://trytalo.com)), you know that it requires a settings asset. This asset is passed to the `TaloManager` which passes these settings down to individual APIs.

Here, we're testing the `SavesAPI`. We need the `SavesAPI` to have a manager and that's what we're setting up in the `SetUp` function before our test runs.

NUnit has a number of [other convenient attributes](https://docs.nunit.org/articles/nunit/writing-tests/setup-teardown/index.html) like `[SetUp]` that runs before _each_ test and `[TearDown]` that runs after _each_ test to keep your test environment clean and avoid flaky tests.

## Quick tips for writing unit tests

Different people have different thoughts on what makes a good unit test. Sometimes testing feels like uncharted territory in the world of game development, but here are some thoughts about how to go about it:

1. Pick your battles. Some things _just work_ so trying to test everything will inevitably just slow you down. For example, test a weird interaction between two items over a basic 2D movement script.
2. Keep your tests small. In Unity, that usually means testing functions within scripts but maybe not the entire script.
3. Mock as much as possible. Don't re-write code you've already written just for a test, try and find clever workarounds to prevent writing duplicate code.

## Closing thoughts

Unit tests bring a level of confidence you otherwise wouldn't have in a piece of code, however they take time to create and need to be maintained going forward.

This post only scratches the surface on helpful attributes and assertions provided by NUnit and the Unity Test Framework. You can test specific platforms, move from Edit-mode to Play-more and more. Check out the [Unity Test Framework docs](https://docs.unity3d.com/Packages/com.unity.test-framework@1.3/manual/index.html) for additional use-cases.

Testing has sometimes felt a bit abstract in game development and we've only just started the process of adding tests to the [Talo Unity SDK](https://github.com/TaloDev/unity) which you can see in our repo.


Unit tests are a quick and easy way of building confidence in any complicated systems you implement into your game.

Testing your game code with the Unity Test Framework


## What is stat tracking?

Stat tracking involves taking a handful of key metrics in your game and updating them in response to player actions. Stat tracking can be really useful for understanding your players or even for [showing-off recap information](https://i.redd.it/hcnnor7alss61.jpg) in blog posts.

After we've finished doing a game jam, we like to do a wrap-up post focusing on some of the stats from our game. During our most recent jam, we worked on a dystopian farming game where you drive around a modded combine harvester. Your combine harvester can take damage from any angle apart from the left flank, where it has a shield that blocks all damage.

To understand how well players understood the mechanic, we tracked the amount of damage blocked as well as the amount of damage taken. In this post, we'll go over how to do that.

![A combine harvester that can block incoming damage from its left side](/blog/stat-tracking-unity/game.png)

## Stat tracking through Talo

Talo provides an easy way to create stats and view them directly in the dashboard. The stat system provides a number of useful constraints to make sure players aren't attempting to cheat and your code is working as expected.

You can use Talo in any modern Unity game by simply importing the SDK through the Unity package manager.

## Setup

Once you've loaded or created a project, go to the package manager (by navigating to `Window > Package Manager`). Click the plus symbol and select "Add package from git url". When prompted, enter the url: `https://github.com/TaloDev/unity-package.git`.

![Choose the add package from git url option in the Package Manager](/blog/stat-tracking-unity/package-manager.png)

We've now added the Talo package to our Unity project. Doing this through git allows you to keep Talo up to date without needing to redownload the zip file and importing it.

Next, if you don't already have a `Resources` folder, create one inside the `Assets` folder. This folder allows you to load assets at run-time through code. Inside this folder, right-click and select `Create > Talo > Settings Asset`.

![Create a settings asset inside the Resources folder](/blog/stat-tracking-unity/settings-asset.png)

If you click into this Asset, you'll find a number of configuration options. The two important ones are `API url` (which you can change if you're choosing to self-host Talo) and `Access key` which identifies your game. You'll need to create an access key through the Talo dashboard.

### Generating an access key

Visit the [Talo dashboard](https://dashboard.trytalo.com), login or create an account (and confirm your email address). Once logged in, create a new game (if you need to) and visit the Access Keys page.

Choose the scopes available to your access key (you'll need the `read:players`, `write:players`, `read:gameStats` and `write:gameStats` scopes) and create your access key. Copy your newly-generated access key into the `Access key` field on the Settings Asset.

### Creating a stat

To create your new stat visit the [Stats page](https://dashboard.trytalo.com/stats) in the dashboard. You can also access it from the `Services` dropdown. Configure your stat however you like but keep note of your chosen `Internal name` since you'll need this to track your stat.

## Identifying the player

We need to know which player to associate with which stat change. Let's create a script to do that automatically for us. Start off by creating a new GameObject in your scene and call it something like `Identity Controller`.

Attach a script to the new GameObject, again I'm calling mine `IdentityController`:

```csharp
using UnityEngine;
using TaloGameServices;
using System;

public class IdentityController : MonoBehaviour
{
    private async void Awake()
    {
        var id = PlayerPrefs.GetString("talo-id", Guid.NewGuid().ToString());
        await Talo.Players.Identify("custom", id);
        PlayerPrefs.SetString("talo-id", id);
    }
}
```

We're using Unity's [PlayerPrefs](https://docs.unity3d.com/ScriptReference/PlayerPrefs.html) to load and save a random ID and associate it with that player. PlayerPrefs provides a fallback option in case there's no matching key (`talo-id` in this example). This will happen the first time the player loads the game but going forward we'll use their assigned ID.

To identify a player we need to provide an identity service (this can be Steam, Epic, etc) - in this case we're using `custom` to simply denote the randomised ID.

## Incrementing stat(s)

Earlier I mentioned I wanted to track two things:

1. Damage blocked by players (with an `Internal name` of `damage-blocked`)
2. Damage taken by players (with an `Internal name` of `damage-taken`)

Currently, I've got a bullet script that handles collision events through the `OnTriggerEnter2D` callback:

```csharp
private void OnTriggerEnter2D(Collider2D collision)
{
    if (collision.CompareTag("Cockpit"))
    {
        collision.gameObject.GetComponent<Cockpit>().OnHit();
        Remove();
    else if (collision.CompareTag("Shield"))
    {
        Remove();
    }
}
```

The player in my game is made up of two `BoxColliders`. One is the `Shield` where the player can't take damage and the other is the `Cockpit` where the player can take damage.

Adding stat tracking to this script is really simple and can be done in just 2 lines of code:

```csharp
using TaloGameServices;

private async void OnTriggerEnter2D(Collider2D collision)
{
    if (collision.CompareTag("Cockpit"))
    {
        collision.gameObject.GetComponent<Cockpit>().OnHit();
        Remove();
        await Talo.Stats.Track("damage-taken");
    else if (collision.CompareTag("Shield"))
    {
        Remove();
        await Talo.Stats.Track("damage-blocked");
    }
}
```

Note: we've had to mark this function as `async` since we need to `await` the tracking.

The `Track()` function requires one parameter which is the `Internal name` of your stat. You can optionally provide a second parameter which is the amount to increase/decrease the stat by.

## Conclusion

If you've ever wondered about how many players are performing specific actions, you can use Talo to easily track these actions. With just 1 line of code, we can track any stat and keep it constrainted within the limits you created it with.

Best of all, these stats are easily visible in the dashboard - you can see global stats or inspect players' individual stats too.


Find out how to track stats like the number of levels players have completed on an individual basis or total across your game.

How to start tracking player stats in your Unity game


## The current state of updates

These days there's plenty of ways to update your game, from using SteamPipe to update your game on Steam or Butler to update your game on itch.io.

These tools provide great automation but depend on these updates being delivered to players at the right time or the player needing to download and install the update before progressing.

Plenty of problems come up with these approaches, like needing to check if a player is on the latest version, and if not, providing some UI that prompts them to go and download (or find) the latest version.

On mobile app stores sometimes you need to wait for a review for minor wording changes or to enable a seasonal event. These reviews can take days to finally be completed.

## Live config

Using [live config](/live-config) you can update your game directly from the web. When players open your game, they'll always receive the latest config. You can even keep your config in sync by checking it before players do specific actions.

In this tutorial you'll integrate live config into your Unity game in a few simple steps.

## Setup

You can enable live config in any modern Unity game. For this demo, I've created a project using the Core 2D template - but you can use any template you like.

Once you've loaded your project, go to the package manager (by navigating to `Window > Package Manager`). Click the plus symbol and select "Add package from git url". When prompted, enter the url: `https://github.com/TaloDev/unity-package.git`.

![Choose the add package from git url option in the Package Manager](/blog/live-config-unity/package-manager.png)

We've now added the Talo package to our Unity project. Doing this through git allows you to keep Talo up to date without needing to redownload the zip file and importing it.

Next, if you don't already have a `Resources` folder, create one inside the `Assets` folder. This folder allows you to load assets at run-time through code. Inside this folder, right-click and select `Create > Talo > Settings Asset`.

![Create a settings asset inside the Resources folder](/blog/live-config-unity/settings-asset.png)

If you click into this Asset, you'll find a number of configuration options. The two important ones are `API url` (which you can change if you're choosing to self-host Talo) and `Access key` which identifies your game. You'll need to create an access key through the Talo dashboard.

### Generating an access key

Visit the [Talo dashboard](https://dashboard.trytalo.com), login or create an account (and confirm your email address). Once logged in, create a new game (if you need to) and visit the Access Keys page.

Choose the scopes available to your access key (you'll need the `read:players`, `write:players` and `read:gameConfig` scopes) and create your access key. Copy your newly-generated access key into the `Access key` field on the Settings Asset.

## Setting up the scene

As part of this tutorial we'll be creating a piece of text and using live config to get the latest version of the string. You can apply this pattern to any concept in your game - like checking the max level a player can reach or if a seasonal event is currently enabled.

To start off, right-click your scene hierarchy and select `Create > UI > Text - TextMeshPro`. You will need to import the TextMeshPro assets if you haven't already.

![Create a text game object in the scene](/blog/live-config-unity/create-text.png)

I've centred the text and [moved it to the middle of the screen](/blog/live-config-unity/align-text.gif) to make it easier to see by holding `Shift` to set the pivot and `Alt` (or `Option` on MacOS) to set the position.

Next, add a new script to your Text object - I've named mine `TextLoader`. Open up your new script.

## Querying the live config

The first thing we need to do in our script is import the namespaces we'll be using. Add the following namespaces:

```csharp
using TMPro;
using TaloGameServices;
```

Now we can use functions from the TextMeshPro and Talo namespaces. Here's what we want the script to do:

1. Fetch down the live config for our game
2. Get the value of the string
3. Update the UI to reflect the live config value of our string

Doing this is really easy - all you need to do is update the `Start()` method of the script:

```csharp
async void Start()
{
    var textUI = GetComponent<TextMeshProUGUI>();

    Talo.GameConfig.OnLiveConfigLoaded += (liveConfig) =>
    {
        textUI.text = liveConfig.GetProp("liveString", "Not set!");
    };

    await Talo.GameConfig.Get();
}
```

Live config works on an event-based system - we're subscribing to the `OnLiveConfigLoaded` event to instantly update our game once the config has been fetched. We're then inspecting the config we receive and updating the UI with the string we're looking for (or a fallback - if it isn't set).

Once we've subscribed to the event, we fetch the game config. You'll notice that if you run your game, the UI will say "Not set!" because we haven't created the config property in the Talo dashboard.

## Creating the live config property

To update your config, visit the [Live Config page](https://dashboard.trytalo.com/game-config) in the dashboard. You can also access it from the `Services` dropdown.

Add a new property, name it `liveString` (the same as we've named it in the script), choose what you want your string to be and finally click `Save`.

![Create your property in the dashboard, give it the same name as the key in the script](/blog/live-config-unity/live-config-dashboard.png)

Now when you run your game, you'll see your string directly in your UI. You can update it again in the dashboard and once again your game will always pull in the latest version of the config.

## Polling the live config

The `GameConfig.Get()` method always pulls in the latest version of your config. That means you can check the latest config before a player takes an action or continue to poll for the latest changes:

```csharp
using UnityEngine;
using TaloGameServices;
using TMPro;

public class TextLoader : MonoBehaviour
{
    void Start()
    {
        var textUI = GetComponent<TextMeshProUGUI>();

        Talo.GameConfig.OnLiveConfigLoaded += (liveConfig) =>
        {
            textUI.text = liveConfig.GetProp("liveString", "Not set!");
        };

        InvokeRepeating("GetConfig", 0f, 2f);
    }

    async void GetConfig()
    {
        await Talo.GameConfig.Get();
    }
}
```

Unity's `InvokeRepeating()` calls a method with a delay (that we've set to 0 seconds so it runs instantly) and then every interval after that (which we've set to every 2 seconds). 

## Conclusion

While even the smallest updates have traditionally required new releases, Talo's live config lets your game be reactive to the latest changes without releasing a new update or waiting for that update to be approved by an app store.

With only a few lines of code, you can pull in your game config. You can update that config whenever you need to from the Talo dashboard. [Check out the docs](https://docs.trytalo.com/docs/unity/live-config) to learn more about how live config works.


Learn how to easily update your game without depending on players downloading a new update or app store reviews.

Sign up

Talo Blog

Tracking player events and actions in your Unity game

Testing your game code with the Unity Test Framework

How to start tracking player stats in your Unity game

How to update your Unity game without releasing a new update